Memory Systems
Claude Code runs on three distinct memory tracks, not one. Knowing which fits your situation determines whether sessions start from scratch or pick up exactly where you left off.
Native Stack
Zero setup, works today. CLAUDE.md for permanent instructions, Auto Memory for automatic cross-session notes, Auto Dream for background consolidation.
Built-inCross-Session Tools
Community-built hooks and MCP servers that persist what Claude does automatically. claude-mem, agentmemory, ICM, Kairn, doobidoo:each with a different recall model.
CommunityTeam + Multi-Agent
Sharing memory across developers or autonomous agents. The Trinity (zero infra), Mem0 Cloud, Zep/Graphiti. Concurrent-write coordination via leases and signals.
AdvancedNative Claude Code Memory Stack
Four mechanisms built directly into Claude Code:no extra dependencies, no API costs for the memory layer itself.
CLAUDE.md
CorePermanent instructions injected at three levels: global (~/.claude/CLAUDE.md), project (./CLAUDE.md), and local (.claude/CLAUDE.md). The primary persistence layer for all Claude Code users.
- Global → Project → Local merge order (additive)
- @path/to/file.md imports for modularity
- 200-line limit per file for reliable attention
- ETH Zürich finding: developer-written +4% adherence vs LLM-generated -3%
Auto Memory
v2.1.59+Claude writes its own MEMORY.md across sessions without manual calls. Uses a file-based memory system at .claude/memory/MEMORY.md per project, or ~/.claude/projects/{path}/memory/ globally.
- 200-line / 25 KB per file hard limit
- Four memory types: user, feedback, project, reference
- Per-project or global scope via settings.json
- Replaces manual 'remember X' patterns
Auto Dream
CommunityBackground sub-agent that consolidates memory after ≥5 sessions AND ≥24h. Community-discovered, not officially documented. Runs a 4-phase cycle: Orient / Gather / Consolidate / Prune.
- Triggers: ≥5 sessions + ≥24h gap (both required)
- 4-phase: Orient → Gather → Consolidate → Prune
- Merges duplicates, removes stale entries
- No configuration:fully automatic
Agent Memory
v2.1.33+Frontmatter field `memory: user|project|local` in agent definition files. Injects up to 200 lines of the corresponding MEMORY.md at agent startup.
- Three scopes: user (global), project, local
- Injected before any user message
- Works with Auto Memory output
- Defined in .claude/agents/agent.md frontmatter
Cross-Session Tools
Six community tools that persist memory beyond what the native stack offers. Each uses a different retrieval model:choose based on what you need to remember.
| Tool | Approach | Storage | Cost | Recall | Install |
|---|---|---|---|---|---|
| claude-mem ★ 26.5K | Hooks-based auto-capture | SQLite + optional Chroma | ~$5-15/month (API calls) | 3-layer disclosure | bun worker port 37777 |
| agentmemory ★ 16K | BM25 + Vector + Graph RRF fusion | Local (SQLite + FAISS) | Free (local) | 95.2% R@5 LongMemEval-S | pip install agentmemory |
| ICM | Episodic decay + permanent graph | SQLite + semantic index | Free (local) | Dual: Memories + Memoirs | brew install icm |
| Kairn | Biological decay model | Local graph DB | Free (local) | ~200d solutions, ~50d workarounds | npm install kairn |
| doobidoo | MCP server | SQLite-vec (default) | Free (local) | Vector similarity | npx doobidoo |
| OpenMemory MCP | MCP server (Mem0 AI) | Local or cloud | Free tier available | Semantic search | claude mcp add mem0 |
Start with: claude-mem if you want automatic capture with no manual calls and can afford ~$5-15/month in API costs. agentmemory if you want local-only with the highest benchmark recall (95.2% R@5 on LongMemEval-S). ICM if you need both episodic memory and a typed relation graph (brew install icm).
Known issue (doobidoo): concurrent access errors under parallel agents:fix with busy_timeout=15000 in config.
Team + Multi-Agent Sharing
Sharing memory across developers or autonomous agents is the hardest problem. Structural reasons:no standardized conflict-resolution protocol across tools:mean no current solution handles all cases cleanly.
Multi-Agent Concurrent Writes
When multiple agents write to the same memory store, you need coordination. The standard pattern: lease acquisition before write, signal-based invalidation on conflict, bounded retry with exponential backoff. No current tool implements this natively:it requires application-level wrapping.
Multi-agent memory patterns →Decision Framework: Which Track?
Six rules that cover 90% of real situations. Each maps a concrete problem to the right solution layer.
The full guide includes a Mermaid decision flowchart covering edge cases: offline constraints, security requirements, data sensitivity, and multi-agent coordination.
Full decision flowchart →Key Risks
Memory systems introduce attack surfaces and failure modes that don't exist with stateless contexts.
Memory Poisoning
An adversarial input causes the agent to store false beliefs in its memory store. On subsequent sessions, those beliefs influence behavior. No current tool implements write validation or anomaly detection.
Details →Context Inflation
Memory retrieval injects tokens at session start. If retrieval is poorly tuned, you can end up with more context tokens from memory than from the actual task:degrading adherence.
Stale Beliefs
Memories stored months ago may reflect outdated codebase state, team conventions, or user preferences. Decay models (Kairn, ICM) partially address this:flat storage (CLAUDE.md, doobidoo) does not.
Storage Fragmentation
Each tool uses its own storage format. Migrating from claude-mem to ICM, or from CLAUDE.md to Mem0, has no standard export path. Lock-in is mild (stores are local files) but migration is manual.
Full Reference in the Guide
The complete guide page covers installation instructions, configuration examples, architecture deep-dives for each tool, a full benchmark comparison (LongMemEval-S / LongMemEval-M), the Mermaid decision flowchart, open problems, and five named architecture patterns.