Nexsus Documentation

An intelligent data platform where every record carries meaning, keeps a complete history, and enforces its own correctness — so your data can't drift, duplicate, or silently break.

This documentation has two tracks. Business & teams explains what Nexsus does and why you can trust it. Developers explains how to build on it. Start anywhere.

Part 1 — Overview

1. What is Nexsus

In one paragraph. Nexsus is a data platform where every record carries meaning, not just values. You define your data once, and Nexsus stores it, understands it, searches it by meaning, keeps a complete history of every change, and enforces its own correctness. You connect through simple tools — including directly from AI assistants — without managing a database of your own.

Who it's for. Teams who want a system of record that is trustworthy by design, and developers who want to build apps and AI agents on structured, meaning-aware data without standing up and securing their own database.

What makes it different.

  • It understands meaning — semantic search is built in.
  • It never forgets — every version of every record is kept.
  • It polices itself — correctness is enforced inside the platform's own engine, not left to your code.

2. Core ideas in 60 seconds

  • Meaning + structure. Every record is both structured (typed fields) and semantic (searchable by meaning).
  • Nothing is ever lost. Edits create new versions; old ones remain as history.
  • The platform enforces its own correctness. Every write is checked against a set of balance equations before it lands; a write that would break one is rejected, and the failing law is named.
  • You ask, Nexsus does. You describe what you want; Nexsus handles the storage, search, and computation.

Connecting your AI assistant

Nexsus is reached over the open MCP standard (Model Context Protocol), so any MCP-capable assistant — Claude, ChatGPT, Gemini, Claude Desktop and more — can connect to your workspace.

You need one thing: your MCP server URL. It's shown in the Connect section on the homepage (and in your dashboard once you've signed in). Access is authorised with OAuth — you sign in once; you never paste an API key into the chat. A client connects with nothing more than the URL: the standard discovery handshake does the rest.

Steps

  1. Create your workspace — sign up and a private, isolated workspace is provisioned for you (14-day trial, no card).
  2. Add the connector — in your assistant, open the place it manages connectors (often labelled Connectors, MCP servers, or Custom tools) and add a custom MCP server using your Nexsus MCP server URL.
  3. Sign in — when prompted, sign in to Nexsus to authorise the assistant (OAuth).
  4. Work with memory — your assistant can now read, store, search and reason over your workspace, persistently, across every session.

Menu names differ between assistants and versions, but the pattern is always the same: add your MCP server URL, then sign in.

Part 2 — For Business & Teams

3. Why you can trust Nexsus

Integrity by architecture, not by policy. In double-entry accounting, every transaction has two equal and opposite impacts — debits equal credits, and if the books don't balance you know immediately that something is wrong, and where. Nexsus applies that same discipline to everything: your data, your schema, even the vocabulary the system uses to name things.

Underneath every record is a set of balance equations that must hold true at all times. Everything starts from one universal law — the Closure Equation: nothing can point at something that isn't there. Every reference — a record to its model, a field to its definition, a link from a sale to a customer — must resolve to a real, declared row. Every other law is a specialisation of this one, applied to a different layer of the system: identity, schema, structure, data, relationships, catalogues, and audit.

Every single write is validated against the full equation set before it commits. If your write would break a law, it's rejected — and you get back the specific law that failed, not "invalid input." Before any record lands, six independent views of it must all tell the same story; any disagreement, and it's rejected. And all of this is enforced inside the database engine itself — not in application code that a bug, a bypass, or a stray script could skip.

The guarantees we make:

  • Nothing is ever overwritten or deleted. Every change is a new version, with full history; deleting archives, never erases.
  • Every write is verified against the full set of balance equations before it is accepted; inconsistent data is refused at the door, with the failing law named.
  • Your numbers always reconcile. Totals and summaries are recomputed from the source on every change, and independently re-checked.
  • One authoritative "current" version of every record, always.
  • Unique, never-reused identifiers for every record.
  • Search that understands meaning, not just keywords.
  • Honest health reporting. The platform continuously audits that its own protections are standing on every workspace — and a workspace that isn't fully protected doesn't pretend: it reports itself as degraded, honestly, until it is.

Go deeper. The developer video Nexsus Balance Equations — Data Integrity, Guaranteed by Math walks the whole control system in about ten minutes — find it on the Videos page. For the underlying principles, see The Mathematics Behind the Platform.

4. Your data, your control

  • Ownership. Your data is yours. Nexsus stores and protects it; it never repurposes it.
  • No surprises. Because history is preserved, you can always see what changed, when, and what it was before — a complete audit trail.
  • Take your data with you. Your records are readable in full through the same typed tools you use every day; a one-call whole-model export is on the roadmap (see §11).

5. Security & privacy

  • Isolation. Each customer's data is strictly isolated from every other customer's, at the database level. Every OAuth token is scoped to its own workspace.
  • Least privilege. The services that access your data run with the minimum permissions required — never as an all-powerful account.
  • Safe by construction. You and your developers interact through controlled, typed tools — never raw database access — so entire categories of risk (injection, accidental cross-account reads, runaway queries) don't exist on the customer surface.
  • Auditability. Append-only history makes every change traceable, supporting compliance and incident review.

Part 3 — Core Concepts

6. The Nexsus data model

  • Record. One item — a customer, an order, a document. It has fields (its values) and a meaning (so it's searchable).
  • Model. The shape of a kind of record — e.g. an "Order" model with fields like amount, status, order_date. Define a model once; every order follows it.
  • Field. A typed attribute — text, number, date, yes/no, or a reference to another record. Each field's type is enforced (a date field only ever holds a date).
  • Relationship. Records can be linked — an Order to a Customer — so you can navigate connections, not just store flat tables. A link can only join records that exist, and its kind must be a recognised relationship.
  • Versions & history. Editing a record creates a new version; previous versions remain as history. There is always exactly one "current" version.
  • Identity (the Nexsus code). Every record has one identity: a 40-digit Nexsus code, guaranteed unique and well-formed — the same code you see in the dashboard. You use it to reference, link, update, and fetch records; an older version's code still resolves to the record's current version.

7. How Nexsus thinks about data

Structured meaning. Every record is stored both as structured fields and as a meaning representation, so two records can be compared by what they mean, not just by exact text.

Search, three ways: - Semantic search — find by meaning. A search for "termination clause" finds the right document even if it says "ending the agreement." - Exact search — find by the literal text. - Filtered reads — narrow by exact criteria, e.g. records where status = "open", server-side.

You can use any of them, or combine them.

Part 4 — For Developers

8. Getting started

Connect via MCP. Nexsus exposes its typed tools over MCP — the same nexsus_* tools a connected Claude or ChatGPT calls. An AI assistant or your own code connects and calls tools like nexsus_create_model, nexsus_submit_record, nexsus_list_records, nexsus_search, nexsus_calc, and nexsus_link.

Your first record:

nexsus_create_model("Order", fields=[
  { name: "amount",     type: "number" },
  { name: "status",     type: "text"   },
  { name: "order_date", type: "date"   }
])

nexsus_submit_record("Order", { amount: 1200, status: "open", order_date: "2026-02-01" })
→ returns the record's 40-digit Nexsus code

Authentication & scopes. You connect with OAuth (or a workspace API key). Every call is automatically scoped to your workspace — you can only ever see and touch your own data.

9. Working with data

  • Create models — define the shape of your data (nexsus_create_model, nexsus_add_field).
  • Write records — add or update data (nexsus_submit_record, nexsus_update). Writes are validated against the balance equations and versioned automatically.
  • Read & list — fetch records of a model, paginated, with server-side filters, field projection and sorting (nexsus_list_records).
  • Search — semantic or exact (nexsus_search); route a plain-language question to the right model first (nexsus_route_query).
  • Calculations — sums, averages, counts, min/max over a model (nexsus_calc). The computation runs on the server; you get the result.
  • Link records — create relationships between records (nexsus_link, nexsus_unlink).
  • History & health — read a record's version history (nexsus_history); check your workspace (nexsus_health).

10. Querying — the typed query API   🔜 Roadmap

Instead of writing SQL, you send a structured query describing what you want:

{
  "model": "Order",
  "where": [
    { "field": "amount",     "op": ">",  "value": 500 },
    { "field": "order_date", "op": ">=", "value": "2026-01-01" }
  ],
  "order_by": { "field": "order_date", "direction": "desc" },
  "select": ["customer_name", "amount"],
  "limit": 50
}

In plain English: "From my Order model, give me orders over $500 since Jan 1, newest first, just the customer name and amount, up to 50."

Nexsus validates the query, scopes it to your workspace, runs it safely, and returns clean results. You never need database access, table names, or a connection string — and you can't accidentally write an unsafe or cross-account query. (Today, nexsus_list_records already gives you server-side equality filters, field projection, and sorting.)

11. Exporting data   🔜 Roadmap

  • Export a model — returns the whole model in a standard format.
  • Small vs large. Small models return directly; large ones run as a background job that produces a downloadable file when ready.
  • Formats. CSV or JSON.
  • Today: every record is already readable in full via nexsus_list_records (paginated) — the roadmap item is the one-call convenience, not access to your data.

12. Errors & validation — the rejection contract

When a write would break a balance equation, it is rejected with a stable error code naming the law that fired — an API contract, not a mystery 500. Your code, or your AI agent, can read the code and fix the call automatically.

Code What it tells you
P-0001 Delete refused — records are archived, never hard-deleted.
P-0002 The row claims a kind of thing the system doesn't recognise.
P-0004 The link's relationship kind isn't recognised (or contradicts the link itself).
P-0005 The field or record claims membership of a model that doesn't exist.
P-0010 The model's shape doesn't reference real, declared fields.
P-0011 The record fills a column the model never declared.
P-0012 A value isn't in the field's allowed values.
P-0013 A label uses vocabulary that isn't registered.

Alongside the coded rejections, everyday validation errors come back in plain language — e.g. "order_date expects a date, got text." Required fields, field types, allowed values, and valid references are all enforced.

Part 5 — Reference

13. Tool reference

The core tools (the full surface is larger — around fifty — and self-describing over MCP):

Tool Purpose
nexsus_create_model Define a new model (the shape of a kind of record).
nexsus_add_field Add a field to one of your models.
nexsus_submit_record Write a new record to a model.
nexsus_update Update a record (creates a new version).
nexsus_list_records List records of a model — paginated, filterable, sortable.
nexsus_search Find records by meaning or exact text.
nexsus_calc Compute sum / average / count / min / max over a model.
nexsus_link / nexsus_unlink Create or archive a relationship between two records.
nexsus_history A record's full version history.
nexsus_registry Your workspace's map: every model, organised by category.
nexsus_health Workspace status — including whether enforcement is fully active.
query 🔜 Run a typed structured query (see §10).
export 🔜 Export a whole model (see §11).

14. The technology, plainly

None of this is exotic. It's well-understood infrastructure, assembled with discipline:

  • PostgreSQL is the store — battle-tested, transactional, auditable. History is append-only, and the current state is always one query away. Enforcement runs inside the engine itself.
  • Numbers and dates are first-class — not text trapped inside blobs. Aggregations run as plain, fast SQL, and a balance equation guarantees what you aggregate always agrees, provably, with what was recorded.
  • Search is three vectors per record. One is structural — computed deterministically, no AI involved, perfectly reproducible. Two are semantic — 1024-dimension embeddings from Voyage AI's voyage-3-large model (one for the record's summary sentence, one for long-form content), stored and searched with pgvector and HNSW indexes. Exact lookup, structural similarity, and meaning-based search, over the same records.
  • The AI surface is a Model Context Protocol server — the open standard Claude, ChatGPT, and Gemini speak natively. Python, built on FastMCP over the official MCP SDK, speaking JSON-RPC 2.0 over streaming HTTP, with per-customer OAuth and the standard discovery handshake.
  • Docker-deployed on Railway, fully managed, with database-level tenant isolation.

15. Glossary

  • Record — one item of data (a customer, an order, a document).
  • Model — the shape of a kind of record.
  • Field — a typed attribute of a model.
  • Relationship — a link between two records.
  • Version — a point-in-time state of a record; edits add new versions.
  • Nexsus code — a record's 40-digit identity; unique, never reused, and stable across versions (an old version's code resolves to the current one).
  • Balance equation — a law the substrate checks on every write; a write that would break one is rejected with the law named.
  • Semantic search — finding records by meaning rather than exact words.

16. FAQ

  • Can I run SQL? No — you use typed tools (and the typed query API, 🔜), which give you query power safely.
  • Can I get all my data out? Yes — every record is readable in full today via the tools; one-call whole-model export is on the roadmap (🔜).
  • What ID do I use? The record's 40-digit Nexsus code — shown in the dashboard and returned by every write.
  • Is my data isolated from other customers? Yes — strictly, at the database level.
  • What happens to old data when I edit? It's kept as history; there's always one current version.
  • What happens if I try to break the rules? The write is rejected before it lands, and the response names the exact law that failed (see §12).

17. What Nexsus keeps internal (and why that's good for you)

Nexsus publishes its data model, its guarantees, its error contract, and its full developer interface — and deliberately keeps its engine internals proprietary (storage internals, exact algorithms, the enforcement machinery). This is what keeps the platform secure, fast, and stable for everyone, and it's why you get the power of the engine as a service — without having to build, secure, or maintain it yourself.

This documentation describes how to use Nexsus and what it guarantees. It is not a specification of the engine's internal implementation.