agent-memory

agent-memory: the long-term memory runtime for AI agents

Invariants · Skill · Issues

An agent that closes its session forgets everything it learned in it. agent-memory is the runtime that fixes that, for any agent — not only coding ones. Markdown files in one store are the single source of truth, the SQLite index beside them is a cache you can delete at any time, and Claude Code, Codex CLI, Muse Code, and anything else that can run a shell command share that store.

Retrieval is local and ranked, and it answers with paths rather than pasted text — the agent opens each hit only as deep as the task needs. Writes do not wait for the agent to remember to make them: they fire at conversation boundaries. A sleep-time pass then consolidates and forgets by value, on its own clock. None of it needs an API key.

Two lines, one store

Agent memory has grown along two architectural lines. One builds a retrieval engine — embeddings, a knowledge graph, a ranking pipeline — which finds the right thing, but hands the agent an opaque chunk it cannot inspect and a store it cannot migrate off. The other hands the agent a filesystem — markdown it reads directly, browsable with ls and grep — which is legible and costs nothing to run, but does not rank, and stops scaling the moment the tree outgrows a listing.

agent-memory is the two of them in one store: the retrieval engine indexes a filesystem the agent can also just read. Relations live as links inside the memories, a local index ranks them, and every hit resolves to a whole markdown file on disk. Recall gains the precision of a graph and a vector search without giving up a plain directory an agent can walk — and it stays fast, because nothing in the read path calls a model or crosses a network.

Retrieve by path, then read by level

Recall does not paste text into your context. It answers with an L0 list — one-line abstract, file path, anchor, score — and the agent opens what it wants at the depth the task needs:

mem recall "why files instead of a database"    # L0 list, 8 entries by default
mem recall "why files instead of a database" --limit 20  # more Memory candidates
mem read <name> --level outline                 # headings only; or abstract, or full
mem context "why files instead of a database"   # both in one call, top few expanded in full
mem trace <name>                                 # cited raw messages, when needed

Index line → abstract → full file → raw material: each rung costs an order of magnitude more than the last, and each is a place to stop. Long files add two free rungs — the anchor that matched, and an outline computed at read time.

Design commitments

• Three read tracks, so a miss on one is not a miss. Deterministic MEMORY.md injection at session start; BM25 recall over an FTS5 index, with a vector plugin fused in by RRF when you want one; and the plain directory tree, reachable with ls and grep when both fail. Same-directory memories are a free neighbourhood, and links in the frontmatter carry the graph without a graph database under them.
• Write coverage is the system's job, not the agent's judgement. Distillation is triggered at boundaries and runs without holding up the task; the full trace is copied first, so "missed by the distiller" never means "lost by the system".
• Files are the truth; every index is a rebuildable cache. rm -rf .index/ && mem rebuild loses zero knowledge — enforced by a test, not promised in a doc. Your memory stays greppable, git-able, and portable off this system.
• A real Manage layer, on its own clock. Sleep-time consolidation with authority tiers: an unattended pass may add and update, deletion only ever arrives as a proposal you confirm. Every competitor either has no M, or buries it in the write path. Supersede leaves the chain intact and recall --as-of answers as of a date, so updating never destroys.
• No LLM client inside the library. Zero keys to install and no billing surface: judgement is borrowed from the host agent's own CLI, which keeps every write visible in your transcript.

The store

$AGENT_MEMORY_STORE/
├── MEMORY.md              root index, one line per memory — the only resident injection
├── config.toml            every tunable; an unknown knob is refused at load
├── schemas/               one file per type: its key fields, the field it groups by, write mode
├── decision/              memories live at <type>/<group>/<name>.md, placed by the schema
│   └── agent-memory/        …/markdown-files-are-the-single-source-of-truth.md
├── archive/               append-only, out of the retrieval surface by default
│   ├── provenance/        distillation evidence, kept forever
│   └── sessions/          full trace copies, in case the host prunes its own
├── dream-reports/         one per sleep: what moved, what was proposed, evidence pointers
├── .index/                fully rebuildable: content-hash manifest, FTS5, access log
└── .state/                runtime state that is not: distillation watermark, write lock

One memory is one file. valid_from and optional invalid_at define its validity interval; replaced and deleted files stay in the store for recall --as-of and trace. Current recall, MEMORY.md, BM25, and Vector use files without invalid_at. Frontmatter carries the stable name, a one-sentence abstract, the type and its schema fields, timestamps, links, weight, and provenance; the body is free markdown. Existing files with status load without a reset.

Explicit links must name distinct active memories in the same store. correct --link replaces the full list; correct --clear-links removes every link. MCP memory_correct uses links: [...] and links: [] for the same operations. Omitting links preserves historical relationships during unrelated correction. See the operation boundary design.

Agents can use mem correct <name> to revise a memory, mem record --supersedes <old> to create a successor, mem supersede <old> <new> to use an existing successor, mem merge <first> <second> --abstract ... --body ... to combine memories atomically, and mem delete <name> to end current validity. Splitting uses new record calls followed by delete of the original. Core checks file scope, relationships, provenance, and concurrent writes; Sleep keeps its proposal and cap limits for unattended actions.

Proof it works

Measured on LongMemEval-S with a bounded haystack, 120 episodes, claude -p (Haiku 4.5) as host, one calibrated Sonnet 5 judge, two exam replays per arm.

Absolute numbers are not comparable to published LongMemEval scores — the haystack is bounded to 12 sessions per episode, which makes this a write-strategy study rather than a corpus-size one. The system-to-system row differs in write and read together, so it is an end-to-end comparison and licenses no attribution to either half.

One store, three hosts: all 9 ordered writer/reader pairs across Claude Code, Codex CLI, and Hermes pass — what one host's shell writes, another's finds, specifics intact. Pooled net contribution over no memory: 2/36 → 13/36, p=0.0074.

The protocol that decides whether a measurement counts as a result, the full ledger, and the raw run records live in docs/experiments.md and experiments/ in the working tree. They ship with the source, not with git history.

Install

Requires Python 3.12 or higher and uv. There is no release on PyPI yet, so install from a checkout:

git clone https://github.com/tigerless-labs/agent-memory.git
cd agent-memory
uv sync --all-packages

That builds mem, mem-mcp, and mem-hook into .venv/bin. Inside the checkout uv run mem reaches them; put the directory on your PATH so your shell can too:

export PATH="$PWD/.venv/bin:$PATH"

Quick start

mem init

The store defaults to ~/agent-memory-store; export AGENT_MEMORY_STORE only to put it somewhere else, and export it everywhere your agents run, not just in this shell.

Write one memory, find it again, then throw the index away and prove nothing was lost:

mem record --type decision --field project=agent-memory \
  --abstract "Markdown files are the single source of truth" \
  --body "Indexes are rebuildable caches."
mem --json recall "source of truth"
rm -rf ~/agent-memory-store/.index && mem rebuild

Wire it into your agent

mem setup --host claude-code
mem setup --host codex
mem setup --host muse-code --provider openrouter

All three commands use the same pipeline: probe the host, initialize or check the Store, safely merge host settings, install lifecycle hooks and the skill, perform provider-specific setup, then run preflight. A successful command ends with status: READY; a written configuration is not by itself considered ready. Re-running setup is safe and does not duplicate managed hooks, skills, provider routing, or MCP entries. Existing unrelated host settings are retained, and a conflicting setting fails closed instead of being re