README

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:

bash
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  --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                                   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 

Top issues