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, 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. Inconsistent data is rejected before it's stored.
• You ask, Nexsus does. You describe what you want; Nexsus handles the storage, search, and computation.

Part 2 — For Business & Teams

3. Why you can trust Nexsus

Integrity by architecture, not by policy. Most systems promise to keep your data clean. Nexsus makes it a property of the platform itself — correctness rules run inside the engine on every single write, so there is no "we forgot to validate that" path.

The guarantees we make:

• Nothing is ever overwritten or deleted. Every change is a new version, with full history.
• Every write is verified before it is accepted; inconsistent data is refused at the door.
• Your numbers always reconcile. Totals and summaries are recomputed from the source on every change.
• One authoritative "current" version of every record, always.
• Unique, never-reused identifiers for every record.
• Search that understands meaning, not just keywords.

The mathematics behind the platform. For readers who want the depth, a companion page lays out the well-established mathematical principles Nexsus is built on — in plain language, with examples. (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.
• Export anytime. You can extract any model — or your entire dataset — whenever you want, in standard formats. No lock-in. (See §11.)
• No surprises. Because history is preserved, you can always see what changed, when, and what it was before — a complete audit trail.

5. Security & privacy

• Isolation. Each customer's data is strictly isolated from every other customer's.
• 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.
• Versions & history. Editing a record creates a new version; previous versions remain as history. There is always exactly one "current" version.
• Identifier (hexacode). Every record has a stable, opaque public ID — a hexacode, e.g. a1b2c3d4e5f6. You use hexacodes to reference, link, and fetch records.

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, two ways: - Semantic search — find by meaning. A search for "termination clause" finds the right document even if it says "ending the agreement." - Filtered search — find by exact criteria, e.g. amount > 500 AND status = "open".

You can use either, or both together.

Part 4 — For Developers

8. Getting started

Connect via MCP. Nexsus exposes a set of typed tools over MCP. An AI assistant or your own code connects and calls tools like create_model, submit_record, list_records, search, calc, and link.

Your first record:

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

submit_record("Order", { amount: 1200, status: "open", order_date: "2026-02-01" })
→ returns a hexacode, e.g. "a1b2c3d4e5f6"

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

9. Working with data

• Create models — define the shape of your data (create_model).
• Write records — add or update data (submit_record, update). Writes are validated and versioned automatically.
• Read & list — fetch records of a model, paginated (list_records). This is how you read an entire model today.
• Search — semantic and/or filtered (search).
• Calculations — sums, averages, counts, min/max over a model (calc). The computation runs on the server; you get the result.
• Link records — create relationships between records (link).

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 account, runs it safely, and returns clean results — with hexacodes, never internal codes:

{
  "records": [
    { "id": "a1b2c3d4e5f6", "customer_name": "Acme Pty Ltd", "amount": 1200 }
  ],
  "total": 1
}

You never need database access, table names, or a connection string — and you can't accidentally write an unsafe or cross-account query. You get the power of querying; Nexsus owns the execution.

11. Exporting data   🔜 Roadmap

• Export a model — export("Order") returns the whole model, sanitized (names + hexacodes).
• Small vs large. Small models return directly; large ones run as a background job that produces a downloadable file when ready — like "Export to CSV" in your email or spreadsheet.
• Formats. CSV or JSON.

12. Errors & validation

• Clear errors. When a write is rejected, you get a plain-language reason — e.g. "order_date expects a date, got text."
• Common rules. Required fields, field types, allowed values (enums), and valid references are all enforced.
• Self-correcting agents. Because errors are explicit and machine-readable, AI agents can read the reason and fix the call automatically.

Part 5 — Reference

13. Tool reference

Each tool has its own entry — purpose, inputs, outputs, an example, and the errors it can return:

14. Query & operator reference   🔜 Roadmap

The operators allowed in a where clause — the entire query language in one table:

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.
• Hexacode — a record's stable, opaque public identifier.
• 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 — export any model or your whole dataset, anytime (🔜).
• What ID do I use? The hexacode.
• Is my data isolated from other customers? Yes, strictly.
• What happens to old data when I edit? It's kept as history; there's always one current version.

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

Nexsus publishes its data model, its guarantees, and its full developer interface — and deliberately keeps its engine internals proprietary (storage internals, exact algorithms, the enforcement engine). 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.