Previously, Claude remembered nothing. Every session started 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 disappeared with /clear.
CLAUDE.md partially compensated by allowing you to encode project conventions, the stack, and deployment rules. However, there's a category of information CLAUDE.md handles poorly: things that evolve over time. Examples include an architecture decision made this month, a style preference corrected mid-session, or a "gotcha" found in production. These have variable lifespans and don't all belong in a file versioned with the project.
Claude Code has introduced a persistent memory system specifically for this purpose.
What Auto-Memory Does — and Doesn't
Auto-memory consists of a set of Markdown files stored in a dedicated directory per project (~/.claude/projects/<project>/memory/) or globally (~/.claude/memory/). Claude reads these files at session start via an index file MEMORY.md and can update them during the session.
It is not an automatic session log. Claude doesn't note everything that happened. It's an active tool—you must explicitly tell it what's worth keeping, or ask it to run the audit itself.
The distinction with CLAUDE.md is important. CLAUDE.md describes the project: stack, conventions, deployment. Memory describes the working relationship: preferences, ongoing decisions, and non-obvious constraints at a given point in time.
The 4 Memory Types
Each memory file declares a type in its frontmatter. This is not cosmetic; it defines when Claude will use them.
user— Defines who you're working with: your role, technical level, and areas of knowledge. This allows Claude to calibrate explanation depth without requiring re-introductions every session.feedback— Guides how to approach the work: what was corrected, what was validated. Examples include: "Don't summarize what you just did at the end of messages" or "Always use a real database in tests, no mocks."project— Captures the current project state: active decisions, ongoing initiatives, and time constraints. These age quickly and require regular review.reference— Provides pointers to information in external systems: "pipeline bugs tracked in Linear project INGEST," or "Grafana latency board at grafana.internal/d/api-latency."
What's Worth Keeping — and What Isn't
Memory is not an archive. What goes into a memory file must be non-deducible from the code or CLAUDE.md and must be 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 logs are more reliable for that.
- In-progress tasks—these do not belong in memory.