What ai-memory actually is.

It is not a notebook for your AI. Calling it that is a massive undersell. ai-memory is an autonomous-tier substrate for AI Non-Human Identity agents: persistent typed memory, a knowledge graph with temporal validity, operator-signed governance rules, signed reflections, attested links, and an operational discipline that says — out loud, in CLAUDE.md — fix everything.

In 60 seconds

An AI agent calls an LLM. The LLM is stateless — it sees only the prompt you hand it, on every call. Every memory of who the agent is, what it learned last week, what its operator told it to do at boot time, and what the agent itself decided three sessions ago is supplied by something outside the LLM. That something is the agent's substrate.

ai-memory is that substrate, built as a single Apache-2.0 Rust binary. It gives an AI Non-Human Identity (NHI) agent:

• Persistent typed memory. Not "blobs of text" — memories carry a kind (decision, observation, claim, concept, etc.), a confidence, a tier with a time-to-live, an agent_id, an audit trail.
• A knowledge graph. Typed directional links between memories — supersedes, contradicts, derived_from, related_to — with temporal validity (valid_from / valid_until), optional Ed25519 attestation, and a query surface that Apache AGE accelerates when you scale past T1.
• Operator-signed governance. Substrate rules L1–L6, each one Ed25519-signed by the operator's key. The agent cannot rewrite the rules; the operator can.
• A hook pipeline. Twenty-five named substrate events; programmable handlers; HMAC-required webhook subscriptions; an SSRF gate by default.
• An autonomous tier. When you wire in an LLM (local Ollama, remote OpenAI-compatible, whatever), the substrate will consolidate duplicate memories, detect contradictions across the chain, and auto-tag — without an agent having to ask.
• A signed audit chain. Every state change recorded in append-only Ed25519-signed events. Replayable, verifiable, cryptographically tamper-evident.

"Notebook for AI" gets you maybe 5% of the way to what this thing does. The real frame is: this is the substrate an autonomous AI agent runs on, the way a process runs on an operating system.

The 5-minute deeper read

Why "substrate" and not "notebook"

A notebook is a passive store. You write to it, you read from it. That is fine for human knowledge management; it is not enough for an autonomous AI agent. An autonomous agent needs the substrate to enforce things on its behalf — even against its own future requests — because the agent is, by design, going to try things and the operator needs guarantees that survive those attempts.

Three concrete guarantees ai-memory enforces that a notebook never could:

1. Identity preservation. Every memory carries metadata.agent_id. Once stored, that field is immutable across update, upsert, dedup, MCP memory_update, HTTP PUT, import, sync, and consolidate. The agent can rewrite the content; it cannot rewrite who wrote it.
2. Governance rules survive the agent. Substrate rules L1–L6 (each cryptographically signed by the operator) are loaded from disk on boot, not from the agent's working context. The agent can ask the substrate to apply them; the agent cannot strike them.
3. Audit chain is append-only. Every store, every link, every reflection, every promotion is signed into the events chain. The chain replays deterministically; tampering breaks the signature; the verifier catches it.

Why "NHI"

"AI Non-Human Identity" is the framing the security industry has converged on for autonomous agents that act on behalf of an organization, the way service accounts and machine identities do today. An NHI has an identity, a credential, a scope, an audit trail — just like a human identity, but without the human. The substrate has to know the difference between "this memory was written by alice the human" and "this memory was written by ai:my-curator-agent@host01:pid-4815." ai-memory carries that distinction natively, end to end.

Why "autonomous tier"

ai-memory ships in four operational tiers: keyword (FTS5 only, no model), semantic (MiniLM embeddings, cosine recall), smart (LLM-backed query expansion + auto-tag + contradiction detection — any provider via AI_MEMORY_LLM_BACKEND, local Ollama or cloud), autonomous (smart + cross-encoder reranking + LLM-driven consolidation and reflection). The autonomous tier is what makes the substrate act rather than just store; it is the one that runs a background curator that consolidates duplicate facts, flags contradictions in the chain, and lets the agent ask "what do I actually know, deduplicated" instead of "what's the keyword match for X."

Why one binary

Operability. One Rust binary, one SQLite file, no daemon required for single-agent use, four operational modes that scale from a developer laptop (T1) to a multi-region hive (T5). The same binary runs the MCP server, the HTTP daemon, the autonomous curator, and the quorum-sync federator — you just pick the subcommand.

Why "fix everything"

Because the substrate is the floor your autonomous agents stand on. If the floor has holes, you do not get to call them "non-blocking." Read CLAUDE.md if you want the full prime directive; the short version is: every issue discovered during testing is filed at the moment of discovery, fixed in the current release, retested, re-checked from a different angle, and only then closed. No deferral. No "vN+1 polish." The substrate gets to ship when the substrate is solid.

That is what ai-memory actually is. If you came here from "notebook for AI," delete that framing — it does not fit. The next essay, how an AI NHI uses ai-memory across a session, walks you through what an autonomous agent actually does with it: boot, recall, store, link, consolidate, reflect, hand off.