Context Management

Context is a working set, not a storage layer. The context window holds everything Claude knows about the current session: your conversation history, file contents, command outputs, CLAUDE.md, auto memory, loaded skills, and the system instructions you never see in the terminal. Keep durable knowledge in files and keep the active session focused on the decision being made now.

Durable Context

Use files for information that must survive sessions. Each new session starts with a fresh context window and no conversation history from previous sessions, so anything that only lives in the chat transcript is gone once the session ends.

• CLAUDE.md for project rules. The project-root file loads at the start of every session and is re-injected after compaction, so it is the most reliable place for instructions that must persist.
• ADRs for architectural decisions.
• Test files for expected behavior.
• Issue or PR descriptions for task goals.
• Changelogs for release facts.

Claude can also save its own learnings between sessions in auto memory. The first 200 lines or 25KB of MEMORY.md (whichever comes first) load at the start of each session. Run /memory to check which CLAUDE.md and auto memory files loaded.

Do not rely on a long chat transcript as the only place where decisions live.

Compaction

When context fills up, Claude Code manages it automatically: it clears older tool outputs first, then summarizes the conversation if needed. Your requests and key code snippets are preserved, but detailed instructions from early in the conversation can be lost — another reason to put persistent rules in CLAUDE.md rather than relying on conversation history.

Auto-compaction triggers automatically as you approach the context limit (by default around 95% of capacity). You can lower this with the CLAUDE_AUTOCOMPACT_PCT_OVERRIDE environment variable, which sets the percentage (1–100) at which auto-compaction fires and applies to both the main conversation and subagents. Values above the default threshold have no effect.

For Sonnet 5 with a 1M context window, v2.1.247 moves automatic compaction to roughly 967k tokens instead of roughly 934k, and v2.1.260 moves Opus and Fable 1M sessions to compact shortly before the 1M limit as well. Treat the extra room as working space, not durable storage for decisions. Fable 5.1 keeps the 1M window as both default and maximum, and its $0.25/MTok cache reads make re-reading a large cached prefix a quarter as expensive as on Fable 5.

You can also compact manually:

• /compact replaces the conversation with a structured summary on demand.
• /compact focus on the API changes steers what the summary keeps.
• Add a "Compact Instructions" section to CLAUDE.md to control what is preserved every time.
• /clear resets context entirely — use it between unrelated tasks rather than carrying stale state forward.
• To compact only part of the conversation, press Esc twice (or run /rewind), select a message checkpoint, and choose Summarize from here or Summarize up to here.

Before a planned compaction, ask for a concise state summary:

Summarize current goal, files changed, commands run, unresolved risks, and exact next step.

After resuming, sanity-check the summary against the worktree:

git status --short
git diff --stat

What survives compaction

What happens to your instructions during compaction depends on how they were loaded:

If a rule must persist across compaction, drop its paths: frontmatter or move it into the project-root CLAUDE.md. Because invoked skills are truncated from the top of the file, put the most important instructions near the top of SKILL.md.

Recap Discipline

Good recaps are factual:

• Current user request.
• Assumptions.
• Files touched.
• Tests passed or failed.
• Known blockers.

They should not include every exploratory detail.

Token Discipline

• Read only the file ranges needed for the next decision. File reads dominate context usage.
• Prefer rg over broad file dumps.
• Summarize long docs instead of pasting them into the prompt.
• Move stable instructions into repository files.
• Delegate research-heavy work to a subagent. It runs in its own fresh context window and returns only a short summary, so large file reads never touch your main context.
• Keep MCP tool definitions out of the way: schemas are deferred by default and loaded on demand via tool search, so only tool names consume context until a specific tool is used. Run /mcp to check per-server costs.
• Close loops by updating tests or docs when behavior changes.

Inspect Your Own Session

Do not guess at context usage — measure it:

• /context shows a live breakdown of what is consuming the window, by category, with optimization suggestions.
• /memory shows which CLAUDE.md and auto memory files loaded at startup.
• /mcp shows the per-server cost of connected MCP tools.

Checkpoints are a separate safety net: before any file edit, Claude Code snapshots the file, so you can press Esc twice to rewind to an earlier state if a change goes wrong. Checkpoints cover file changes only and are local to your session, separate from git.

References

• Explore the context window
• How Claude Code works — the context window
• Store instructions and memories
• Reduce token usage