agent-memory-atlas AGENTS.md

Working in this repository

A code-grounded field guide to agent memory systems: 357 reports, each read at a pinned commit, plus 21 design patterns extracted from them.

There are two jobs here, and they use different parts of the repo.

---

Job 1 — You are designing or building memory for some other product

Start with the use-the-atlas skill (.agents/skills/use-the-atlas/). It is this section as a workflow: read the target repository, pick a profile, write a build brief, stop for approval, implement in an order where each stage stands alone, then run the tests by id. The rest of this section is what it is built on.

Do not read the reports. There are hundreds and reading widely is how an agent ends up recommending the most interesting mechanism instead of the smallest sufficient one. Read five things, in this order.

1. content/patterns/index.md, the section How to use the library. It is a list of failure modes, each pointing at the pattern that closes it. Start from the failure the product cannot tolerate, not from the mechanism that sounds most rigorous.

2. The Stacks, by what you are building table on the same page. Five rows — single-user tool, multi-tenant, companion/roleplay, autonomous actor, and memory that must be correctable and defensible — each naming the failure that actually hurts for that shape. Pick the row, then read the What you can defer paragraph under it, which is the part that keeps the build small.

3. The pattern pages you selected. Each carries Cost to adopt, Tradeoffs, Implementation checklist, Tests to require, and Seen in the atlas. The last one names the systems worth reading — that is your entry point into the corpus, and the only one you need.

4. content/overview.md §8 What I Would Build and §10 Practical Checklist. §8 gives a build order in which each stage works on its own; vector search and model-based extraction come last, deliberately.