Memory Stack (4 levels)
Where the information Claude uses lives and how to manage it
The 4 memory levels
Claude Code does not store state between sessions by default. Everything that needs to persist must be explicitly placed in one of the four levels.
Level 1: CLAUDE.md (explicit rules) Markdown files read at the start of each session. They contain project conventions, important commands, and architecture decisions. Human-readable, versioned with the code.
~/.claude/CLAUDE.md # Global (all sessions).claude/CLAUDE.md # Project (team)CLAUDE.md # Root (current folder)Level 2: Auto-memories (automatic learning)
Claude automatically records decisions made during sessions in ~/.claude/projects/*/memory/MEMORY.md. This mechanism is transparent: you can review these files to audit what Claude has learned.
Level 3: Tasks API (structured cross-session state) For multi-step workflows spanning several sessions, the Tasks API maintains state with dependencies and statuses. Useful for long projects where each session picks up where the previous one left off.
Level 4: Agent memory field (local context) Each specialized agent can have its own declarative memory in its YAML frontmatter, independent from the main session.
What disappears each session
The conversation itself is ephemeral. When you close a session, everything that has not been explicitly persisted is lost. There is one exception: claude --continue resumes the last session, but this only works if you have not opened any other sessions in between.
Selection rule
| Need | Level to use |
|---|---|
| Permanent project convention | CLAUDE.md |
| Decision made in session | Auto-memory (or manual CLAUDE.md) |
| State of a long task | Tasks API |
| Context of a specialized agent | Agent memory field |
| Ephemeral configuration | Session (no persistence) |
CLAUDE.md as composed memory
“You should never have to correct Claude twice for the same mistake.” (Boris Cherny, creator of Claude Code)
Each mistake corrected once becomes a CLAUDE.md rule. Over 3 months, a well-maintained CLAUDE.md accumulates the conventions, gotchas, and architecture decisions that accelerate all subsequent sessions, including for new team members.
# CLAUDE.md (growth pattern)Week 1 : 5 rules → 5 errors avoidedMonth 1 : 20 rules → 20 errors avoidedMonth 3 : 50 rules → accelerated onboardingTarget size: between 4 and 8 KB total (across all levels). Beyond 16 KB, model coherence degrades according to practitioner studies.
Enter your email to read the full card and get the complete PDF bundle.
All content is free and open-source. We just ask for your email.