Context Management
Keep Claude Code sessions accurate through memory, compaction, and concise handoffs.
Key takeaways
- Context is a working set, not storage: keep durable knowledge in files (
CLAUDE.md, ADRs, tests) and the session focused on the current decision. CLAUDE.md, unscoped rules, andMEMORY.mdare re-injected from disk after compaction, butpaths:-scoped rules and nestedCLAUDE.mdare lost until a matching file is read again.- Auto-compaction fires near 95% of capacity (tune with
CLAUDE_AUTOCOMPACT_PCT_OVERRIDE); steer it with/compact focus on ...and reset between unrelated tasks with/clear. - Invoked skill bodies survive compaction but are capped at 5,000 tokens each and 25,000 total, so put the most important instructions near the top of
SKILL.md. - Measure context instead of guessing:
/contextbreaks down window usage,/memorylists loaded files, and/mcpshows per-server tool cost.
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.mdfor 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.
Keep CLAUDE.md small
The project CLAUDE.md loads into context on every session and reloads after every compaction.
Keep it lean (aim for under ~200 lines) and move reference-heavy material into skills or
path-scoped rules under .claude/rules/ so it only loads when a matching file is read.
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.
You can also compact manually:
/compactreplaces the conversation with a structured summary on demand./compact focus on the API changessteers what the summary keeps.- Add a "Compact Instructions" section to
CLAUDE.mdto control what is preserved every time. /clearresets context entirely — use it between unrelated tasks rather than carrying stale state forward.- To compact only part of the conversation, press
Esctwice (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 --statCompaction thrashing
If a single file or tool output is so large that context refills immediately after each summary,
Claude Code stops auto-compacting after a few attempts and shows an error instead of looping. The
fix is to clear the offending content: start a fresh session with /clear, or avoid re-reading the
oversized file. See the official troubleshooting guide for recovery steps.
What survives compaction
What happens to your instructions during compaction depends on how they were loaded:
| Mechanism | After compaction |
|---|---|
| System prompt and output style | Unchanged; not part of message history |
Project-root CLAUDE.md and unscoped rules | Re-injected from disk |
Auto memory (MEMORY.md) | Re-injected from disk |
Rules with paths: frontmatter | Lost until a matching file is read again |
Nested CLAUDE.md in subdirectories | Lost until a file in that subdirectory is read again |
| Invoked skill bodies | Re-injected, capped at 5,000 tokens per skill and 25,000 tokens total; oldest dropped first |
| Skill descriptions (the startup listing) | Not re-injected; only skills you actually invoked are preserved |
| Hooks | Not applicable; hooks run as code, not context |
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
rgover 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
/mcpto 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:
/contextshows a live breakdown of what is consuming the window, by category, with optimization suggestions./memoryshows whichCLAUDE.mdand auto memory files loaded at startup./mcpshows 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.