CLAUDE.md vs agent memory: what each should store

A team adds another paragraph to CLAUDE.md every time Claude Code makes a mistake.

Six weeks later, the file contains build commands, style rules, a product exception, three temporary migration notes, an old API decision, and a warning that contradicts a newer warning lower down.

Claude has more memory and less clarity.

CLAUDE.md and agent memory are both useful, but they should not store the same things. The simplest way to choose is to ask who needs the information, how long it stays true, and what happens when it changes.

The short answer

Use four separate homes:

Information	Best home	Why
Stable project instructions	CLAUDE.md	Intentional, reviewable, version-controlled guidance
Personal recurring patterns	Auto memory	Useful continuity for one person's Claude sessions
Current task state	Handoff or task note	Temporary, specific, easy to replace
Team decisions	Shared approved record	Needs owner, status, scope, and replacement history

One file can technically hold all four. It usually should not.

What belongs in CLAUDE.md

Claude Code's documentation describes CLAUDE.md as persistent project guidance. Use it for instructions that are both important and durable.

Good entries include:

• the command to run tests for this repository;
• which package manager the team uses;
• the boundary between two services;
• where migrations live;
• naming or formatting conventions not enforced automatically;
• a hard rule such as never logging raw tokens;
• a durable architecture invariant that affects most work.

A useful CLAUDE.md sentence tells Claude what to do repeatedly. It should still be correct when a different engineer opens the repository next month.

Keep the file close to the code it governs. If instructions apply only to one package or directory, scope them instead of loading them into every task.

What belongs in agent memory

Auto memory is best for personal, recurring working knowledge that helps Claude collaborate with one user across sessions.

Examples:

• you prefer small commits;
• you want test output summarized in a particular format;
• a local environment has a recurring setup detail;
• you routinely ask for a plan before edits;
• a harmless tool preference repeats across projects.

This is working continuity, not company policy. A teammate should not inherit your personal preferences as if the team approved them.

Do not use personal memory as the only home for a rule that controls production behavior, customer data, or architecture. Nobody else can reliably review or receive it.

What belongs in a task handoff

A handoff carries temporary execution state:

• current objective;
• files changed;
• evidence gathered;
• tests run;
• blockers;
• unresolved decisions;
• next step.

It should make a new session productive without replaying the full transcript. When the task ends, much of it can disappear.

If one item must shape future work, promote it to the right durable home. A new test command may enter CLAUDE.md. An approved product exception may enter the team's decision record.

What should not be buried in CLAUDE.md

Temporary plans

"For this week's migration, route new users through v2" will go stale. Keep it with the task and give it an expiry condition.

Unresolved ideas

A proposed architecture is not an instruction. Label it as proposed and ask the owner before an agent treats it as binding.

Long explanations of every past discussion

Claude needs the verdict and the reason relevant to its task, not every message that preceded them.

Customer or product exceptions with no owner

A sentence such as "enterprise accounts keep legacy access" is dangerous without scope, reason, owner, and status. When the exception ends, who removes the line?

Secrets

Never place credentials, tokens, or private customer data in a repository instruction file.

Where architecture and product decisions belong

Some architecture decisions are stable enough to appear as a short invariant in CLAUDE.md. The full record still needs more:

• what the team chose;
• why it chose it;
• what it rejected;
• who owns the call;
• what code or behavior it affects;
• whether it is active or superseded.

Product decisions matter too. A pricing promise or onboarding rule may constrain several services even though it is not an architecture decision. Product, engineering, support, and coding agents should be able to trace the same current answer.

This is why decision-log tools for product and engineering teams and ADRs complement repository instructions rather than compete with them.

A practical CLAUDE.md structure

A focused file might contain:

# Repository guide

## Commands
- Install: `pnpm install`
- Test affected packages: `pnpm test --filter ...`

## Boundaries
- Billing owns payment state transitions.
- Identity may read account status but must not write billing state.

## Hard invariants
- Never log raw credentials or payment details.
- Any change to guest-checkout ordering must check active checkout decisions.

## Context sources
- Use the issue tracker for current task scope.
- Query the shared decision source before changing checkout or pricing behavior.

This tells Claude how to work and where to find changing truth. It does not pretend the file itself can contain every current decision.

A maintenance test

Review each instruction with four questions:

1. Does this apply to many future tasks?
2. Would another teammate agree it is a team instruction?
3. Is it still current?
4. Is CLAUDE.md the smallest correct home for it?

If the answer to the first two is no, move it to personal memory or the task handoff. If the answer to the third can change with a product or architecture call, put the full decision in a record with status and an owner.

The same model applies beyond Claude Code. Cursor rules, MCP servers, repository files, and shared decision records each solve a different context job.

Where Lockstep fits

Lockstep is the shared decision layer. It captures possible decisions from Slack, docs, tickets, and code discussions, asks the owner to confirm them, and keeps the approved version tied to what it affects. Claude Code and other MCP-compatible agents can retrieve the relevant active decisions before they work.

It does not replace CLAUDE.md or auto memory. CLAUDE.md tells Claude how this repository works. Auto memory helps one user continue recurring patterns. Lockstep carries the product and architecture calls the whole team must keep consistent.

For cross-tool teams, see how to share memory between Cursor and Claude Code. For live context sources, compare MCP servers for engineering teams.

The best context setup is not the one that remembers the most.

It is the one that gives each kind of information a clear owner, scope, and place to change.