LLM Wiki — Synaptic Lattice

Context Compaction

Properties1
tagsprompt-engineering, workflow-pattern, research-gap

Leitura de 3 min

Context Compaction

Overview

Context compaction replaces the older part of a session’s model context with a generated checkpoint: a structured summary of the objective, important details, completed and active work, blockers, next moves, and relevant files, plus a serialized tail of recent context. The agent continues with more room in the model’s context window. Compaction is lossy (tool output truncated, attachments become textual descriptors) but does not delete the earlier durable session messages — later model requests are built from the latest completed checkpoint plus the messages after it.

Trigger Model

Automatic compaction runs a preflight estimate before a model call:

estimated tokens > context limit - max(requested output tokens, buffer)

The estimate is approximate (JSON-serialized request, ~4 chars/token). If compaction succeeds, the request is rebuilt from the new checkpoint and retried without re-promoting input. A provider context-overflow error can also trigger one-shot compaction + retry, even when auto is false (which only governs the preflight size check); a second overflow is surfaced as an error.

Manual compaction (e.g. /compact, /summarize, or a server API call) is durably admitted and can compact short histories that wouldn’t trip automatic compaction; repeated requests coalesce.

Checkpoint Contents

The session’s selected/default model generates the summary with tools disabled and at most 4096 output tokens. A tail of recent serialized context up to keep.tokens (default 8000) is retained separately — not a byte-for-byte transcript (tool output capped at 2000 chars; file/media attachments become textual descriptors). Later compactions update the previous summary and carry forward its retained tail. The completed compaction is presented to the model as historical context, explicitly not as new instructions; running/failed compactions are excluded.

Instruction Epoch

Compaction is decoupled from instruction synchronization. Live instruction sources (e.g. AGENTS.md) produce durable value deltas, and the model-facing System messages are derived during request assembly rather than persisted. Completed compaction advances the instruction epoch, making currently admitted instruction values initial — without re-reading sources or publishing an instruction event.

Relationship to Token Windows

This pattern is distinct from claude-code-context-window, which documents a tool’s raw context-window limits and defaults. Compaction is the management mechanism that keeps a session working within those limits — a workflow pattern rather than a capacity fact.

Implications

Compaction is the dominant strategy for long-horizon agent sessions: summary-based lossy compression plus a retained recent tail, triggered by preflight estimation and overflow recovery. Its “instruction epoch” decoupling is a design insight for instruction handling — instructions are synced via durable deltas and materialized at request time, not persisted per compaction. Open questions: where the 2000-char tool-output cap and 8000-token keep default sit relative to other agents’ compaction (Claude Code, Cursor), and whether checkpoint summaries are interchangeable across tools.

claude-code-context-window token-usage-reduction opencode

Open Questions

  • Does any other agent (Claude Code, Cursor, Codex) expose compaction config comparable to keep.tokens/buffer, and are their defaults tuned differently?
  • Is there a portable checkpoint format for handoff between agents, or is each tool’s checkpoint tool-specific?

Sources

  • raw/external/opencode-ai-compaction-d433d7dd.md

Visão de gráfico

Backlinks