Introduction
What is SapixDB?
SapixDB is a new kind of database — built from the ground up for a world where AI agents are the primary consumers and producers of data.
In a traditional database, data sits passively in tables waiting to be queried. In SapixDB, each data domain is owned by a living AI agent with its own identity, its own cryptographic keys, and its own semantic understanding of its data. Every record it writes is cryptographically signed, hashed, and chain-linked to the record before it — forming an unforgeable, time-ordered strand. And when the data model needs to change, a Mutant agent proposes the change, tests it, and waits for a human administrator to approve before anything touches production.
The result is a database that thinks, evolves, and carries its own trust — not as features bolted on top, but as structural properties of how data is stored.
Why SapixDB
The Problem with Existing Databases
Modern databases were designed for a different era — one where humans wrote queries, schemas were defined upfront, and trust was handled by a policy document nobody read. That era is over.
Today, AI agents query, write, and reason about data continuously. They need to know not just what the data says, but who wrote it, when, and whether it can be trusted. They need schemas that grow alongside new discoveries, not ones that require a migration ticket and three weeks of planning.
No structural trust
Traditional databases have no built-in way to prove who wrote a record or whether it was tampered with after the fact. With AI agents writing data autonomously, this is a fundamental problem.
No lineage by default
Answering "why does this record exist and what led to it?" requires expensive external tooling. In SapixDB, lineage is baked into every write — it's the chain itself.
Schema rigidity
Every new data requirement triggers a migration. DBAs, scripts, rollback plans. In an agent-driven world where relationships are discovered dynamically, this kills velocity.
AI is bolted on
Making a traditional database agent-ready requires custom RAG pipelines, vector stores, semantic layers — built separately and maintained forever. SapixDB is agent-native from the storage layer up.
Governance as afterthought
Compliance (HIPAA, SOX) is typically a middleware concern. In SapixDB it is structural — PHI fields are classified at write time, dual-admin requirements are enforced at the storage level.
SapixDB doesn't add features to fix these problems. It eliminates them by design.
Core Concepts
How SapixDB Thinks About Data
SapixDB is built on a biological metaphor that maps one-to-one to real engineering primitives. Understanding these six concepts is all you need to get started.
🔬Nucleotide (Record)
The smallest unit of data. A nucleotide is a single signed, immutable record — identified by a UUID, hashed with BLAKE3, signed by its owning agent, and linked to the record before it. Records are never updated in place. They are appended, superseded, or tombstoned. The hash is the identity.
🧬Strand
Every agent owns one strand — an append-only hash-linked chain of all its nucleotides. The strand is the source of truth. Because each record points to its predecessor by hash, the entire history of an agent's data is always queryable and tamper-evident. You can ask “what did this look like at 3pm Tuesday?” and get a cryptographically verifiable answer.
🤖Agent (Gene)
An agent is both the data owner and the data steward. Each agent holds an Ed25519 keypair — its private key never leaves the process. All records it writes are signed with that key. Agents communicate peer-to-peer via the mesh protocol, replicate data to each other automatically, and answer queries in natural language via SaQL.
📊Graph
Relationships between records and agents are first-class graph edges — typed, weighted, and traversable. You can ask “give me all records of type X connected to agent Y within 2 hops” across your entire cluster in a single call. No join tables. No foreign keys.
🗣️SaQL — Semantic Agent Query Language
SaQL lets you query in natural language. Instead of SQL, you express a goal: latest 10 records where status = active or records from the last 24 hours. SaQL translates these into precise strand traversals. No schema knowledge required from the caller.
⚙️Mutant (Governed Evolution)
When the data model needs to change, a Mutant agent proposes the change, describes the rationale, and waits. A human administrator reviews and approves. Only then does the change apply — and the entire approval chain is recorded in the strand forever. No migration scripts. No surprise schema changes in production.
🔐Codios (Authorization)
Codios is the agent contract security layer from Midlantics. When configured, SapixDB calls Codios before every write and read — Codios decides whether the operation is permitted. Each authorization check carries the agent identity, the operation type, and the resource path. A 403 from Codios blocks the operation entirely. Without Codios, SapixDB runs in open mode — appropriate for local development.
📡A2A (Observability)
A2A is the Midlantics observability and governance layer. SapixDB emits a structured audit event to A2A after every write — genesis, records, blobs, graph edges, applied mutations. Events are fire-and-forget (A2A failure never delays or rolls back a write) and appear in the A2A dashboard alongside traces from BOBOYKA agents, giving you a unified view of all agent activity across the entire platform.
Quickstart
Spin Up Your First Agent
SapixDB runs as a single process on one port (7475) and serves all your agents — just like a traditional database serves all its tables through one connection. Start with one agent and add more domains using _typefields in your records. Here's everything you need to get started.
1. Generate your keypair seed
Every agent has a permanent Ed25519 identity. Generate a secret seed once and save it — this is the agent's private key and must never change:
Request
# Run once — save the output somewhere safe
python3 -c "import secrets; print(secrets.token_hex(32))"
# → a3f8c201b7e94d0f2c6a1b3e5d7f9a0c... (64 hex chars)
2. Start the agent
Pass the seed alongside your agent identity and data directory:
Request
SAPIX_AGENT_ID=my-agent \
SAPIX_KEYPAIR_SEED_HEX=<your-64-char-hex> \
SAPIX_STRAND_DIR=./data \
SAPIX_PORT=7475 \
# Optional: Codios authorization (see docs/manual#codios)
# SAPIX_CODIOS_URL=https://codios-api.midlantics.com
# SAPIX_CODIOS_API_KEY=codios_sk_...
# Optional: A2A audit trail (see docs/manual#a2a)
# SAPIX_A2A_URL=https://a2a-api.midlantics.com
# SAPIX_A2A_API_KEY=a2a_sk_...
sapix-agent
The agent derives its Ed25519 keypair from the seed on every boot — identity is stable as long as the seed stays the same. Every record written to the strand is signed with this keypair and the signature is verifiable forever.
3. Initialize the strand
Every agent starts with a genesis record — the root of its chain:
Request
POST /v1/genesis
{
"agent_id": "my-agent",
"description": "Customer data agent for Acme Corp"
}Response
{
"record_id": "019...",
"hash": "3a7f...",
"parent_hash": null,
"sequence": 0
}The genesis record is the only record with a null parent_hash. Every subsequent write will chain from here.
Writing Data
Appending Records to the Strand
You write data by appending a record. The payload is your data as a JSON object — SapixDB encodes it as MessagePack internally and signs the block before storing it.
Request
POST /v1/records
{
"payload": {
"type": "customer",
"name": "Lena Fischer",
"email": "[email protected]",
"plan": "enterprise"
}
}Response
{
"record_id": "019...",
"hash": "7c2a...",
"parent_hash": "3a7f...",
"sequence": 1,
"signed_by": "my-agent",
"timestamp_hlc": 1748736000000
}Every response includes the hash of the new record, the hash of its parent, and the agent that signed it. This receipt is all you need to verify the chain at any future point in time.
Superseding a record
Records are immutable — you never update them. Instead you write a new record that supersedes the old one. The previous record stays in the chain forever:
Request
POST /v1/records
{
"payload": {
"type": "customer",
"name": "Lena Fischer",
"email": "[email protected]",
"plan": "enterprise"
},
"supersedes": "7c2a..."
}The original record is still there. Time travel is always available — see the Querying section below.
Tombstoning (logical delete)
Request
POST /v1/records
{
"payload": { "type": "customer", "id": "019..." },
"flags": 2
}flags: 2 writes a TOMBSTONE record. The data is not physically deleted — it is logically marked as removed. The chain is never truncated.
Querying Data
Asking Questions in Plain Language
SapixDB ships with SaQL — a semantic query layer that accepts natural language goals and translates them into precise strand operations. No SQL. No schema required.
SaQL queries
Request
POST /v1/query
{ "query": "latest 10 records" }Request
POST /v1/query
{ "query": "records from the last 24 hours" }Request
POST /v1/query
{ "query": "record with hash 7c2a..." }Time travel
Because every record is hash-linked with a Hybrid Logical Clock timestamp, you can query the exact state of any agent's data at any point in the past:
Request
GET /v1/strand/as-of?ts=2026-05-01T15:30:00Z
Response
{
"as_of_ts": 1746113400000,
"records": [
{
"hash": "7c2a...",
"payload": { "name": "Lena Fischer", "plan": "enterprise" },
"signed_by": "my-agent",
"valid_from": 1746100000000,
"valid_until": null
}
]
}The response reflects the state of the strand as it existed at that exact timestamp. No backups. No snapshots. The chain is the time machine.
Reading the chain head
Request
GET /v1/strand/head
Response
{
"head_hash": "9e1b...",
"sequence": 42,
"agent_id": "my-agent",
"timestamp_hlc": 1748736001337
}
Agents & Graph
Connecting Agents and Traversing Relationships
Registering a peer agent
Agents discover each other through the mesh. Once registered, writes to one agent fan out to all peers automatically:
Request
POST /v1/mesh/peers
{
"agent_id": "inventory-agent",
"endpoint": "http://10.0.0.2:7475"
}Creating a relationship
Request
POST /v1/graph/edges
{
"src": "my-agent",
"dst": "inventory-agent",
"edge_type": "manages",
"weight": 1.0
}Traversing the graph across agents
A single traversal call performs BFS across your entire cluster, crossing node boundaries automatically:
Request
GET /v1/graph/traverse?depth=2&edge_type=manages
Response
{
"start_agent": "my-agent",
"agents_visited": ["my-agent", "inventory-agent"],
"edges": [
{
"src": "my-agent",
"dst": "inventory-agent",
"edge_type": "manages",
"across_peer": true,
"peer_endpoint": "http://10.0.0.2:7475"
}
],
"depth_reached": 1
}
Authorization & Observability
Codios + A2A — Security and Audit at the Data Layer
SapixDB integrates with two Midlantics platform services that every production deployment should use: Codios for per-operation authorization and A2A for audit trail and observability. Both are optional — omitting them runs the agent in open mode, which is safe for local development.
Codios — authorize every operation
Get your API key from codios.midlantics.com → Settings → API Keys, then add two env vars:
docker-compose.yml / environment
SAPIX_CODIOS_URL: "https://codios-api.midlantics.com"
SAPIX_CODIOS_API_KEY: "codios_sk_..." # from your Codios dashboard
SapixDB then calls POST /authorize on Codios before every write and read, sending the agent ID, operation type, and resource path. A 200 proceeds; a 403 blocks the operation and returns an error to the caller. Set SAPIX_REQUIRE_CODIOS=true to make Codios mandatory — the agent refuses to start without it.
A2A — emit an audit event on every write
Get your API key from a2a.midlantics.com → Settings → API Keys, then add two env vars:
docker-compose.yml / environment
SAPIX_A2A_URL: "https://a2a-api.midlantics.com"
SAPIX_A2A_API_KEY: "a2a_sk_..." # from your A2A dashboard
After every successful write, SapixDB fires a structured event to A2A in the background — the write response is never delayed. Events include the agent ID, event type (genesis, write, blob_write, graph_write, mutation_applied), record ID, and timestamp. They appear in the A2A dashboard alongside BOBOYKA agent traces.
See Manual § 2c and Manual § 2d for full configuration reference including the authorization request format and monitoring endpoints.
Compliance
HIPAA and SOX — Structural, Not Bolt-On
HIPAA — PHI field classification
Declare which fields contain Protected Health Information. SapixDB will enforce access controls and log every read automatically:
Request
POST /v1/hipaa/phi-fields
{
"field_name": "email",
"classification": "PHI",
"reason": "email is a direct patient identifier under HIPAA §164.514"
}Every read of a PHI field is logged with the requesting agent identity and timestamp. A full audit report is always available at GET /v1/hipaa/audit-report.
SOX — Dual-admin sign-off
Designate an agent as a financial (SOX Tier 1) agent. Any proposed schema change targeting that agent will require two distinct administrators to approve before it applies:
Request
POST /v1/sox/designate
{
"agent_id": "revenue-agent",
"designated_by": "[email protected]",
"reason": "owns financial transaction records"
}The dual-sign requirement is enforced structurally — a single admin approval returns 403 regardless of permissions. There is no way around it.
What's Next
SapixDB is generally available
SapixDB is production-ready and open to everyone. Community is free forever. A 30-day free trial gives you the full Enterprise feature set — no credit card required. Paid plans add higher limits, replication, and priority support.
SapixDB is built for teams where:
- Provable data lineage is a requirement, not a nice-to-have
- AI agents need to own and understand their own data
- Compliance must be structural, not procedural
- Schemas evolve without migrations
- The database scales by cell division, not by sharding
Start free and scale when ready.
Get started in minutes
Pull the Docker image, drop in your license key, and you are live. The 30-day free trial unlocks the full Enterprise feature set — no credit card needed.
