Skip to main content
NOV 2026 New identity Latest guide updates. Latest: AI Design Patterns Local vs cloud AI Grill me Changelog →
Claude Code

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-in
πŸ”„

Cross-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.

Community
πŸ‘₯

Team + multi-agent

Sharing memory across developers or autonomous agents. The Trinity (zero infra), Mem0 Cloud, Zep/Graphiti. Concurrent-write coordination via leases and signals.

Advanced
Concepts

01 / 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.

AxisValuesClaude Code example
ContentWorking state, episodes, facts, procedures, reference documentsMEMORY.md holds facts; a skill holds a procedure
FormContext tokens, files, database or graph, model weightsCLAUDE.md is a file that becomes context tokens at load
ScopeTurn, session, machine, repository, team service, organization, agent fleetAuto memory is tied to a repository yet stays on one machine
LifecycleWrite, retrieve, consolidate, supersede, forgetCompaction 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.

Sources and details in the guide →
Scope

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.

MechanismScopeShared howLifecycle
Claude Code auto memoryOne machine, every worktree of the repositoryNot across machines or cloudStays until edited or deleted
Claude Code subagent memory:user, project or localproject scope can be committedInert when auto memory is off
Managed CLAUDE.mdOrganization-managed machinesDeployed by administratorsGuidance, not enforcement
Codex memoriesLocal store under ~/.codexSeparate from ChatGPT memoryOff by default, updated in the background
Gemini CLI Auto MemoryLocal transcriptsDrafts patches and SKILL.md for reviewExperimental, never applied without approval
GitHub Copilot MemoryRepositoryFacts shared with collaborators, cited to codeExpire after 90 days unless upvoted
Kiro memoryLocal user accountIDE and CLI on one machineNot 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.

Sources per vendor →
Track 1

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

Core

Permanent 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%
Full details in guide →

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
Full details in guide →

Auto Dream

Community

Background 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)
Full details in guide →

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
Full details in guide →
Track 2

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.

Track 3

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.

The Trinity

Zero infra

Commit CLAUDE.md + .mcp.json + /skills to the repo. Any developer who clones gets the full memory state immediately: no server, no account, no sync step.

Best when: Team with shared conventions, no infra budget
Full details →

Mem0 Cloud MCP

Free tier

Shared memory pool accessible to all team members via MCP server. One-command install, optional self-host. Works across sessions and users.

Best when: Small team needing shared context without self-hosting
Full details →

Zep / Graphiti

Advanced

Temporal knowledge graph with bitemporal edge windows: tracks not just what was true, but when it was true and when it was learned.

Best when: Complex projects where history and causality matter
Full details →

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 →
Evidence

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.

  1. captured
  2. stored
  3. indexed
  4. retrievable
  5. injected
  6. 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.

Pipeline and 2026 usage benchmarks →

Decision framework: Which track?

Six rules that cover 90% of real situations. Each maps a concrete problem to the right solution layer.

If: Solo developer, CLAUDE.md covers the context
Native Stack: enable Auto Memory, costs nothing, zero setup
If: Re-explaining context every session wastes 10+ minutes
claude-mem or agentmemory: both auto-capture without explicit calls
If: Need causal chains: 'this bug caused that regression'
Kairn (biological decay) or ICM Memoirs (typed relation graph)
If: Team memory, zero infra budget
The Trinity: CLAUDE.md + .mcp.json + skills committed to repo
If: Team memory, okay with a lightweight cloud service
Mem0 Cloud MCP: free tier, one-command install
If: Several coding agents on one machine should share what they learn
memorix: one project pool across Claude Code, Codex, Cursor and others
If: Multi-agent pipeline, concurrent writes
Lease + signal pattern on top of any persistent store
If: Before keeping any memory layer
Plant a canary, then run your own tasks with memory on and off

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.

High

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 →
Medium

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.

Medium

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.

Low

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.