agent-memory: Local-First Long-Term Memory for AI Agents Using Plain Markdown

The problem agent-memory solves

AI agents that operate across sessions have no built-in mechanism to carry knowledge from one conversation to the next. An agent that learns a project's architecture, a team's preferences, or a debugging approach in one session starts from nothing in the next. Retrieval-augmented generation can inject documents, but it does not automatically capture what an agent learned during work.

agent-memory fixes this by acting as the write and retrieval layer between sessions. Markdown files in a designated store are the single source of truth. An SQLite index beside them serves as a cache for fast ranked search, but the README is explicit: the index is a rebuildable cache you can delete at any time. Running `rm -rf .index/ && mem rebuild` recovers the full index without losing any knowledge, because knowledge lives in the files, not the index.

Claude Code, Codex CLI, and any other agent that can execute shell commands share one store. The design does not bind the memory system to a single agent or a single API provider. Because no LLM client lives inside the library itself, there is no billing surface and no keys to configure for the retrieval path.

Two architectural lines in one store

The README describes the tension that shaped the design. One line of memory systems builds a retrieval engine: embeddings, a knowledge graph, a ranking pipeline. The retrieval is precise, but the store is opaque. The agent receives a chunk of text it cannot inspect, and the knowledge is locked into a format that is hard to migrate or audit.

The other line gives the agent a filesystem: Markdown files it can read directly, browsable with `ls` and `grep`. The store is legible and costs nothing to run, but it does not rank results and stops scaling once the tree grows too large for a directory listing.

agent-memory combines both. The retrieval engine indexes a filesystem the agent can also just read. Relations between memories live as links inside the Markdown frontmatter. A local index ranks them. Every retrieval result resolves to a whole Markdown file on disk. The README states that recall gains the precision of a graph and a vector search without giving up a plain directory an agent can walk, and nothing in the read path calls a model or crosses a network.

The four-level read path

Recall in agent-memory does not paste text into context. It returns an L0 list: one-line abstract, file path, anchor, and score. The agent then opens what it needs at the depth the task requires. The README documents this as four rungs, each an order of magnitude more expensive than the last:

mem recall "why files instead of a database"
mem recall "why files instead of a database" --limit 20
mem read <name> --level outline
mem context "why files instead of a database"
mem trace <name>

The first command returns up to eight memory candidates by default. The second increases the candidate pool. `mem read` with `--level outline` returns headings only rather than the full file. `mem context` runs both recall and partial expansion in one call. `mem trace` retrieves the cited raw messages that were distilled into a memory, preserved for audit.

Three read tracks run in parallel so that a miss on one does not mean no result. The first is deterministic injection of MEMORY.md at session start. The second is BM25 over an FTS5 index, with an optional vector plugin fused in by reciprocal rank fusion. The third is the plain directory tree, available when both indexed tracks fail.

Store layout and the config.toml contract

The README documents the store structure directly. One memory is one file. The store root holds MEMORY.md (the resident injection index with one line per memory), config.toml (every tunable parameter, where an unknown key is refused at load), and a schemas/ directory with one file per memory type. Memories live under type/group/name.md, placed by the schema. An archive/ folder holds append-only material out of the retrieval surface by default, and a provenance/ subfolder keeps distillation evidence indefinitely.

Frontmatter in each memory file carries the stable name, a one-sentence abstract, the type and its schema fields, timestamps, links to other memories, weight, and provenance. The body is free Markdown. The `valid_from` and optional `invalid_at` fields define a memory's validity interval. Replaced and deleted memories remain in the store so that `recall --as-of` can answer as of a specific date without losing the update history.

The .env.example in the repository shows the primary configuration variable:

AGENT_MEMORY_STORE=~/agent-memory-store

This variable points the CLI and any compatible agent to the store directory.

The Manage layer: sleep-time consolidation

Most memory systems either have no management layer at all, or bury consolidation inside the write path where it runs synchronously and blocks the agent's work. The README identifies this as a design gap and describes agent-memory's Manage layer as running on its own clock: an unattended pass that adds and updates memories, but where deletion only ever arrives as a proposal the user confirms.

The sleep-time pass consolidates and forgets by value. Authority tiers limit what the unattended pass can do without confirmation. Supersede operations leave the full chain intact rather than overwriting the original, so updating never destroys the history. The README states that `recall --as-of` answers as of any date because old versions remain accessible.

The benchmark data in the README measures the system against MemCore on LongMemEval-S with a bounded haystack of 120 episodes. agent-memory reached 52.9 percent pooled accuracy (127 of 240 answers), against 35.8 percent for MemCore and 5.8 percent for a baseline with no memory. The README notes that absolute numbers are not comparable to published LongMemEval scores because the haystack is bounded to 12 sessions per episode, making it a write-strategy study rather than a corpus-size comparison.

Package structure and what is not yet documented

The pyproject.toml shows a workspace with six packages: agent-memory-core, agent-memory-cli, agent-memory-mcp, agent-memory-adapters, agent-memory-executor, and agent-memory-harness. Optional extras cover vector support, the MCP adapter, and the evaluation harness. The project requires Python 3.12 or later.

An MCP adapter is listed in the workspace, which means the memory store can be exposed to agents that communicate over the Model Context Protocol. The README mentions `memory_correct` as an MCP operation name for revising memories, and `links: [...]` and `links: []` for managing relationships.

The README does not document a published PyPI install command. The repository is structured as a monorepo workspace and does not yet have GitHub releases. Teams intending to deploy the system will need to install from source using the workspace setup. The docs/ directory is present in the repository and referenced for design documents such as the management operation boundaries, but those documents are not reproduced in the README.

Limitations and licence

agent-memory is a write-strategy system, not a context window management system. It handles what gets written and retrieved across sessions, not how an individual session's context is managed. Teams looking to compress or rotate within-session context need a different tool.

The quality of write coverage depends on the host agent. Distillation is triggered at conversation boundaries and uses the host agent's own CLI to make judgements. A weaker model will produce lower-quality memories. The README notes that the full trace is copied first so that a failure in distillation does not lose the raw record, but the distilled memory quality still depends on what the host model does with it.

Vector search is an optional add-on, not the default. The default retrieval path is BM25 over FTS5. Teams that need dense retrieval for semantically fuzzy queries must install the vector extra and configure the plugin.

The project is MIT licensed. There are no restrictions on commercial use, modification, or redistribution. The repository was last pushed on 2026-09-25.

Editorial conclusion

agent-memory is the right choice for teams running Claude Code, Codex CLI, or any agent that can execute shell commands and want persistent memory that stays on their own infrastructure. The plain Markdown store is portable, greppable, and survives index loss without any knowledge loss. It is not the right choice for teams that need a hosted memory service with a REST API or who want memory managed by a third-party cloud. The project requires Python 3.12 or later, and the sleep-time consolidation pass currently uses the host agent's own CLI to make judgements, which means the quality of write coverage depends on the host model being used. The last push was on 2026-09-25, and there are no GitHub releases yet.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. tigerless-labs/agent-memory on GitHub