Put instructions in CLAUDE.md and history in shared memory. CLAUDE.md (or AGENTS.md) is loaded in full into every session, so it should hold short, stable rules: how to build, conventions, where things live. Shared memory is searched when it's needed, so it can hold the long tail: why a decision was made, what was reverted, which tasks are open. Most projects need both, and the CLAUDE.md is where you tell agents to use the memory.
The difference in one table
| CLAUDE.md / AGENTS.md | Shared memory (a ledger over MCP) | |
|---|---|---|
| What it holds | Instructions | Decisions, lessons, guardrails, notes, tasks |
| How the agent gets it | Loaded whole at session start | brief at session start, recall with words about the change |
| Size it works at | Short: Anthropic suggests under 200 lines per file | Hundreds of entries; only matching ones come back |
| Who writes it | People, in commits | Agents and people, as they work |
| When something changes | Someone edits the line | A new entry supersedes the old one, which is retired |
| Who reads it | Whoever has the repository checked out | Every agent and person with a key to the project, in any client |
| Versioned | In git, with the code | In the ledger, with the author and date of each entry |
The CLAUDE.md column is from Anthropic's memory docs, checked on 30 October 2026.
What belongs in CLAUDE.md
Things that are true in every session and short to state:
## Build
- `npm test` before committing; `npm run lint -- --fix` for style.
## Layout
- API handlers in src/api/handlers/, one file per route.
## Project memory (RepoMemory, project "acme/shop")
- At the start of a session, call `brief` for the project. Never break a guardrail.
- Before planning a change, call `recall` with words about the change.
- When a change is reverted or you choose one approach over another, call `record_entry`.
If a line only matters when someone touches one part of the code, it's a
candidate for a path-scoped rule (.claude/rules/ in Claude Code,
.cursor/rules/ in Cursor) or for the ledger.
What belongs in shared memory
Things that matter for one change, and stories that explain a rule:
- Lesson: "Captcha on checkout cut completed orders 5%. Reverted after two weeks; bots only spike on release days."
- Decision: "Chose Postgres full-text search over embeddings: same query, same results, no model to run."
- Guardrail: "Never run migrations on deploy; the release job runs them
first."
briefreturns every guardrail at the start of a session, so rules like this don't depend on a search matching them. - Task: "Move image uploads to R2", which an agent claims before starting so no other agent starts the same job.
Here's a lesson being recorded, as an agent would through the
record_entry tool:
curl -s https://api.repomemory.dev/v1/record \
-H "X-API-Key: $REPOMEMORY_KEY" -H "Content-Type: application/json" \
-d '{"project":"acme/shop","kind":"lesson",
"title":"Captcha on checkout cut completed orders 5%",
"body":"Shipped a captcha on the checkout page in March and reverted it after two weeks: completed orders fell 5%. Bots only spike on release days.",
"tags":["checkout","captcha"],"agent":"claude-code"}'
Six months later, an agent asked to "add a captcha to checkout" recalls with those words and finds it before writing any code.
Signs you've put something in the wrong place
- Your CLAUDE.md has a "history" or "don't do X again" section that keeps growing. Move the stories to the ledger and leave one-line rules.
- Agents repeat a reverted change. The lesson was in a PR description or a chat nobody's agent reads.
- Two lines in CLAUDE.md contradict each other because a decision changed.
In a ledger, recording the new decision with
supersedesretires the old one. - A rule is ignored by Cursor or Codex because it lives in Claude Code's machine-local auto memory.
Set it up
Create a free key on the API keys page, then in the repository:
export REPOMEMORY_KEY=sk_live_...
npx @plexsicity/repomemory init
It adds the MCP server to Claude Code and Cursor and writes the project-memory section into AGENTS.md or CLAUDE.md. The docs show the setup for Codex, VS Code and Claude.ai.