Claude Code Memory Architecture (Reverse-Engineered)

Two independent reverse-engineering efforts revealed Claude Code's three-layer memory design. Combined engagement: 15,500 likes, 24,812 bookmarks. The definitive reference for how Claude Code manages persistent context.

The Three-Layer Design

Two researchers independently reverse-engineered Claude Code's memory system in late March 2026, arriving at the same architectural conclusions:

Layer 1: Index (Always Loaded)

A compact summary of what the agent knows - project structure, key decisions, active tasks. This loads into context on every session start. Small enough to fit in the system prompt window. Functions like a table of contents for the agent's memory.

Layer 2: Topic Files (On-Demand)

Detailed knowledge organized by topic. Loaded only when the current task matches the topic. Keeps the context window lean - the agent doesn't load everything it knows, just what's relevant. Similar to how Kevin's wiki uses qmd search to pull relevant pages rather than loading the entire wiki.

Layer 3: Transcripts (Grep-Only)

Raw conversation history. Never loaded into context directly. Searched via grep/ripgrep when the agent needs to recall a specific past interaction. The heaviest layer by volume, the lightest by context cost.

Key Mechanisms

autoDream - A background process that periodically rewrites the index and topic files based on new transcripts. The agent's memory consolidates itself without explicit user action. This is the "compile" step that turns raw signal into structured knowledge. Source: X/@himanshustwts, 2026-03-31

Staleness-first - The memory system prioritizes freshness. When conflicts exist between old and new information, the newer source wins. Stale entries get demoted or removed during autoDream cycles. Source: X/@iamfakeguru, 2026-03-31

The reviewed diagram makes the access paths concrete. Manual writes, per-turn extractMemories, and background autoDream write into ~/.claude/projects/.../memory/; MEMORY.md is always injected through the system prompt, topic files are read on demand through FileReadTool, and JSONL session transcripts stay grep-only. The operational point is bandwidth control: memory has a hot index, warm topic files, and cold transcripts, with consolidationLock.ts preventing background rewrites from racing each other. Source: local X image artifact, 2026-07-03

CLAUDE.md Loading Order

The @Hesamation bookmark captures the practical moat: the .claude folder is where taste, rules, skills, and workflows become persistent harness state. The local image diagrams the instruction stack as organization policy, user instructions, project instructions, and local project tweaks, all merged into the session prompt. Source: X/@Hesamation, 2026-03-21; Source: local image artifact, 2026-07-03

Anthropic's current docs make the operational distinction sharper. CLAUDE.md files are context instructions, not hard enforcement. The load path runs from managed organization instructions to user-level ~/.claude/CLAUDE.md, project CLAUDE.md or .claude/CLAUDE.md, and local CLAUDE.local.md; directory-level files are concatenated so instructions closer to the launch directory are read later. Settings have their own precedence model: managed policy, command-line overrides, local settings, project settings, then user settings. Use settings and hooks for hard controls, and use CLAUDE.md for behavioral guidance and project memory. Source: Claude Code memory docs, checked 2026-07-03; Source: Claude Code settings docs, checked 2026-07-03

Sources

Both efforts stem from the 2026-03-31 Claude Code Source Leak (the npm sourcemap exposure): this page covers the memory subsystem; the leak page covers the broader findings and debunks the viral "employee-gating bypass" claim.

@himanshustwts explored Claude Code's source code directly and published "the full technical recipe behind Claude Code's memory architecture" - 6,280 likes, 8,305 bookmarks. Focused on the implementation details: file structure, loading triggers, consolidation logic. Source: X/@himanshustwts, 2026-03-31

@iamfakeguru reverse-engineered the system by analyzing "billions of tokens of my own agent logs" against the leaked source - 9,220 likes, 16,507 bookmarks. Focused on the behavioral patterns: when memory loads, how staleness works, what triggers rewriting. Source: X/@iamfakeguru, 2026-03-31

Relation to Kevin's System

Kevin's wiki follows a structurally similar pattern, arrived at independently via the Karpathy LLM Wiki approach:

The parallel validates the design. Both systems converge on: compact always-on context, topic-scoped retrieval, and background consolidation.

---

Timeline

• 2026-07-03 | Deep-reviewed the @Hesamation .claude folder bookmark and aligned it with current Claude Code docs: CLAUDE.md is persistent context, while settings/hooks own hard enforcement. Source: raw/x-bookmarks/enriched/2035479614974275758.json; local image artifact; Claude Code docs, 2026-07-03
• 2026-07-03 | Deep-reviewed the local memory-architecture diagram and added the concrete write/read paths: manual write, extractMemories, autoDream, always-injected MEMORY.md, on-demand topic files, grep-only transcripts, and consolidationLock.ts. Source: X/@himanshustwts, 2026-03-31; Source: local image artifact, 2026-07-03
• 2026-03-31 | @himanshustwts published source-code-based analysis - 6,280 likes, 8,305 bookmarks. Source: X/@himanshustwts, 2026-03-31
• 2026-03-31 | @iamfakeguru published log-analysis-based reverse engineering - 9,220 likes, 16,507 bookmarks. Source: X/@iamfakeguru, 2026-03-31