Analyzed: March 31, 2026 leak snapshot
The memory system is not a generic vector database bolted onto the product. It is a file-backed memory layer with explicit path controls, type taxonomy, and prompt-side operating rules.

​
What “memory” means in this codebase

Claude Code’s memory system is file-oriented. The source under src/memdir/ shows a design built around:
  • a memory directory on disk
  • MEMORY.md as the main entrypoint
  • typed memory files and daily logs
  • selective retrieval of relevant memories for a given query
This is much more concrete than “the model remembers things.”

​
Memory enablement

src/memdir/paths.ts makes the auto-memory gate explicit. Auto-memory can be disabled by:
  • CLAUDE_CODE_DISABLE_AUTO_MEMORY
  • bare mode via CLAUDE_CODE_SIMPLE
  • remote mode without a persistent memory directory
  • settings that turn off autoMemoryEnabled
If none of those disable paths apply, auto-memory is on by default.

​
Path resolution model

The memory directory resolution order in source is:
  1. CLAUDE_COWORK_MEMORY_PATH_OVERRIDE
  2. trusted autoMemoryDirectory settings sources
  3. default per-project path under the Claude config home
The default path shape is derived from a sanitized project root and lands under a memory/ directory. MEMORY.md inside that directory is treated as the entrypoint file.

​
Security constraints around memory paths

The memory path logic is unusually defensive. Examples visible in src/memdir/paths.ts and src/memdir/teamMemPaths.ts:
  • reject relative paths
  • reject near-root and drive-root paths
  • reject UNC paths
  • reject null bytes
  • reject dangerous ~/ expansions that would collapse to home or a parent
  • resolve symlinks when validating team-memory writes
This is not cosmetic hardening. Memory paths can become implicit read and write roots, so path mistakes would become privilege mistakes.

​
Memory taxonomy

src/memdir/memoryTypes.ts defines four memory types:
  • user
  • feedback
  • project
  • reference
The code also includes detailed prompt-side guidance for what belongs in each category and, just as importantly, what should not be stored at all.

​
What the code explicitly says not to save

The memory prompt guidance excludes several common-but-bad categories:
  • code patterns and architecture that can be re-derived
  • git history
  • debugging recipes already captured in code and commits
  • anything already in CLAUDE.md
  • ephemeral task details
That is a strong signal about the intended system: memory is supposed to retain non-derivable context, not duplicate the repository.

​
Relevant-memory retrieval

The retrieval path in src/memdir/findRelevantMemories.ts is straightforward:
  1. Scan memory file headers.
  2. Exclude files already surfaced.
  3. Ask a side-query model to select the most relevant files.
  4. Return up to five matching memory files.
The selector prompt is tuned to be conservative and to avoid surfacing generic tool reference docs when the agent is already using those tools.

​
Retrieval model choice

The relevant-memory selector uses a side query on the default Sonnet model, not the main loop model. That is a practical pattern throughout the codebase:
  • main model for the session’s main work
  • smaller or separate model calls for support tasks such as selection and estimation

​
Team memory

The codebase also includes a team-memory layer under src/memdir/teamMemPaths.ts. It lives as a subdirectory of the auto-memory directory and has its own path validation rules. Team memory is gated separately and depends on auto-memory being enabled first. The path-validation code is clearly security-driven:
  • sanitize keys
  • reject traversal and encoded traversal
  • reject Unicode normalization attacks
  • resolve deepest existing ancestors
  • block symlink escapes
This is one of the stronger indicators that the authors expected hostile or at least untrusted path inputs somewhere in the flow.

​
Mental model

The memory system has three distinct jobs:
  • persist durable context to files
  • inject stable memory entrypoints into prompt context
  • retrieve a small number of relevant memory files for the current task
That is narrower and more disciplined than a generic “long-term memory” marketing claim.