← agentdb.run

How it’s built

One engine, one log, one history.

The whole system, subsystem by subsystem — precise names, real semantics, no marketing altitude. Written and maintained by Sam Ginsberg, who built the engine. Numbers on this page: Wave 5 + Clean Sweep · July 2026, each dated and SHA’d in the claims ledger.

WHO'S ASKINGHumans — AgentDB Studio + Assist19 surfaces · copilot proposes, you approve · passkeys + MFAAgents — native MCP · SDKs · REST · GraphQL · CLIsix typed tools · schema:// · one conformance suite, every doorAgentDB Access — the identity & governance planeper-statement authorize · default-deny · sealed credential vault (use ≠ read) · KMS/Vault master keys · per-op auditOne Rust engine — one WAL, one MVCC, one snapshot across every modalityrows (MVCC + OCC) · cold columnar tier (.acs + zstd) · HNSW/DiskANN vectors · BM25 full text · durable graph + traverse()git-like branches · AS OF (LSN · timestamp · branch) · REPLAY OF run_id · eval-gated DEPLOY · blend() · EMBED()cross-modal atomicity proven: relational + vector + full-text + graph + audit in ONE transaction, kill-9 durable (Wave 1)The recordgroup-commit WAL, RPO=0 · audit hash-chain (BLAKE3)signed checkpoints — offline public-key verifyThe evidence spinemodel_calls · decisions · evidenceagent runs + tool calls as durable, queryable objectsThe lake — object storage you ownshared commit log on S3-compatible storage · RPO=0 · fenced remote takeover · per-tenant logs/GC/checkpoints · export/import
Every box is shipped and verified at product HEAD — nothing aspirational is drawn.

The engine

AgentDB is one Rust engine with one write-ahead log (WAL), one MVCC, and one snapshot across every modality. The row store is MVCC with first-committer-wins optimistic concurrency control (OCC); a cold columnar tier (.acs + zstd) takes aged data. Vectors are HNSW and DiskANN/Vamana (recall@10 ≥ 0.95), full text is BM25, and graph edges are durable facts with a native traverse(). All of it commits through one group-commit WAL — every acknowledged write is fsynced first (RPO=0), and the group commit amortises fsync across concurrent writers, which is the entire durable-write moat: the lead over comparators widens where fsync is expensive.

Cross-modal atomicity is proven, not asserted: relational + vector + full-text + graph + audit rows in one transaction, one snapshot, kill-9 durable (Wave 1). The SQL surface is full: joins, window functions, recursive CTEs, correlated subqueries, composite FK/CHECK constraints, 50+ scalar functions.

The record outlives the machine.

The lake program puts the whole commit history on object storage you own — an S3-compatible shared commit log with RPO=0. A machine can die mid-write; a fresh machine attaches the same bucket and continues from the last committed write. Correctness under takeover is a fencing story: exactly one writer holds the pen at a time — a rejected writer’s retries are re-gated on every attempt (the single-writer check happens before any cached lane is reused), and cross-shard commits use presumed-abort two-phase commit over a per-tenant commit-decision log, so a kill -9 at any point of the 2PC either fully commits or fully aborts on recovery. This is deliberately not a distributed OLTP cluster and not multi-region async replication: one writer, fenced takeover, zero committed-write loss.

Backup and DR follow the same shape: online backup with no quiesce, and cold-tier export/import straight to your buckets.

Multi-tenancy

Tenants are isolated at the log: per-tenant WAL lanes, per-tenant garbage collection, and per-tenant checkpoints, with per-tenant limits so one caller cannot starve the rest. Hot tenants can opt into intra-tenant WAL sharding — parallel lanes inside one tenant, with the 2PC machinery above keeping cross-shard writes atomic.

Encryption & key custody

At-rest encryption is AES-256-GCM over WAL, segments, indexes, and individual columns — feature-gated, default-off, claimed as available, never implied always-on. Keys are envelope-wrapped: your master keys live in AWS KMS, HashiCorp Vault, or age, and rotation is online. The same envelope machinery seals the credential vault (below).

The evidence spine

Three durable, queryable object families record what AI did: model_calls · decisions · evidence. Agent runs and tool calls are rows, not log lines; retrievals are recorded with what they returned; prompts are versioned objects with deployment history; evals are durable objects that can gate a deploy. This is what makes REPLAY an engine primitive instead of log archaeology.

AgentDB Access

The built-in identity plane — no external IdP required. Humans: passkey-first WebAuthn, httpOnly sessions, TOTP MFA, Argon2id-hashed single-use recovery codes, session revocation. Agents: scoped keys. Authorization is default-deny with conditions (require_mfa, approved device, IP/hours) checked per statement, and refusals carry structured reasons — into the audit ledger. The credential vault holds provider secrets under envelope encryption with a use-≠-read custody model: agents reference credentials by ID; the server injects them; every AI call relays through /access/relay/:provider with SSE streaming, so the browser never holds the secret. The database gateway adds per-op audit with literal-stripped query fingerprints and export policy (max_result_rows). CSRF on state-changing routes, break-glass CLI recovery, emergency lockdown.

AgentSQL — grammar & semantics

AgentSQL is SQL — a superset, never a proprietary query language. Six verb families SQL never had:

AS OF resolves a read to an exact point of history — by LSN (the engine’s write counter), by wall-clock timestamp, or by branch head — with full snapshot isolation. Branches are git-like: fork, write in isolation, diff, merge; AS OF BRANCH point reads route through the branch head’s snapshot with the ancestry chain, O(chain), not a table scan. REPLAY OF run_id guarantees the query executes against the precise engine state captured when the run started — deterministic, run-scoped, byte-stable. DEPLOY PROMPT 'name:vN' TO PRODUCTION REQUIRE EVAL 'e' PASSED is a reserved statement: production deploys are refused without a passing gate, and ROLLBACK PROMPT reverts the pointer, audited. blend() fuses vector, BM25, and graph proximity into one ranked score in one statement; EMBED() runs in-database embedding through the provider registry. Retrieval is permission-aware in the planner: forbidden rows never reach the ranking.

MCP conformance

The MCP server is native — in the engine’s process, not a bridge. Streamable HTTP and stdio transports; six typed tools (query · explain · vector_knn · full_text_search · blend · audit_log); the live schema as a resource; prompt templates for semantic-search, hybrid-search, and audit-review. Every MCP call runs the identical authorization, audit, and tenancy path SQL runs. All four doors — REST, GraphQL, MCP, SDKs — run one conformance suite.

Verification discipline

Concurrency is loom-model-checked and TSAN-clean. The crash suite kills the engine with real SIGKILL, in the blocking release gate, on every merge — mid-commit, mid-2PC, mid-takeover. A SQLite differential oracle checks query semantics. TPC-C runs hold 12/12 consistency invariants. Benchmarks are symmetric same-machine races with durability modes disclosed on both sides and comparators at best-shot configs — fsync verified with strace on the other side, losses published next to wins. The harness, configs, and competitor pins are public: agentdb-bench-harness.

Authored by Sam Ginsberg. Refreshed each benchmark wave — verdicts change in the claims ledger first. Questions this page doesn’t answer: ask the person who built it.