Zyrn — an AI-native database.

§0Manifesto moved from repo, lives here now

Every fact is also its own provenance, and AI is the operator.

Zyrn is a database where the operator is AI. Not a SQL engine with an "AI assistant" stapled on. Not a vector store with metadata bolted to it. Not a knowledge graph with a chat interface. A database whose entire API surface, fact model, indexing strategy, and audit guarantees are designed end-to-end for AI as the primary user. Humans live at the chat surface and never write a query.

Zyrn stores facts. A fact is an immutable typed record with mandatory provenance — source_hash, parser_id, ingest_ts, byte range. Every fact knows where it came from, who parsed it, when, and with which version. There is no UPDATE. There is no DELETE. Corrections supersede; the past is never overwritten.

AI talks to Zyrn through typed tool calls — ingest, retrieve, aggregate, relate, traverse, rank, trace, supersede. There is no query language for the LLM to emit incorrectly, because there is no language. Tool signatures are the API. New capabilities are new tools, not extensions to a grammar.

Retrieval is deterministic. Filters first; vector ranking only within the filtered candidate set. The five-stack of lossy conversions that wrecks RAG accuracy (PDF → text → chunks → embeddings → cosine → LLM) is replaced by parse-once-store-as-facts plus exact-match indexes the system maintains itself. The vector layer is demoted from retriever to ranker.

Aggregations are computed by Zyrn, not by the LLM. Sums, counts, joins, averages — code does math. The LLM narrates the result. The LLM is at the edges: parsing on the way in, narrating on the way out. The core is exact.

Zyrn commits to two accuracy classes and never blurs them. Class A (factual: counts, sums, filters, joins, substring search) carries a 100% guarantee. Class B (interpretive: summaries, judgments) returns AI best-effort with full provenance. The user sees which is which.

binary doc  →  AI parse  →  fact log  →  typed tool call  →  deterministic result  →  AI narrate  →  chat

That's the loop. AI lives at parse-in and narrate-out. The middle is code.

Why this exists

For sixty years databases have been designed for human DBAs. SQL is a 1974 design for humans typing at terminals. Schemas declared upfront. Migrations to change them. DBAs hand-tuning indexes. Foreign keys to remember relationships. INSERT/UPDATE/DELETE because humans like editing data.

When AI talks to these systems, the LLM is the only AI in a stack of seven human layers: database design, schema, query language, indexing strategy, ETL, application code, UI. The LLM spends every query translating across all of them. The cumulative tax of that translation is what people call "RAG accuracy problems."

The fix is not a better query language. The fix is not a better chunking strategy. The fix is not a better embedding model. The fix is to remove the human layers entirely. The database itself must be AI-native — designed end-to-end for AI as the primary operator.

In 2026, AI can author idiomatic database operations more fluently than most humans. What's missing is a database that doesn't force AI to translate to human conventions first. Zyrn is built on the bet that storage designed for AI is the missing layer of the AI-native stack.

Note: this manifesto used to live in the repo as MANIFESTO.md. As of v3.2.0 it lives here on the marketing site. The repo carries only operator/developer material. AI agents read no markdown — they fetch GET /kb from a running server for their full operational model. Two surfaces, zero overlap.

§1Overview

What it is

Zyrn is a database designed around AI as the operator, not human as the query writer. There is no SQL surface for AI. There is no schema migration ritual. There is no separate vector database. Every piece of information — structured rows, unstructured documents, conversation memory, document extractions — becomes a typed fact with mandatory provenance.

Three things that are different

What this is NOT

• Not a vector database. Vectors are rankers; they never decide truth.
• Not a graph database. Relations exist but the primitive is the fact.
• Not an LLM. The LLM is a client. Zyrn is the substrate.
• Not a SQL replacement for humans. Humans use the read-only console; AI uses the typed tools; nobody writes SQL against the fact store.

§2Install

One-line install (Linux + macOS, x86_64 + aarch64)

curl -fsSL https://raw.githubusercontent.com/shammyali/zyrn/main/install.sh | bash

Installs the zyrn binary to ~/.local/bin. Override with ZYRN_INSTALL_DIR=/usr/local/bin for system-wide.

Docker

docker run -p 7878:7878 -v $PWD/data:/data \
  -e ZYRN_AUTH_TOKEN=$(openssl rand -hex 32) \
  ghcr.io/shammyali/zyrn:latest

From source

cargo install --git https://github.com/shammyali/zyrn --features http_server

First run

# 1. Generate auth token
export ZYRN_AUTH_TOKEN=$(openssl rand -hex 32)

# 2. Start the server
zyrn serve ~/zyrn.duckdb 127.0.0.1:7878

# 3. Verify it's responding
curl -s http://127.0.0.1:7878/health
# → {"status":"ok","version":"3.0.0"}

# 4. Audit integrity at any time
zyrn verify ~/zyrn.duckdb

System requirements

§3The 7 determinism invariants

These are theorems, not features. Each one has code, tests, and audit paths behind it. Together they are the bank-grade contract. Full spec lives in DETERMINISM.md.

§4MCP tool reference

Zyrn exposes 21 typed JSON-RPC 2.0 tools over the MCP standard. AI agents call them by name. Full JSON Schema for each tool is returned by tools/list.

Core fact operations

Introspection

Vision + outbox + math

HTTP endpoints (non-MCP)

§5Architecture

Fact shape

The atomic unit. Every record in the store is a fact.

{
  "id": "26c25a0d-2576-4a34-9c90-7f98680e83e2",
  "fact_type": "claim",
  "schema_version": 1,
  "fields": {
    "claim_number": "CL-2026-001",
    "amount": 85000,
    "currency": "AED",
    "agent_id": "agent_142"
  },
  "source_path": "praktora:UV_ACL_Claim/CL-2026-001",
  "source_hash": "9d2b3...",
  "parser_id": "praktora_v1",
  "content_hash": "bc107...",
  "ingest_ts": "2026-05-22T08:49:34Z",
  "valid_from": "2026-01-15",
  "valid_until": null,
  "supersedes": null
}

Component map

The stack

Logos defines AI-native operations. Zyrn stores the facts those operations consume and produce. Voxa is the application surface. Together: the AI-native stack.

§6For AI agents reading this

You may be an AI deciding how to use Zyrn. Below is the contract.

Example: ingest claims via MCP

POST /mcp
Authorization: Bearer $ZYRN_AUTH_TOKEN
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "ingest",
    "arguments": {
      "parser_id": "json_lines_v1",
      "source_bytes_b64": "...base64 of NDJSON...",
      "source_path": "praktora:customer-extract/CS20"
    }
  }
}

Example: aggregate with provenance

{
  "name": "aggregate",
  "arguments": {
    "query": { "fact_type": "claim", "field_equals": [["agent_id","agent_142"]] },
    "op": "sum",
    "field": "amount"
  }
}

// → response includes derived_from naming the exact facts
{
  "op": "sum",
  "field": "amount",
  "value": 127000.00,
  "n": 2,
  "derived_from": ["26c25a0d-...", "6edebf38-..."]
}

§7The Protocol v1.0 · enforced since v3.1.1

The protocol is not a request for AI to be well-behaved. It's a description of what the substrate refuses to do.

Compliance is not a function of model strength or goodwill — it's a function of the API surface, schema validators, content-hash gates, and audit emissions that the substrate runs on every call. A strong AI honors the protocol and the enforcement machinery is dormant. A weak or hostile AI tries to violate it and the substrate refuses, emitting a contract_violation audit fact. Either way, behavior is bounded by the substrate, not the agent.

The 9 laws

Enforcement classification

Five of nine laws are structurally unbreakable — the violation path does not exist in code, regardless of which AI is on the other side. The handshake itself is now mandatory (v3.1.1) — strict mode is the default and every tool call except the bootstrap requires a valid session, with every refusal emitting an audit fact.

Handshake — how an AI acknowledges the protocol

Acknowledgment is not free-form text. It's a content-addressed hash echo. The AI fetches the canonical protocol bytes, computes their SHA-256, and sends that hash back via MCP. If the hashes don't match, the substrate refuses to open a session.

// 1. Fetch the canonical protocol text. Always open, no auth needed.
GET /protocol
// → { protocol_version: "1.0",
//     protocol_hash:    "4e93f5b9da60b47819cfaf3290600ea579622df66aae970a0cc055a4a252850a",
//     protocol_text:    "THE ZYRN PROTOCOL v1.0\n...",
//     handshake_mode:   "optional" }

// 2. Echo the hash via the MCP tool zyrn_protocol_v1 (listed FIRST in tools/list).
POST /mcp
Authorization: Bearer $ZYRN_AUTH_TOKEN
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "zyrn_protocol_v1",
    "arguments": {
      "agent_key":     "your-stable-identifier",
      "protocol_hash": "<sha-256 from step 1>"
    }
  }
}
// → { status: "accepted",
//     session_id:           "zyrn_sess_...",
//     idle_ttl_seconds:     300,
//     absolute_ttl_seconds: 3600,
//     protocol_version:     "1.0" }

// 3. Send the session_id on every subsequent call via the
//    X-Zyrn-Session header. Required in strict mode (the default).
POST /mcp
Authorization: Bearer $ZYRN_AUTH_TOKEN
X-Zyrn-Session: zyrn_sess_...
{ "jsonrpc": "2.0", "id": 2, "method": "tools/call", ... }

Handshake modes — operator-configured

Session lifecycle

Consequences of violation

Why this design

Markdown is descriptive. JSON Schema is structural. Neither is binding. An AI client can read tool descriptions and interpret them differently than the substrate enforces them — that gap is where weak AIs fail and where attacks live. The Zyrn Protocol closes the gap on the substrate side:

1. Forbidden operations are physically impossible (no UPDATE tool exists).
2. Required fields are validated at request parse, before any storage.
3. The protocol text is hashed; clients must echo the hash to open a session.
4. Every privileged action is audited so violations are post-hoc detectable.

Roadmap — protocol as a Logos program (v4.0)

In v4.0 the protocol becomes a Logos program. The .logos source is the source of truth. The Rust binary embeds the compiled-Logos verifier. The markdown rendering is generated from the source. The substrate's tool dispatcher calls into the Logos verifier on every operation.

contract append_fact(session: linear Session, fact: Fact) -> linear Session
  effect Cap
  effect Database
  requires session.expires_at > now()
  requires fact.source_path != ""
  requires fact.source_hash != ""
  requires fact.parser_id in trusted_parsers()
  requires canonical_hash(fact) == fact.content_hash
  ensures  audit_emit("fact_appended", fact.id, session.agent_key)
  on_violation: emit("contract_violation", session.agent_key, reason)
                 -> revoke_session(session.id)

The Logos compiler proves requires/ensures hold or refuses to compile. The verifier runs at every call boundary. The substrate cannot ship a tool whose contract violates the protocol because the binary won't link. The verifier is the protocol. The protocol is the verifier. No drift is possible.

Full text: docs/PROTOCOL.md · canonical bytes: PROTOCOL_V1_TEXT · live endpoint: GET /protocol on any Zyrn instance.

§8Ecosystem

Nine sibling crates, same family, same doctrine. All Apache-2.0, all public.

§9FAQ

§10Documentation

Full documentation lives in the repo. The most important documents: