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. Knowing whether the memory is actually used decides whether it is worth keeping.
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.
Advanced01 / Memory types
Memory types: coordinates, not a stack
Popular diagrams stack five layers (working, episodic, semantic, procedural, "meta-memory") and pair each with a brain region. The research literature classifies memory on independent axes instead, and one artifact has a value on every axis.
| Axis | Values | Claude Code example |
|---|---|---|
| Content | Working state, episodes, facts, procedures, reference documents | MEMORY.md holds facts; a skill holds a procedure |
| Form | Context tokens, files, database or graph, model weights | CLAUDE.md is a file that becomes context tokens at load |
| Scope | Turn, session, machine, repository, team service, organization, agent fleet | Auto memory is tied to a repository yet stays on one machine |
| Lifecycle | Write, retrieve, consolidate, supersede, forget | Compaction rewrites working state; Auto Dream consolidates |
"Meta-memory" is the wrong word for housekeeping. In psychology it means monitoring your own remembering. Retention, deduplication and decay are memory management.
Storage choices are not definitions. Episodic memory does not have to be append-only, and procedural memory is not only a skill registry: instructions, code and model weights count too. Treat brain-region pairings as an analogy, not anatomy.
Where memory lives: local, repository, shared
"Tied to the project" does not mean "shared with the team". Each row was read in the vendor's documentation on Nov 3, 2026.
| Mechanism | Scope | Shared how | Lifecycle |
|---|---|---|---|
| Claude Code auto memory | One machine, every worktree of the repository | Not across machines or cloud | Stays until edited or deleted |
| Claude Code subagent memory: | user, project or local | project scope can be committed | Inert when auto memory is off |
| Managed CLAUDE.md | Organization-managed machines | Deployed by administrators | Guidance, not enforcement |
| Codex memories | Local store under ~/.codex | Separate from ChatGPT memory | Off by default, updated in the background |
| Gemini CLI Auto Memory | Local transcripts | Drafts patches and SKILL.md for review | Experimental, never applied without approval |
| GitHub Copilot Memory | Repository | Facts shared with collaborators, cited to code | Expire after 90 days unless upvoted |
| Kiro memory | Local user account | IDE and CLI on one machine | Not documented |
Two designs dominate. Claude Code, Codex and Gemini CLI keep learned memory on one machine and share only files people curate (CLAUDE.md, AGENTS.md, skills). Copilot shares learned repository facts with the team and compensates with code citations, write-access gating and expiry. Neither spreads one person's learned memory to a team by accident.
02 / Native stack
Native 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. Tied to the repository, but machine-local: all worktrees of one repository share one memory directory, and nothing syncs across machines or cloud environments.
- 200-line / 25 KB index limit
- Shared by every worktree of the same repository
- Excluded from transcript cleanup: stays until edited or deleted
- 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
- Not in official docs or the changelog (checked Nov 3, 2026)
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
- Project scope lives in .claude/agent-memory/ and can be committed
- Inert when auto memory is disabled
03 / Cross-session
Cross-session tools
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. Facts for claude-mem and agentmemory were read at their release tags (v15.9.0 and v0.9.31).
| Tool | Approach | Storage | Cost | Recall | Install |
|---|---|---|---|---|---|
| claude-mem β 111K | 9 hook events + LLM observer; injects the newest 50 observations at session start | SQLite + Chroma (on by default) | Your Claude subscription by default | Smart 3-step search | /plugin install claude-mem |
| agentmemory β 30K | 12 hooks capture; injection opt-in; BM25 + Vector + Graph RRF | iii file store or Redis | Zero LLM by default | 95.2% R@5 LongMemEval-S (self-reported) | npm i -g @agentmemory/agentmemory |
| memorix β 896 | One memory pool across ~18 coding agents, MCP + optional hooks | SQLite, scoped to a project by Git identity | Free (local) | Consolidation and retention from a dashboard | memorix setup --agent <name> |
| basic-memory β 4.5K | Plain Markdown you can edit, Claude Code plugin hooks | Markdown + SQLite index | Free locally; paid cloud for teams | Hybrid search | See the project README |
| 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 | pip install kairn |
| doobidoo β 2.1K | MCP + REST server, Codex hooks | SQLite-vec (default) | Free (local) | Vector similarity | pip install mcp-memory-service |
| OpenMemory MCP | MCP server (Mem0 AI) | Local or cloud | Free tier available | Semantic search | claude mcp add mem0 |
Star counts verified Nov 3, 2026 via the GitHub API.
Start with: claude-mem if you want automatic capture that is injected at every session start. agentmemory if you want local-only hybrid retrieval and are ready to opt in to injection (AGENTMEMORY_INJECT_CONTEXT=true); without it, the agent only pulls memory through MCP. memorix if several coding agents on one machine should share one project memory. ICM if you need both episodic memory and a typed relation graph (brew install icm).
claude-mem, read before installing: secret redaction is off by default (CLAUDE_MEM_REDACT_ENABLED). From v15.2.0 to v15.8.2, the browser setup uploaded the last 30 days of prompts to cmem.ai without asking; v15.8.3 (Nov 2, 2026) fixed it.
Known issue (doobidoo): concurrent access errors under parallel agents: fix with busy_timeout=15000 in config.
04 / Team sharing
Team + multi-agent sharing
Sharing memory across developers or autonomous agents is the hardest problem. Structural reasons, primarily the lack of a 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 →Is your memory used? From captured to effective
Each step can fail without raising an error. Most tools and benchmarks stop at "retrievable": they check that the right item comes back, not that the agent used it.
- captured
- stored
- indexed
- retrievable
- injected
- effective
What a 2026 measurement found
MemUse (arXiv 2611.01718, a November 2026 preprint) followed memory delivered in 8,000 SWE-bench Verified episodes from three memory systems. Resolve rates stayed within 0.4 points of a no-memory baseline. Most delivered entries were irrelevant, most relevant entries went unused, and in two systems most deliveries repeated what the agent could already see. One preprint does not settle every workload; it does justify testing your own.
Before adopting or keeping a memory layer: count items at each stage, plant a canary (write one synthetic observation, open a fresh session or another agent, check it comes back in the right scope and nowhere else), then run your own tasks with memory on and off. Among the tools above, only Graft publishes such an A/B, on 15 questions.
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 →05 / Risks
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 or instructions in its memory store. On later sessions, they influence behavior. 2026 preprints (MemGhost, MemHarmBench) show agents completing legitimate tasks normally while following the planted intent. Write validation is still not a default anywhere.
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.