agent-memory: Markdown as the Store, SQLite as a Cache

What an agent forgets when the session closes

The problem agent-memory targets is narrow and concrete: an agent that ends its session loses everything it worked out during it. The README frames this as the gap the project exists to close, and it is not limited to coding agents. Any agent that can run a shell command is in scope, because the interface is a command line tool called `mem` rather than a library import. The intended user is someone who runs Claude Code, Codex CLI, or a comparable host and wants the two of them to read and write the same memory store. The README states that what one host's shell writes, another's finds, and that all nine ordered writer/reader pairs across Claude Code, Codex CLI, and Hermes pass in the project's own testing. That cross-host claim is the main reason to consider this over a per-tool memory plugin: the store is not owned by any one editor or CLI.

The store layout is the architecture

The README publishes the directory tree, and it is the clearest description of how the system is put together. `MEMORY.md` at the root is a one-line-per-memory index and is described as the only resident injection, meaning it is the single thing loaded into context unconditionally. `config.toml` holds tunables, and the README notes an unknown knob is refused at load, which is a deliberate strictness choice. `schemas/` holds one file per memory type, defining key fields, the field a type groups by, and its write mode. Memories then live at `<type>/<group>/<name>.md`, so a decision memory lands under `decision/agent-memory/markdown-files-are-the-single-source-of-truth.md`. `archive/` is append-only and out of the retrieval surface by default, split into `provenance/` for distillation evidence and `sessions/` for full trace copies. `dream-reports/` holds one report per sleep pass. `.index/` is the rebuildable cache: a content-hash manifest, an FTS5 index, and an access log. `.state/` holds runtime state that is not rebuildable, specifically the distillation watermark and the write lock. The split between `.index/` and `.state/` matters: one you can delete, the other you cannot.

Retrieval answers with paths, not pasted text

Recall does not inject memory bodies into the agent's context. It returns an L0 list, described as one-line abstract, file path, anchor, and score, and the agent then opens what it needs. The README gives three commands. `mem recall "why files instead of a database"` returns the L0 list, eight entries by default. `mem read <name> --level outline` returns headings only, and the level flag also accepts abstract or full. `mem context "why files instead of a database"` combines both in one call with the top few results expanded in full. The stated cost model is that index line, abstract, full file, and raw material each cost roughly an order of magnitude more than the previous rung, and each is a place the agent can stop. Long files add two more stopping points, the matched anchor and an outline computed at read time. The read tracks are three: deterministic `MEMORY.md` injection at session start, BM25 recall over an FTS5 index with an optional vector plugin fused in by reciprocal rank fusion, and the plain directory tree reachable with `ls` and `grep`. Links in frontmatter carry relations between memories without a graph database. This is a real design position: the index is a ranking aid, not the store, and the fallback when ranking fails is a shell command.

Writes fire at boundaries and consolidation runs separately

The README states that writes do not wait for the agent to remember to make them and instead fire at conversation boundaries. Distillation is triggered at those boundaries and runs without holding up the task, and the full trace is copied first, so the README's phrasing is that missed by the distiller never means lost by the system. A sleep-time pass then consolidates and forgets by value on its own clock, with what the README calls authority tiers: an unattended pass may add and update, but deletion only ever arrives as a proposal the user confirms. Superseding leaves the chain intact, and `recall --as-of` answers as of a date, so an update does not erase the prior state. That is a genuine difference from systems that overwrite on write. The library contains no LLM client, so judgement is borrowed from the host agent's own CLI, which the README says keeps every write visible in the transcript. The practical consequence is that there is no API key to install and no billing surface inside the library, but also that memory quality is bounded by whatever model your host CLI is running.

Getting it running and the knobs that exist

The README shows the runtime commands but does not reproduce an install line, so the exact package name and install command are not confirmable from the supplied material. What is confirmable is the Python version badge, 3.12+, and the version badge, 0.1.0. The store location is an environment variable, `$AGENT_MEMORY_STORE`, which the README uses as the root of the published tree. Configuration lives in `config.toml` inside that store, and the README states that an unknown knob is refused at load, so a typo in a key name fails loudly rather than being ignored. Memory types are declared in `schemas/`, one file per type, and each schema defines its key fields, the field the type groups by, and its write mode; placement of a memory file follows from the schema rather than from the agent's choice of path. The rebuild path is `rm -rf .index/ && mem rebuild`, which the README claims loses zero knowledge and says is enforced by a test rather than promised in a doc. That claim is the one worth verifying yourself before trusting the store with anything you care about.

Where this design breaks down

The README is candid that the benchmark numbers are not comparable to published LongMemEval scores. The haystack is bounded to 12 sessions per episode, which the project itself describes as making this a write-strategy study rather than a corpus-size one. The system-to-system row, agent-memory W2 at 127/240 pooled accuracy against MemCore W2 at 86/240, differs in write and read together, and the README states this licenses no attribution to either half. So the headline comparison tells you the end-to-end stack beat another end-to-end stack under a bounded haystack; it does not tell you which component did the work. The other limitation is structural: there is no LLM client inside the library, so the system cannot distill or consolidate without a host CLI to borrow judgement from. If you want memory that runs headless, in a service, or without an agent CLI present, this is the wrong shape. The 0.1.0 version number and the absence of any retrieved release also mean the surface is young. The README references a protocol document and a full ledger under `docs/exper`, but that path is truncated in the supplied material, so the evaluation methodology cannot be checked from here.

How it differs from embedding-first memory services

The README draws the contrast itself: one architectural line builds a retrieval engine with embeddings, a knowledge graph, and a ranking pipeline, which finds the right thing but hands back an opaque chunk and a store you cannot migrate off. The other hands the agent a filesystem, legible but unranked, which stops scaling when the tree outgrows a listing. agent-memory sits between them by indexing a filesystem the agent can also read directly, so every hit resolves to a whole Markdown file on disk. The operational difference against a hosted memory API is that nothing in the read path calls a model or crosses a network, per the README, so recall latency and cost do not scale with query volume. The difference against a plain Markdown folder is the FTS5 index and the optional vector plugin fused by reciprocal rank fusion, plus the schema-driven placement and the supersede chain. If your alternative is a hosted service, you are trading a managed sync and a vendor's ranking for a directory you can `git init` and a `mem rebuild` that reconstructs the index from the files.

Licence, maintenance, and what to check first

The licence is MIT, which permits commercial use, modification, and redistribution provided the copyright notice and permission notice are included; this is a description of the licence text, not legal advice, and you should read the LICENSE file in the repository for the binding terms. On maintenance cost, the material shows a last push of 2026-09-10 and no retrieved releases, so there is no release cadence to plan upgrades around and no changelog to diff against. The design does reduce one class of maintenance: because `.index/` is a rebuildable cache and `.state/` holds only a watermark and a write lock, the state you would need to back up is the store minus `.index/`. The upgrade risk sits in `config.toml`, since the README says an unknown knob is refused at load, which means a config written against one version may fail on the next if keys are renamed. Verify that first on a copy of your store rather than in place.

Editorial conclusion

Adopt it if you already run Claude Code or Codex CLI, want the memory store to be a directory you can grep and commit, and are comfortable with a 0.1.0 project whose index is disposable by design. Do not adopt it if you need a hosted API, a managed sync layer, or a memory system that works without a host agent CLI to borrow judgement from. Before committing, run `mem rebuild` after deleting `.index/` on your own store and confirm the recall results match, then check that your host's transcript format is one the distillation boundary actually recognizes.

Official sources

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