Claude remembers nothing. Every session starts from scratch — the preferences you explained
last week, the business constraints it discovered while working on the code, the corrections
you had to make twice. Everything disappears with /clear.
CLAUDE.md partially compensates: you encode project conventions, the stack, deployment rules. But there's a category of information CLAUDE.md handles poorly: things that evolve over time. An architecture decision made this month, a style preference corrected mid-session, a gotcha found in production. These have variable lifespans and don't all belong in a file versioned with the project.
Claude Code has a persistent memory system for exactly this.
What auto-memory does — and doesn't
Auto-memory is a set of Markdown files in a dedicated directory per project
(~/.claude/projects/<project>/memory/) or global
(~/.claude/memory/). Claude reads them at session start via an index file
MEMORY.md, and can update them during the session.
What it doesn't do: it's not an automatic session log. Claude doesn't note everything that happened. It's an active tool — you have to tell it explicitly what's worth keeping, or ask it to run the audit itself.
The distinction with CLAUDE.md matters. CLAUDE.md describes the project: stack, conventions, deployment. Memory describes the working relationship: preferences, ongoing decisions, non-obvious constraints at a given point in time.
The 4 memory types
Each memory file has a type declared in its frontmatter. It's not cosmetic — it defines when Claude will use them.
- user — who you're working with: role, technical level, areas of knowledge. Lets Claude calibrate explanation depth without re-introductions every session.
- feedback — how to approach the work: what was corrected, what was validated. "Don't summarize what you just did at the end of messages" is feedback. "Always use a real database in tests, no mocks" too.
- project — current project state: active decisions, initiatives, time constraints. These age fast — they need regular review.
- reference — where to find information in external systems: "pipeline bugs tracked in Linear project INGEST", "Grafana latency board at grafana.internal/d/api-latency".
What's worth keeping — and what isn't
Memory is not an archive. What goes in a memory file must be non-deducible from the code or CLAUDE.md, and useful in future sessions.
Worth keeping:
- A style preference confirmed or corrected during the session
- A real gotcha discovered while working — an invisible constraint, a counter-intuitive behavior
- An active architecture decision not yet reflected in code
- A pointer to an external resource you use regularly
Doesn't belong in memory:
- Anything visible in the files — Claude will find it by reading the code
- Session details — git log is more reliable for that
- In-progress tasks — they belong to the session, not persistent memory
- Conventions already in CLAUDE.md — pointless duplication
Project memory vs global memory
Project memory (~/.claude/projects/<sanitized-cwd>/memory/) is isolated
per working directory. Open Claude from a different folder, and you get a different memory.
This is the right option for project-specific preferences and decisions.
Global memory (~/.claude/memory/) applies across all sessions and projects.
That's where truly cross-cutting preferences go: expected response style, the person's
technical level, communication conventions.
In practice: start with project memory. If a preference comes up across all projects, move it to global. Never duplicate both.
Automatic feeding: the rule in ~/.claude/CLAUDE.md
Rather than asking Claude to save something each time you think of it, you can give it
the rule once in the user-level CLAUDE.md — ~/.claude/CLAUDE.md, loaded
in every session across all projects.
# Global rules
## Auto-memory
When a session reveals persistent information, save it immediately
to the right memory file without waiting to be asked:
- Preference discovered or corrected → memory/user or memory/feedback
- Approach correction → memory/feedback
- Durable project decision → memory/project
- Pointer to regularly-used resource → memory/reference
Do not save: temporary state, in-progress work, what's already in
CLAUDE.md, what's deducible from the code.The filter matters as much as the trigger. Without it, Claude will log every session detail and memory grows as fast as the CLAUDE.md you just cleaned up.
Maintaining memory: the audit prompt
Memory ages. Project-type memories especially — a decision made in January may be resolved by March, but the file stays. Without regular review, you accumulate stale information that Claude will read and potentially apply incorrectly.
An audit prompt to run at session start when memory has drifted:
Audit the memory files in `.claude/projects/.../memory/`.
For each file:
1. Is the content still accurate? (check against current file state if needed)
2. Is it non-deducible from code or CLAUDE.md?
3. Is the type correct? (user / feedback / project / reference)
4. Is the frontmatter description precise enough?
Global coherence: duplicates, contradictions, stale project memories, MEMORY.md up to date?
Output as table: File | Issue | Recommended action
Then apply corrections.
To avoid hunting for this prompt, save it as a slash command in
.claude/commands/audit-memory.md (project) or
~/.claude/commands/audit-memory.md (global). Then /audit-memory
is enough.
Conclusion
Auto-memory solves a specific problem: information that evolves too fast for CLAUDE.md, but worth carrying across sessions. It works well when you're selective — one file per topic, a well-chosen type, a precise description in the frontmatter.
What breaks the system: trying to put everything in it. Memory that grows without criteria ends up as useless as a 300-line CLAUDE.md — Claude loads everything, processes everything, and the signal drowns in noise.