Claude Code 3-Layer Memory Architecture: What 512K Lines of TypeScript Revealed

When 512K lines of Claude Code's TypeScript source leaked, most people focused on the model interactions. The engineers who paid attention focused on something else: the memory architecture. It's elegant, model-agnostic, and directly applicable to any agentic system you're building.

The key insight from the codebase: If it can be looked up, it shouldn't be remembered.

The 3-Layer Architecture

Layer 1: MEMORY.md (Always Loaded)

The foundation of Claude Code's memory system isn't a database or an embedding store. It's a lightweight markdown file — MEMORY.md — that's injected into every context window automatically.

The design constraints:

• It's an index, not storage — each line is a pointer to where information lives, not the information itself. Think: Table of Contents, not the Book.
• Each line under 150 characters — enforcing brevity ensures the index stays useful as context grows
• First 200 lines injected into context — only the top of the file is always active; the rest is available for lookup

This design makes the always-on context tiny. No bloat. No wasted tokens on information the agent doesn't need right now.

Layer 2: Topic Files (On-Demand)

When MEMORY.md indicates that a topic is relevant, the agent loads the corresponding topic file. These are separate .md files — one per topic — containing:

• Architecture decisions and their reasoning
• Team conventions and code style rules
• Slash commands and their behavior
• Project-specific context

Critically: these files are loaded ONLY when MEMORY.md says they're relevant. An agent working on a frontend bug doesn't load the backend architecture docs. Token efficiency by design.

Layer 3: Raw Transcripts (Grep Search)

Past sessions are never fully reloaded. Instead, when historical context is needed, the agent searches raw session transcripts using grep for specific IDs or patterns. No embeddings. No vector database. Just grep.

This is the simplest possible implementation of episodic memory — and for a coding agent, it's the right call. Code artifacts, function names, and session identifiers are highly searchable as text. The overhead of maintaining a vector database for this purpose would outweigh the benefit.

The Skeptical Memory Pattern

One detail from the leaked codebase that deserves special attention: Claude Code treats its own memory as a hint, not a fact.

When memory says a function exists → verify against the codebase first.

When memory says a file is at /path → check before using.

This is sophisticated and correct. Memory can be stale. Memory can be wrong. Memory can reflect a state of the codebase that no longer exists. The agent that trusts its memory implicitly will confidently reference functions that have been deleted.

The pattern: use memory to guide where to look, then verify what you find. Never assume memory is current.

The Design Principles (Steal These)

1. Always-loaded context should be tiny — index, don't store. The full information lives elsewhere; the pointer lives in context.
2. Reference via pointers — MEMORY.md points to topic files; topic files point to actual code. Don't duplicate.
3. Never persist what can be looked up — if a fact can be retrieved from the codebase in one grep command, it shouldn't consume a permanent memory slot.
4. Memory = hint, not truth — any system that treats its stored memory as ground truth will eventually confidently state something false.

This pattern is model-agnostic. It works with Claude, GPT, Gemini — any LLM that has a context window. And it scales: hundreds of topic files can exist without affecting the context overhead of any single interaction.

Jason Newell is an AI practitioner, builder, and writer covering agentic systems, developer tooling, and the future of AI engineering.