Use for explicit context window management — summarizing accumulated history, dropping irrelevant context, creating checkpoints, and keeping the conversation focused when the session is long or context pressure is rising.
Long sessions accumulate:
Without active management, the agent makes decisions based on stale context, wastes tokens re-reading known information, and eventually hits context limit without warning.
Start memory management when you see:
auto_compact threshold is approaching (see agent_config.json: auto_compact_threshold)When starting a new phase of work (after completing a major feature or before a risky change):
scratch_write("
=== SESSION CHECKPOINT [2026-03-11] ===
Completed:
- Added parallel_dispatch skill
- Fixed CLAUDE.md (removed stale cli/ references)
- Expanded think + orchestrator SKILL.md
Current state:
- Working in: skills/coding/, skills/global/
- Last file edited: skills/coding/parallel_dispatch/SKILL.md
- All edits verified: ruff passing, no tests broken
Open threads:
- academic/SKILL.md not yet added
- memory_management SKILL.md in progress
Key decisions made:
- Not converting 10_superpowers to different format — already correct layout
- ralph SKILL.md already complete; SOUL.md reference is fine
")
Before a large fan-out (reading 10+ files), write a brief state summary so you can recover context after:
scratch_write("
Before read phase:
Goal: find all usages of class ForeForest
Files likely affected: src/eoh/, skills/lazy_timeseries/
Will ignore: tests/, rust-cli/
")
After the read phase, update the scratch with key findings.
When context contains large blocks of irrelevant information:
If auto_compact fires (summary injected into history):
For tasks spanning multiple sessions, use todo_write to persist state across compaction events:
todo_write([
{"task": "Expand firecrawl SKILL.md", "status": "done"},
{"task": "Add academic/SKILL.md", "status": "pending"},
{"task": "Run full quality pass", "status": "pending"}
])
todo_read at session start to recover where you left off.
| Anti-pattern | Correct behavior |
|---|---|
| Re-reading the same large file twice in one session | Cache results in scratch; re-read only if file may have changed |
| Carrying full file content across many turns | Summarize what's relevant; discard the rest |
| Waiting for auto_compact to manage context | Be proactive; checkpoint before pressure builds |
| Not tracking what edits have been made | Use scratch or todo as an audit trail |
| Summarizing so aggressively that key decisions are lost | Keep facts, decisions, and open threads — drop ephemera only |