| name | context-compaction |
| description | Keep a long agent session inside its context window without losing the plot. Use when a session is getting long, tool outputs are large, the agent starts "going off the rails" late in a task, or context usage is high. Trigger on big logs, long transcripts, or before a context-heavy step. |
context-compaction
The context window is the agent's working memory and it fills fast; even within the window, stale
tool output dilutes focus. If an agent goes off the rails late in a long task, the cause is almost
always context, not the model.
Steps
- Truncate at the boundary. A 50k-line log is not more useful than its first/last 200 lines
plus a count. Cap large tool outputs before they enter context.
- Summarize-and-compact. When the conversation crosses a threshold, replace the older middle
with a model-written summary ("what we've done and learned so far"), keeping the original task
and the most recent turns verbatim.
- Retrieve, don't carry. Keep large reference material on disk; pull in only the chunks needed,
when needed.
- Externalize state. Write the plan/progress to
tasks/todo.md and re-read it instead of
holding it in the conversation. The agent forgets between runs; the repo doesn't.
- Reset to anchors. On a fresh tick of a loop, reset context to the anchor files (AGENTS.md,
the skill, the spec) rather than growing it.
Notes
token-lean pathway truncates aggressively; accuracy-max summarizes so nothing needed is lost.
