# CLAUDE.md vs shared memory for coding agents

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](https://code.claude.com/docs/en/memory), checked on 30 October 2026.

## What belongs in `CLAUDE.md`

Things that are true in every session and short to state:

```markdown
## 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." `brief` returns 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:

```bash
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 `supersedes` retires 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](https://repomemory.dev/dashboard/keys) page, then in the repository:

```bash
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](https://repomemory.dev/docs#mcp) show the setup for Codex, VS Code and Claude.ai.

---

*First published on [repomemory.dev](https://repomemory.dev/guides/claude-md-vs-shared-memory). I build RepoMemory, so weigh my take on it accordingly.*