Zyrn — an AI-native database.

§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 · shipped v3.1.0

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

Six of nine laws are structurally unbreakable — no amount of model cleverness changes the outcome because the violation path does not exist in code.

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. Use session_id on subsequent calls (strict mode). Refresh by activity.

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: