Memory & Context

Claude Code has no memory between sessions except the files you give it. Everything in those files loads every turn, so memory is a running tax on the context window: useful context costs you the same budget as dead weight. The skill is keeping the right things present and the rest out.

Two clocks run at once. Across sessions, persistence lives in files (CLAUDE.md, auto-memory, state files on disk). Within a session, the live context window fills up and eventually gets compacted, and you have some control over what survives. Most "Claude forgot" pain is one of these two clocks being managed badly.

The layers

Layer	What it is	Lifespan	Loaded
Project CLAUDE.md	repo standing orders, committed	with the repo	every turn
User CLAUDE.md (~/.claude)	personal rules across all repos	your machine	every turn
Auto-memory (MEMORY.md)	facts the agent saved for itself	your machine	every session, in full
Context window	the live conversation	this session	live
State files on disk	durable loop or task state	as long as you keep them	read on demand

The first three are the running tax (loaded whether or not you use them). The last two are pay-as-you-go.

The building blocks

CLAUDE.md. The file Claude reads at the start of every session. Project-level (repo root, committed) sets rules for everyone; user-level (~/.claude/CLAUDE.md) sets your personal rules across repos. They stack, global first then project, so a project can override your defaults. Highest-ROI entries: quick-start and test commands, non-obvious patterns, and critical rules marked IMPORTANT or YOU MUST (emphasis measurably improves adherence). Seed it mid-session by pressing #. See Memory & CLAUDE.md.

/memory. Edits your CLAUDE.md memory files and controls auto-memory from inside a session, so you do not have to open the files by hand.

Auto-memory (MEMORY.md). Files the agent maintains for itself. The index loads in full every session, so cap its size and keep one fact per entry. (As a reference point, a well-run MEMORY.md index stays around 200 lines; past that it starts crowding out real work.)

/compact [instructions]. Directed compaction. When the window fills, you steer what survives: /compact focus on the API changes keeps your working set instead of a generic summary. This is the single most useful long-session move.

The context window itself. Quality starts to degrade once the window is heavily full. A subagent runs in its own fresh window, which is why delegating a noisy task (a broad search, a large refactor) resets the clock for your main thread.

Subagent inheritance. A spawned subagent inherits your CLAUDE.md, skills, and MCP servers, but not your conversation history. It starts cold on the discussion, so brief it explicitly. This is why CLAUDE.md quality matters more, not less, once you delegate.

State files. For loops and detached work, memory lives on disk: a state.json the run reads at the top and writes at the bottom. A fresh firing has no history, so the file is its memory. See Loops & Autonomy.

Decide: where does this belong?

The thing	Put it in
A rule everyone on the repo should follow	project CLAUDE.md (commit it)
A personal habit across all your repos	user CLAUDE.md
A fact the agent should recall next session	auto-memory (MEMORY.md), one fact per entry
A large reference the agent needs sometimes	a skill or a doc it can open on demand, not CLAUDE.md
State a loop must carry between firings	a state.json on disk

The trap is putting "sometimes" knowledge in CLAUDE.md, where you pay for it every turn. If it is not needed most turns, it belongs somewhere the agent opens on demand.

Recipes

1. A lean CLAUDE.md. Commands first (install, dev, test, lint), then non-obvious patterns, then critical rules with IMPORTANT / YOU MUST. Iterate it like a prompt: add one rule, watch whether behavior changes, prune anything that does not earn its line.

2. Seed a rule mid-session. When you correct Claude on something it should always do, press # and it writes the rule into CLAUDE.md instead of forgetting it after the turn.

3. Directed compaction on a long refactor.

/compact focus on the auth refactor: the new token flow and the files still to migrate

You keep the working set; the rest gets summarized away.

4. Multi-tier memory. Standing rules in CLAUDE.md, evolving facts in MEMORY.md (one per entry, linked), deep reference in skills or docs the agent opens when needed. Each tier has a different load cost, so match the thing to the tier.

5. Reset context with a subagent. Before a broad search or a large generated dump, delegate it to a subagent and keep only the conclusion. Your main window stays clean.

Failure modes

• Bloated CLAUDE.md. Every line is a prompt you pay to send on every request. A fat file degrades context availability for actual work. Prune aggressively.
• Assuming default memory persists. Nothing carries between sessions unless it is in a file. If you want it next time, write it down (or press #).
• Losing your working set at auto-compaction. The automatic summary is generic. On a long session, run a directed /compact before the window forces one on you.
• Subagent amnesia. Delegating without a brief, then expecting the subagent to know what you discussed. It does not inherit history; spell out the task.
• Stale rules. A CLAUDE.md rule that no longer changes behavior is dead weight. Test whether removing it changes output; if not, cut it.

Quick reference

You want	Reach for
Standing rules, loaded every turn	CLAUDE.md (project + user)
Save a rule without leaving the chat	# or /memory
Recall a fact next session	MEMORY.md, one fact per entry, keep it lean
Keep your working set when the window fills	/compact <instructions>
Free up the main context	delegate to a subagent
Carry state across loop firings	state.json on disk

Lean cheat: if it is not needed most turns, it does not belong in CLAUDE.md. Load on demand instead.

The commands above have a quick-reference card at Context management.