Claude Code memory is a layered system — CLAUDE.md files you write and auto-memory Claude keeps itself — that carries project knowledge across sessions that would otherwise start blank.
Large language models are stateless by design: every session is a fresh API call with an empty context window. Claude Code starts each one as a clean whiteboard, with no record of last night's debugging, your architectural decisions, or your naming conventions. The memory system exists to close that gap.
Getting it right removes the "Repetition Tax" — the tokens and attention you burn re-establishing your job, your project rules, and your environment in every new terminal session. Instead of one sprawling instruction file, Claude Code splits memory into two layers: the fixed rules you write (CLAUDE.md) and the lessons Claude accumulates (auto-memory).
For an engineer, understanding each layer's precedence and physical limits is what separates a memory setup that steers the agent from one that quietly drifts out of date.
Why does each Claude Code session start with no memory?
Every Claude Code session is bounded by a context window, and at startup that context is empty.
Rebuilding it by hand each time is the "Repetition Tax": you spend tokens and focus retyping
constants like "this project uses TypeScript" or "API handlers live in src/api".
This is not a limit you beat by pasting more into the top of each session. The fuller the context window, the less room is left for the model to reason about the complex code tasks that follow — manually stuffing context erodes the quality of what comes back.
So Claude Code needs an automatic briefing: it loads the infrastructure facts (build commands, directory layout, conventions) at startup and keeps temporary conversation memory separate from stable long-term memory. That separation is what lets Claude respond consistently no matter which session of the project you are on.
Two memory systems: CLAUDE.md and auto-memory
You need to separate instructions (rules you write) from lessons (state Claude accumulates). Both load at the start of every conversation as context — not as hard-enforced configuration. To block an action regardless of what Claude decides, reach for a hook, not a CLAUDE.md line.
| Feature | CLAUDE.md | Auto-memory |
|---|---|---|
| Nature | Behavioral rules (you write) | Accumulated lessons (Claude writes) |
| Content | Rules, standards, project layout | Working build commands, fixed bugs, prefs |
| Scope | Project, user, or org | Per repository, shared across worktrees |
| Loaded into | Every session, in full | First 200 lines or 25KB of the index file |
CLAUDE.md is the project's constitution: what Claude must do. Auto-memory is more like a running logbook, letting Claude recognize patterns it has hit before so it does not repeat old mistakes. Use CLAUDE.md when you want to steer behavior; let auto-memory distill what it learns from the corrections you give it. For the wider picture of how CLAUDE.md, rules, skills, and hooks work together to steer Claude, see Claude memory files and how they steer Claude.
