Claude Code Memory Files Explained

Anthropic’s March 2026 source code leak revealed something unexpected: the memory infrastructure powering Claude Code is more sophisticated internally than anything exposed to users. The leak uncovered a three-tier memory system with compression pipelines and consolidation strategies designed to prevent bloat — yet users still hit a hard 200-line cap on the file that matters most. That gap between internal architecture and user-facing capability defines the current state of Claude Code memory, and it tells you a lot about where the product is heading.

How Claude Code Memory Actually Works

Claude Code’s memory system operates through four distinct layers, but only two of them are meaningfully visible to developers. The foundation is CLAUDE.md — a static instruction file you write and maintain. Alongside it runs Auto Memory, a subsystem where the model writes its own session learnings to ~/.claude/projects/ /memory/ without requiring manual note-taking, enabling Claude Code’s ability to remember learnings between sessions.

The MEMORY.md file serves as the always-loaded index, but only the first 200 lines or 25 KB are read into context at session start, whichever limit is hit first. When a project’s accumulated memory exceeds that threshold, the system encourages breaking content into separate topic files — debugging.md, api-conventions.md, patterns.md — and using MEMORY.md as a concise pointer index. Claude reads both MEMORY.md and topic-specific files through standard file tools, not semantic vector retrieval. That distinction matters: there’s no embedding-based search, no fuzzy matching. If the index doesn’t point to the right file, the model doesn’t see the content.

Auto Memory is enabled by default. Developers can toggle it via the /memory command, disable it globally through settings, or override it with the CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 environment variable for CI pipelines, as part of Claude Code’s auto memory system. The system is designed to save patterns that prove useful across multiple interactions — project conventions, key commands, debugging approaches, user preferences — while avoiding one-time information, duplicates of existing CLAUDE.md instructions, or speculative conclusions drawn from reading a single file, following its selective retention rules.

The Four CLAUDE.md Scopes

Per Anthropic’s documentation, CLAUDE.md files support four scopes: managed policy (organization-wide instructions at machine-level paths like /Library/Application Support/ClaudeCode/CLAUDE.md on macOS), user instructions (~/.claude/CLAUDE.md), project instructions (./CLAUDE.md or ./.claude/CLAUDE.md), and local instructions (./CLAUDE.local.md), as documented for these four CLAUDE.md file scopes.

The hierarchy is deliberate. Managed policy sits at the top — IT or DevOps pushes rules that apply to every session on every user’s machine. User scope carries personal preferences across all projects. Project scope holds conventions specific to a codebase. Local scope captures directory-level overrides without committing them. All four load together and merge, so your personal preferences combine with project-specific rules without conflict.

For most individual developers, the user and project scopes are where the action is. The user-level file is the native cross-project layer for personal preferences — “always use pnpm, not npm,” “prefer functional components,” “write tests in Vitest.” The project file is your team’s shared constitution. If you’re working across multiple machines and re-explaining the same conventions every morning, you’re leaving value on the table.

What the Source Code Leak Revealed

The March 2026 leak — triggered when Anthropic published version 2.1.88 with an exposed source map file — revealed that Claude Code’s internal memory architecture is a three-tier structure: (1) a MEMORY.md index that’s always loaded but contains only pointers, (2) Markdown memory files called only when needed, and (3) JSON transcript files that log file changes but are never loaded into active context, as detailed in the March 2026 Claude Code source code leak.

That third tier is the one users never see. JSON transcripts record what files changed during a session, but they sit outside the context window — searchable in theory, invisible in practice. The leak also exposed a three-stage memory compression strategy: truncating cached tool outputs locally, generating a structured 20,000-token summary of the most recent session when approaching context limits, and compressing the entire conversation as a last resort, per the leak that exposed this three-stage memory compression strategy.

Here’s the tension: the internal system is engineered to prevent bloat. Compression pipelines run automatically. Transcripts are kept out of active context. And yet the user-facing constraint remains a flat 200-line, 25 KB cap on MEMORY.md with no configurable override. A GitHub feature request (#28276) proposing a memoryDirectory setting to enable cross-machine sync and team-shared memory remains open as of June 2026. The workaround is manual: rsync ~/.claude/projects/*/memory/ between machines, or duplicate content into CLAUDE.md where it counts against your context budget.

The Memory-Action Asymmetry

What I call the Memory-Action Asymmetry is this: Claude Code’s agentic execution capabilities — nested sub-agents up to 5 levels deep, background agents, sandbox execution, MCP server integration — increasingly outpace its memory infrastructure, which remains constrained to a filesystem-based, 200-line index with no semantic search or cross-machine sync. The product markets itself as an agent that learns. The reality is an agent that learns within a single machine, single session boundary, and then forgets everything that doesn’t fit in a Markdown file.

The June 2026 release cadence makes this gap more visible. Safe Mode shipped in the v2.1.169 release, with nested sub-agents up to 5 levels deep following in the v2.1.172 release, /rewind and a 37% CPU reduction in streaming landing in the v2.1.191 release, and artifacts arriving as a separate June 18 update. The same releases fixed MCP config collision crashes, background agents resurrecting after stop, 1M-context sessions getting permanently stuck, and OAuth token refresh deadlocks. ReleaseBot’s documentation of these fixes The agentic architecture is still fighting foundational reliability issues while simultaneously shipping features that demand more from memory than the memory layer can deliver.

Consider the artifacts feature, shipped June 18. Artifacts turn live coding sessions into shareable HTML dashboards and incident reports visible to authenticated teammates. It’s a genuinely useful collaboration tool. But it also highlights the memory gap: artifacts are org-shared and persistent, while Auto Memory remains siloed per-machine at ~/.claude/projects/ with no built-in team-sharing mechanism. If your team wants shared learnings, you’re back to duplicating content into CLAUDE.md — the one channel that does propagate.

Practical Configuration Patterns

The /init command initializes project memory by creating a CLAUDE.md file in the project directory. Setting CLAUDE_CODE_NEW_INIT=1 enables an enhanced interactive setup flow that walks through project configuration step by step, as documented in the claude-howto memory guide. For ongoing management, the /memory command opens memory files in your editor for bulk updates.

A few operational notes: the # prefix for quick single-line memory additions has been discontinued. Use /memory or ask conversationally instead. Auto Memory organizes entries semantically by topic rather than chronologically, and Claude is expected to update or remove entries that prove outdated — though how reliably it does this in practice varies.

For teams managing multiple AI coding tools, there’s a broader configuration strategy worth considering. The three dominant formats — AGENTS.md, CLAUDE.md, and Cursor rules — can be organized in a layered architecture with AGENTS.md as the cross-tool source of truth, as we covered in our guide to Claude Code Skills, Cursor Rules, AGENTS.md: AI Agent Config. That approach minimizes duplication and cuts token costs when your team uses more than one AI assistant.

When Native Memory Isn’t Enough

The native system works well for single-developer, single-machine workflows with moderate context needs. It breaks down when you need cross-machine sync, team-shared semantic memory, or retrieval across large knowledge bases. At that point, you’re looking at external memory backends — vector databases, RAG pipelines, or platforms like the Managed Agents API where memory mounts directly to a filesystem but supports scoped permissions and audit logs.

The Managed Agents approach is instructive: Anthropic’s own enterprise offering uses filesystem-based memory with shared stores and per-agent access scopes. That’s the architectural direction. The consumer Claude Code product just hasn’t caught up yet.

For now, the honest assessment is this: Claude Code’s memory system is a solid v1. It solves the “re-explain everything” problem well enough for individual use. But if you’re operating at team scale, across machines, or with automation that requires persistent shared context, you’ll hit the ceiling quickly — and the workaround is still rsync.