One memory substrate, from a single agent to a federated hive.
The same Rust binary, the same schema and the same three surfaces (MCP, HTTP, CLI) run on a laptop, behind a shared daemon, across a quorum-replicated cluster and on a PostgreSQL tier. What changes from tier to tier is topology, the consistency model and the trust boundary. New in v1.0.0: the wake plane, which pushes a content-free hint the moment a message lands, so agents stop sleeping between inbox polls.
ai-memory inside an agent hive.
Each host runs its agents, one ai-memory daemon, one same-host wake hub and one store. Hosts meet only through federation: a mutually-authenticated, Ed25519-signed push mesh with W-of-N quorum writes and a catch-up pull for peers that were away. Host A runs an MCP agent whose ai-memory mcp child opens SQLite in-process; host B runs the CLI, which also opens the store in-process (it is not a thin HTTP client); host C keeps its data in PostgreSQL, which agent traffic reaches only through its daemon. Every daemon listener is TLS, loopback included.
Read it top-down. Agents reach the daemon over HTTPS or spawn a local process; the daemon resolves identity, applies governance and writes the store; a committed message publishes a wake to the local hub; the federation riser replicates the write to the other hosts. Sources: src/daemon_runtime.rs, src/mcp/mod.rs, src/federation/sync.rs, src/wake_hub/server.rs.
Three surfaces, one engine, two backends.
MCP serves a named profile: core (the store, recall, list, get, search, load-family and smart-load tools, plus the always-on memory_capabilities bootstrap), graph, admin, power or full, or a comma-separated mix of profiles and tool families. HTTPS serves every route under /api/v1/: the daemon refuses to listen without TLS on any bind, loopback included; a single-operator install mints and renews a local CA certificate, and every fleet shape brings its own. The CLI exposes the same operations as verbs. All three resolve an agent identity and pass the same per-namespace governance gate before the engine touches storage.
Backend parity, stated exactly. On PostgreSQL every request still terminates at the daemon: postgres_route_gate serves 76 of the 89 unique paths and answers the rest with a uniform 501 NOT IMPLEMENTED rather than ever touching the wrong database. serve and curator run against PostgreSQL; the tenant-facing CLI read/write verbs and MCP over stdio are SQLite-only; the admin verbs schema-init, keys, reown, verify-audit-trail, agents bind-api-key, identity hub-cache and doctor take a per-run --store-url target. Sources: src/handlers/postgres_gate.rs, src/profile.rs, src/transit_encryption.rs, src/daemon_runtime.rs.
short · mid · long
Every memory carries a tier. Short expires after hours, mid after days, long never; recall boosts and promotion move memories up. TTLs come from the retention model in src/models/memory.rs.
SQLCipher or deployment-specific
Build with the sqlcipher feature to encrypt the SQLite file. For PostgreSQL volumes, the enterprise posture check records an operator attestation that storage encryption is on; it does not probe the disk itself.
Two tamper-evident chains
The signed_events table is an append-only SHA-256 chain checked by verify-signed-events-chain. The opt-in audit log is a hash-chained JSON stream checked by audit verify. Content is never written to the audit log.
backup · restore · doctor
ai-memory backup snapshots SQLite with an operator-signed manifest and refuses other stores; PostgreSQL uses your own base backups and WAL archive. doctor reports health locally or across a fleet with --remote.
LLM sweeps, opt-in
The curator periodically auto-tags and checks for contradictions through a configured LLM; autonomy adds consolidation, forgetting of superseded memories and priority feedback. Neither runs without an LLM configured.
Keyword + vector, plus a graph
Keyword search, embeddings from a local MiniLM model or an OpenAI-compatible endpoint, an in-process HNSW index on SQLite or pgvector on PostgreSQL, and temporal links with valid_from / valid_until. Apache AGE accelerates graph walks when installed.
Messages that wake their recipient.
memory_notify commits a durable inbox row, then publishes a bounded hint through an in-process bus, a wake sink and the host's wake-hub (a Unix-domain-socket switch with per-recipient queues, an allowlist and a delegation verifier) to the recipient's wake-listen session. The hint carries a digest, never the body. Across hosts the row travels by federation, and the receiving node publishes its own local wake only when the apply actually moved the row forward.
Degrade, never corrupt. The inbox row commits before any wake fires, so a slow, full or absent hub costs a hint and a counter, never a message. Clients must keep polling at least once a minute (BACKSTOP_POLL_MAX). The hub has no TCP or TLS listener: it is same-host by construction, and the cross-host leg is federation's mutual TLS. Jev is drawn as what it is: an operator-side subscriber that routes and pre-scores, not an ai-memory component. Sources: src/inbox_wake.rs, src/wake_sink/mod.rs, src/wake_hub/routing.rs, src/federation/applied_wake.rs; guide: wake plane, integrate any agent.
Durable first, replicated second.
A federated write commits locally before it fans out, so replication can be slow or partial without losing data. Every push is Ed25519-signed and carried over mutual TLS with pinned certificate fingerprints; receivers verify the signature, refuse replays and unenrolled peers, and check that the sender may write the namespace it claims.
The 202 contract. When fewer than W peers acknowledge before --quorum-timeout-ms, the daemon answers 202 Accepted with quorum_met:false and durability:"local": the write is safe on this node and queued for redelivery, which is why it is never reported as a server error. Writes made over MCP stdio join the quorum only when mcp_federation_forward_url points the MCP server at the local daemon; otherwise they skip the quorum and reach peers through the catch-up pull (a peer receives only rows in namespaces its attestation allowlist grants (deny by default) that are visible to its identity; scope=private rows stay on the node unless marked federation_share:true or the operator sets AI_MEMORY_FED_SYNC_TRUST_PEER=1), and their erasures travel through the outbox. Sources: src/handlers/parity.rs, src/replication.rs, src/federation/signing.rs, src/federation/peer_attestation.rs, src/federation/erasure_outbox.rs, src/config.rs; guide: federation.
Policy per namespace, approval where it matters.
A namespace standard binds a governance policy: for each of write, promote and delete, who may act (any, registered, owner or approve). The gate answers Allow, Deny or Pending; pending actions wait in a queue for memory_pending_approve or memory_pending_reject. Capability tokens are on by default and strictly additive.
Sources: src/models/namespace.rs, src/governance/capability.rs, src/governance/agent_action.rs; guide: governance.
Five tiers. Each one inherits the last.
Each tier page has its own animated diagram, a walkthrough of one write and one recall, a deployment recipe and the limits that tell you when to move up.
Single node
One agent, one store, no network. MCP over stdio or the CLI opens SQLite in-process; encrypt it with a SQLCipher build.
Tier 2Shared daemon
Many agents on one host share one store through ai-memory serve, isolated by namespace and scope, gated by governance, woken by the local hub.
Federated cluster
Several daemons replicate over the signed mTLS mesh with W-of-N quorum writes, catch-up pulls and erasure propagation.
Tier 4Data-center swarm
The PostgreSQL tier: daemons on PostgreSQL 18 with pgvector and, when installed, Apache AGE, spread across racks with rack-aware quorum.
Tier 5Federated hive
Independent certified clusters across data centers or regions, joined by federation with quorum tuned for partitions. No global consensus, by design.
3-region hive
The do-1461 run record: three regions, a federated quorum mesh and three encrypted legs, each proven both ways.
EnterpriseCPU + memory nodes
Federated nodes with API embeddings and no GPU.
EnterpriseCPU + memory + GPU nodes
The same federation with local embeddings on GPU nodes.
What each tier uses.
Every capability below is in the v1.0.0 build; the matrix shows where it does work. “opt” means available and off unless you turn it on.
| Capability | T1 | T2 | T3 | T4 | T5 |
|---|---|---|---|---|---|
| Store | SQLite | SQLite, shared | SQLite per peer, or PostgreSQL | PostgreSQL | PostgreSQL or SQLite per site |
| Encryption at rest | SQLCipher build | SQLCipher build | SQLCipher, or attested volume | attested volume | attested volume |
| MCP (core / full) · stdio, SQLite only | yes | yes | SQLite peers | no | SQLite sites |
HTTPS /api/v1/ daemon (TLS on every bind) | opt | yes | yes | yes | yes |
| CLI (in-process) | yes | yes | yes | admin verbs via --store-url | admin verbs via --store-url |
| Namespaces, scope visibility, governance | yes | yes | yes | yes | yes |
| Wake plane (one hub per host) | opt | yes | per host | per host | per host |
| Signed federation, W-of-N quorum | — | — | yes | rack-aware | cross-site |
| mTLS between peers | — | opt | required | required | required |
| signed_events chain · audit log | chain · audit opt | chain · audit opt | per peer | audit opt · chain verifier reads SQLite | per SQLite peer · audit opt |
| Backups | ai-memory backup | ai-memory backup | backup, or PostgreSQL base backups | base backups + WAL archive | WAL shipping off-site |
| Distributed consensus (Raft / Paxos) | no | no | no | no | no |
Tier guidance and sizing: enterprise deployment. Certified scope: the enterprise federation certification covers 500–1000-agent clusters built from blocks of at most 50 peers, as a trust boundary, not as a throughput figure (docs/compliance/ENTERPRISE-FEDERATION-CERTIFICATION.md).
What this architecture does not do.
Read these before you size a fleet. Each is documented with its reasoning in architectural limits.
No direct-to-PostgreSQL client
Agent traffic never connects to PostgreSQL: every request terminates at the ai-memory daemon, which stays the throughput bottleneck on both backends. Only operator admin verbs open a per-run --store-url connection.
One writer at a time per SQLite file
WAL lets readers pass the writer, but writes serialize. A shared daemon, MCP children and CLI processes on one host all queue on the same file lock. PostgreSQL removes this ceiling.
No CDC
There is no logical-replication or change-stream interface on either backend. The supported observation surface is hooks and webhook subscriptions.
Eventual, not consensus
Federation is quorum writes plus catch-up, with no Raft or Paxos and no gossip discovery. Knowledge-graph invalidations reach peers asynchronously.
Same host only
The hub listens on a Unix socket; mounting it remotely is not a supported transport. Cross-host messages ride federation, and the poll stays the delivery guarantee.
HNSW lives in process
On SQLite the vector index is held in RAM and rebuilt at start-up. pgvector keeps a durable index on PostgreSQL.