Claude Code Memory System
Claude Code has 4 levels of persistent memory: project CLAUDE.md (repo root), subdirectory CLAUDE.md (loaded on demand, when Claude reads a file in that folder), user CLAUDE.md (~/.claude/), and auto-memory (markdown files written by Claude in ~/.claude/projects/<project>/memory/, whose first 200 lines of MEMORY.md or 25 KB load every session). Discovered CLAUDE.md files are concatenated into context, not overridden; an organization policy file and a personal CLAUDE.local.md also exist.
Strengths
- 4 granularity levels: global → project → subdirectory → auto-memory
- Auto-memory: Claude writes its own persistent notes between sessions
- Committable CLAUDE.md, project rules propagate to the whole team via the repo
Limitations
- Overloaded CLAUDE.md → context window wasted every session
- Auto-memory can go stale if Claude isn't invited to clean it up regularly
- A CLAUDE.md loads in full every session, whether or not it concerns the file you are touching, and it never updates itself. Before installing a tool that injects rules at the right moment, try the native answer: files in .claude/rules/ with a paths field, which only load when Claude reads a matching file
- Auto-memory (MEMORY.md) is a personal block: an instruction worth sharing cannot be pulled out of it without handing over everything else along with it, preferences and private notes included ([Instagram reel Ddv8_rzgaCr](https://www.instagram.com/reel/Ddv8_rzgaCr/)). What should travel with the team goes into a rule (.claude/rules/) or a skill, which can be shared one at a time; memory keeps what concerns only you
Best for
- Long-term projects where Claude needs to know conventions and architecture without reminders
- Multi-dev teams wanting to share Claude rules via the repo (committed CLAUDE.md)