Compaction

Compaction replaces the active model context from an older part of a session with a generated checkpoint. The checkpoint contains a structured summary and a serialized tail of recent context, so the agent can continue with more room in the model’s context window.

Compaction is lossy, but it does not delete the earlier durable session messages. After a successful compaction, V2 builds model requests from the latest completed checkpoint and the messages that follow it.

Automatic compaction

Automatic compaction is enabled by default. Before a model call, V2 estimates the size of the final system prompt, messages, and advertised tools. It starts compaction when:

estimated tokens >= min(input limit - buffer, context limit - max(output reserve, buffer))

The estimate uses the latest model response’s input usage plus output and newer content. Without usage, it estimates text, media, instructions, and tools locally. The output reserve is capped at 32,000 tokens; an absent input limit does not constrain the ceiling. Successful compaction rebuilds the request without promoting input again or spending another agent step.

V2 also recognizes provider errors classified as context overflow. If an overflow occurs before the provider produces assistant output or other retry evidence, V2 can compact and retry that step once. This recovery is attempted only when auto is enabled. A second overflow after recovery is returned as an error.

Manual compaction

Manual compaction is available through session interfaces. See the generated API reference for the server operation.

A manual request is durably admitted and wakes the session runner. It can compact short histories that would not trigger automatic compaction. By default, compaction runs at the next safe step boundary before pending steered or queued prompts, even if they were submitted first. Repeated requests while one is pending coalesce into that pending request. Whether compaction completes or fails, the barrier is then settled so pending prompts can proceed.

The server operation returns the admitted compaction input; it does not wait for summary generation. Clients can then wait for the session or follow the session.compaction.* events. Supplying an optional message id makes an exact retry idempotent, but reusing an ID owned by another record returns a conflict.

Configuration

Add compaction to any OpenCode configuration file:

{
  "$schema": "https://opencode.ai/config.json",
  "compaction": {
    "auto": true,
    "keep": {
      "tokens": 15000,
    },
    "buffer": 20000,
  },
}

keep.tokens and buffer accept non-negative integers. Larger keep.tokens preserves more recent detail but leaves less room for future work. Larger buffer triggers preflight compaction earlier.

Provider compaction

By default, compaction generates a local text summary. To use the selected provider’s native compaction operation for automatic and manual requests, set a provider policy. An individual model’s policy replaces the entire provider policy:

{
  "$schema": "https://opencode.ai/config.json",
  "providers": {
    "openai": {
      "compaction": { "mode": "provider", "threshold": 120000 },
      "models": {
        "gpt-5.4-mini": { "compaction": { "mode": "provider" } },
        "gpt-4.1": { "compaction": { "mode": "local" } },
      },
    },
  },
}

• threshold is an optional positive integer in provider mode. Omit it to use the selected model’s usable input ceiling above. A configured threshold is clamped to that ceiling. In this example, gpt-5.4-mini uses its own ceiling, not 120,000.
• Scheduling uses the normal safe session step boundaries, not in-band provider context management. compaction.auto: false disables all new automatic work.
• After installing a native checkpoint, automatic checks wait for a fresh model usage anchor. Encrypted checkpoint bytes are not a meaningful token count.
• OpenAI Responses uses a streamed compaction trigger when the route supports it. Endpoint-only routes use their standalone compaction endpoint. Deployment/model support can vary. Transient provider failures retry under the same session retry policy and plugin hook as other requests; nothing is installed until a checkpoint is returned.
• A known automatic context overflow uses local recovery over the durable original history, re-expanding native checkpoints. This applies both to ordinary model calls and native compaction rejection. If local recovery fails, the prior checkpoint remains intact and the error surfaces. Authentication, rate limits, cancellation, and other failures do not trigger local fallback. Manual native compaction also surfaces errors without fallback.
• Unsupported routes are rejected during model resolution. Configure custom endpoints through provider/model settings.baseURL, not a model.request hook; native compaction rejects endpoint rewrites by that hook.
• Trigger checkpoints retain whole, real user messages and attachments up to the compaction.tokens budget, including users retained across earlier native compactions. Synthetic guidance is not retained as user input. Endpoint results are stored as the provider returned them. Neither path fabricates a text summary. Keep threshold comfortably above tokens plus the system prompt and tools, or every step will compact again as soon as the next response reports usage.
• Successful native checkpoints advance the instruction epoch and are replayed only with a matching provider, model, protocol, and endpoint. Switching to an incompatible route reuses an earlier compatible checkpoint or retained transcript. Disabling automatic compaction does not remove an installed checkpoint.

Local checkpoint contents

V2 uses the session’s selected agent, model, and variant to generate the summary. The request reuses the normal instructions, tool definitions, and structured history prefix, then appends a user message requesting a checkpoint. Context hooks run as they do for normal session requests.

Compaction does not dispatch local tool calls or override tool choice. The summary must contain at least one heading from the requested template, such as ## Objective. If it does not, V2 makes one additional request asking the model to fill in the template correctly. A second invalid response fails compaction. Provider-hosted tools remain subject to the selected provider’s behavior.

The summary records the objective, requirements, decisions, completed and active work, blockers, next moves, relevant files, and additional context.

The newest serialized context up to keep.tokens is retained separately. This is not a byte-for-byte transcript: tool output is limited to 2000 characters, and file or media attachments become textual descriptors rather than embedded data. On later compactions, V2 updates the previous summary and carries forward its retained recent context before selecting a new tail.

The completed compaction is presented to the model as historical conversation context, explicitly not as new instructions. Running and failed compactions are not included in model context.

Compaction advances the instruction epoch

Conversation compaction and instruction synchronization are separate. Before each physical model attempt, V2 compares live instruction sources with the latest admitted values, before delivering pending input for that attempt. Ordinary changes become durable value deltas. Later changes freeze their model-facing text when admitted and project it as chronological System messages; request assembly renders only the epoch baseline from stored values.

Completed compaction advances the instruction epoch at the exact ended-event sequence and makes the currently admitted values initial. It does not reread sources or publish an instruction event. Session movement retains instruction state so destination changes become chronological updates. Committed revert clears instruction state so the next model attempt requires one complete source read. See Instructions for source ordering and update behavior.

Current limitations

• Compaction requires a resolvable model. Automatic scheduling needs a positive catalog context limit; manual and overflow recovery do not. There is no separate compaction-model setting or fallback model.
• Summary generation can fail if the summary prompt itself cannot fit beside its output allowance, the model returns no summary, or the provider fails.
• Automatic and overflow compaction need older conversation context that can be replaced. A provider overflow can still surface when there is no compressible head or fixed instructions and tool schemas dominate the request.
• Overflow recovery retries only once per step. Token estimation is heuristic, so it cannot prevent every provider-specific overflow.
• Earlier durable messages remain stored even though they are no longer in the active model context.

V1 used additional tail-turn and pruning behavior. Those V1 details are only migration context; the settings and behavior on this page describe V2.