Memory Hierarchy
claude-code has five distinct memory systems operating at three scopes. This is not one memory system — it is a layered hierarchy where each level serves a different purpose, persistence, and access pattern.
The Five Systems
| # | System | Who Writes It | Scope | Persistence |
|---|---|---|---|---|
| 1 | CLAUDE.md | User | Global + Project | Permanent until user edits |
| 2 | auto-memory | Claude | Project | Permanent, consolidated by auto-dream |
| 3 | Session memory | Claude | Session | Per-session transcript |
| 4 | Team memory | Agents | Team | Shared across teammate-tool agents |
| 5 | Agent memory | Agent | Per-agent | Private to each spawned agent |
Three Scopes
| Scope | What Lives Here | Loaded When |
|---|---|---|
| Global | ~/.claude/CLAUDE.md, global rules |
Every session |
| Project | ./CLAUDE.md, .claude/rules/*.md, ~/.claude/projects/<slug>/memory/ |
When entering project directory |
| Session | Conversation transcript, tool results, compacted context | Current session only |
Loading Order
The system prompt is assembled from six layers on every query turn (not just session start). CLAUDE.md is reloaded every turn and supports up to 40,000 characters:
~/.claude/CLAUDE.md(global user rules)./CLAUDE.md(project root).claude/rules/*.md(modular rules, alphabetical)~/.claude/projects/<slug>/memory/MEMORY.md(auto-memory index, first 200 lines only)- system-reminders (40+ behavioral injections at tool boundaries)
- Session context (conversation history, tool results)
The Three-Layer Auto-Memory Architecture
Within the auto-memory system, a three-layer hierarchy exists:
- Layer 1 —
MEMORY.md: 200-line index of ~150-character pointers, always in context - Layer 2 — Topic files: actual project knowledge, loaded on demand by Claude
- Layer 3 — Daily transcripts: never re-read fully, only grep'd for specific identifiers
auto-dream is the garbage collector for this hierarchy.
Key Design Decision
The memory system deliberately rejects embeddings and vector search. Claude calls ls(), reasons about relevance from filenames, then reads selected files. See grep-over-rag.
Key Claims
clm-20260409-9365a2e841e1: Five distinct memory systems at three scopes
Sources
src-20260409-a14e9e98c3cd— Internals: Auto-Memory, Auto-Dream, and Agent Teams