Claude Code Memory Guide

How to make Claude Code actually remember what matters — without you being the memory manager. April 2026. Source-code-verified.

The Core Problem A fresh Claude Code instance loads your CLAUDE.md and MEMORY.md index, but does not intelligently route to the right memory files based on your task. You end up telling it "read X.md" every session — when the harness should handle this automatically. This guide maps the problem and the solutions.

Guide Sections

1. How Memory Actually Works

The loading chain, memory selection agent (Sonnet), auto-memory, dream consolidation, and what the harness controls. Source-code-verified internals.

2. The Memory Routing Problem

Why loading everything is worse than loading nothing. Approaches from keyword matching to semantic search to LLM re-ranking.

3. Hooks, Rules & Automation

All 27 hook events, path-scoped rules, context injection patterns, MCP memory servers. Practical recipes you can copy.

4. How Other Tools Do It

Cursor, Windsurf, Copilot, Aider, Continue, Cline/Roo, Codex CLI, Amazon Q, Zed — their memory and context approaches compared.

5. Best Practices & Recipes

Concrete patterns: structuring CLAUDE.md, writing good MEMORY.md entries, SessionStart hooks, path-scoped rules, and a phased improvement plan.

6. Source Code Reference

Hard-coded constants, complete data flow, system prompt assembly order, feature gates, and key source file locations.

Key Findings

Loading everything is worse than loading nothing Research from Harvard's D3 Institute shows indiscriminate memory loading degrades LLM performance. Bad or irrelevant memories create a "propagating error feedback loop." 3-5 memories is the sweet spot.

Claude Code has a memory selection agent A Sonnet sub-agent selects up to 5 memory files per query by matching filenames and one-line descriptions. But it operates on metadata only — no semantic search. And behavioral rules (feedback memories) have no routing mechanism beyond this.

The fix is a pipeline, not a single technique Always-on rules in CLAUDE.md + path-scoped rules (harness-enforced) + SessionStart hooks (keyword matching) + optional MCP semantic search. Each layer catches what the previous one misses.