🧠
Memory System
How Claude Code remembers across sessions using persistent memory files.
Types of Memory
Claude Code distinguishes between CLAUDE.md files (auto-loaded based on directory) and memory files (loaded on demand through @ references). Together they form the persistent knowledge layer.
| Type | Auto-Loaded | Scope | Example |
|---|---|---|---|
| Project CLAUDE.md | Yes | Team-shared, version-controlled | Architecture, commands, standards |
| User CLAUDE.md | Yes | Personal, all projects | Code style prefs, workflow shortcuts |
| Subfolder CLAUDE.md | Yes (if working in that folder) | Subsystem-specific | API conventions, component patterns |
| Memory files | No — loaded via @ reference | On-demand context | Frontend persona, spec docs, domain knowledge |
The Memory Hierarchy
Memory Hierarchy & Discovery
~/.claude/CLAUDE.mdUser-wide (all projects)Always loaded./CLAUDE.mdProject root (team-shared)Always loaded./src/CLAUDE.mdSubfolder (specific context)If working in dir./memory/*/CLAUDE.mdMemory files (on demand)Via @ referenceAdding Memory
Memory can be added through the /memory command or by running /init on an existing project. The /memory command lets you add specific facts or preferences, and Claude will prompt whether to store them at the project or user level.
bash
# Add a memory via command
/memory add Always use descriptive variable names
# Initialize memory for an existing project
/init
# Reference memory files in CLAUDE.md
# Add this line to any CLAUDE.md:
@./memory/frontend/CLAUDE.mdOrganizing Memory Files
text
memory/
├── frontend/
│ └── CLAUDE.md ← Frontend persona, React patterns
├── spec/
│ └── CLAUDE.md ← Product specification
├── api/
│ └── CLAUDE.md ← API conventions, endpoints
└── testing/
└── CLAUDE.md ← Testing strategy, fixtures💡Tip
Memory files that are not auto-loaded give you fine-grained control over when context is injected. Load the frontend context only when building UI. Load the API context only when working on endpoints. This keeps the context window lean.