The complete guide to Claude Code setup. 100+ hours saved. 370x optimization. Production-tested patterns for skills, hooks, and MCP integration.
Claude Code sessions have finite context. When you approach the limit, context gets compacted – earlier messages are summarized to make room. If you’re not prepared, you lose critical details. This chapter covers how compaction works, how to structure information for preservation, and how to recover after compaction.
Purpose: Preserve critical session context through compaction events Source: Anthropic session_memory_compaction.ipynb + production patterns Difficulty: Intermediate Time: 15 minutes to set up, ongoing awareness
Claude Code automatically compacts context when usage approaches capacity (default: ~95%). During compaction, earlier messages are summarized into a shorter form.
What gets preserved: Recent messages, active tool calls, system instructions (CLAUDE.md, rules). What gets lost: Exact error messages, specific file paths from early in the session, nuanced corrections you made, debugging context.
Without preparation, compaction loses the details that matter most:
Before compaction: "The bug was in line 47 of src/auth/middleware.js --
the token validation used === instead of jwt.verify().
We tried 3 approaches before finding this."
After compaction: "Fixed an authentication bug."
The specific line number, file path, root cause, and failed attempts are gone.
Structure your working context so the most important information survives compaction. This template defines preservation priority:
## Session Memory (Compaction-Safe)
### 1. Errors & Corrections (HIGHEST PRIORITY)
- [Exact error message and fix, verbatim]
- [User corrections -- represent learned preferences]
### 2. Active Work
- Currently working on: [specific task]
- File being modified: [exact path]
- State: [what's done, what's next]
### 3. Completed Work
- [Feature]: [exact file paths, line numbers, specific values]
- [Fix]: [what was wrong, what was changed, evidence it works]
### 4. Pending Tasks
- [ ] [Task with specific details]
- [ ] [Task with specific details]
### 5. Key References
- Entry: #NNN
- Branch: dev-XXX
- PR: #NNN
- API key: [reference, not value]
Corrections are #1 because they represent learned preferences. If the user corrected you from using id to employee_id, losing that correction means you’ll repeat the mistake. Corrections are the highest-signal, lowest-volume information in a session.
Active work is #2 because it’s what you need to continue immediately after compaction. Knowing “I was editing line 47 of auth.js” is more actionable than knowing “I finished the database migration.”
Use a PreCompact hook to output structured memory guidance before compaction occurs:
{
"hooks": {
"PreCompact": [
{
"hooks": [
{
"type": "command",
"command": ".claude/hooks/pre-compact.sh"
}
]
}
]
}
}
Example hook (.claude/hooks/pre-compact.sh):
#!/bin/bash
# Output compaction guidance as structured message
cat << 'COMPACTION_GUIDANCE'
=== COMPACTION GUIDANCE ===
When summarizing this conversation, preserve in this EXACT order:
1. ERRORS & CORRECTIONS (verbatim - these are learned preferences)
2. ACTIVE WORK (current file, current task, current state)
3. COMPLETED WORK (exact paths, exact values, exact line numbers)
4. PENDING TASKS (not yet started)
5. KEY REFERENCES (entry numbers, branch names, PR numbers)
CRITICAL: Keep direct user quotes for corrections.
These represent preferences that must not be lost.
=== END GUIDANCE ===
COMPACTION_GUIDANCE
exit 0
This message appears in the context just before compaction, guiding the summarization to preserve the right details.
Two ways context resets – they need different recovery strategies:
| Aspect | Auto-Compaction | Manual /clear |
|---|---|---|
| When | ~95% context usage | User types /clear |
| What happens | Early messages summarized | ALL messages removed |
| CLAUDE.md | Preserved | Preserved |
| Recent context | Preserved (most recent turns) | Gone |
| Recovery | Usually seamless | Need to re-establish state |
When you notice context has been compacted (or after /clear), recover state from the filesystem:
# Run after compaction to re-establish context
git log --oneline -10 # What was recently committed
git status # What's currently changed
git diff HEAD~1 --stat # What the last commit changed
Add a recovery section to your CLAUDE.md that loads automatically:
## Recovery (After Compaction)
If this is a fresh context, discover state:
1. `git log --oneline -5` -- recent commits
2. `git status` -- current changes
3. Read `system-status.json` -- feature status
4. Check plan file if referenced above
This ensures recovery instructions survive compaction (CLAUDE.md is always loaded).
Anthropic’s research shows that code quality degrades as context fills past 75%. This has practical implications:
git commit -m "checkpoint: [description]")Why 75%, not 95%?: By the time auto-compaction kicks in at 95%, you’ve already been producing lower-quality code for 20% of the session. Proactive checkpointing at 75% keeps quality high throughout.
# Before hitting 75%:
git add -A && git commit -m "checkpoint: implemented auth middleware, tests passing"
# In new session:
git log --oneline -3 # See where you left off
git diff HEAD~1 # See what the checkpoint contains
# Continue from there
Check your context usage to know when to checkpoint:
/context or press c in the status bar~/.claude/settings.json to show context percentagePrevious: 41: Evaluation Patterns Next: 43: Claude Agent SDK