Compaction

Compaction makes room in a long session by replacing older conversation with a summary, so the session can keep going past the model’s context limit.

How it works

When a session approaches the model’s context limit, OpenCode summarizes the entire current conversation. It also keeps the most recent conversation, about 15,000 tokens by default, beside the summary so exact recent details remain available.

before   [ system prompt ][ older conversation ............ ][ recent 15k ][ pending work ]
request  [ system prompt ][ older conversation ............ ][ recent 15k ][ summary instructions ]
after    [ system prompt ][ summary of older + recent ][ recent 15k ][ pending work ]

Sending the full conversation lets the summary request reuse the normal request’s prompt cache when the provider supports it. Later compactions update the existing summary using the conversation since that checkpoint.

Start

Automatic compaction is on by default:

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

Compaction is lossy. Increase keep.tokens when exact recent details matter, or request compaction yourself before the automatic one.

Manual

Request compaction at any time, even for a short history:

opencode api post /api/session/ses_example/compact --data '{}'

The api command discovers and authenticates with the background service. Its response confirms the request was accepted; it does not wait for the summary. Follow session.compaction.* events to learn when it finishes. See the API reference for the full operation.

Pass an id to make an exact retry idempotent. Reusing that ID for a different request returns a conflict.

opencode api post /api/session/ses_example/compact --data '{"id":"msg_compact_once"}'

Settings

Add compaction to any OpenCode configuration file:

{
  "$schema": "https://opencode.ai/config.json",
  "compaction": {
    "auto": false,
    "keep": { "tokens": 24000 },
    "buffer": 16000,
  },
}

keep.tokens and buffer accept non-negative integers.

Model

By default OpenCode writes the summary itself, using the session’s model. Set agents.compaction.model to use another model for summaries:

{
  "$schema": "https://opencode.ai/config.json",
  "agents": {
    "compaction": { "model": "anthropic/claude-sonnet-5-5" },
  },
}

If that model cannot be resolved, OpenCode falls back to the session’s model.

Background compaction

Automatic compaction normally pauses the session while the summary is written. With background compaction, OpenCode writes the summary ahead of time and swaps it in when compaction is due:

{
  "$schema": "https://opencode.ai/config.json",
  "experimental": {
    "background_compaction": true,
  },
}

85% of the threshold   summary of the conversation so far starts in the background
                       the session keeps going; the summary is held, not applied
threshold              the held summary is swapped in; everything since it is kept as is

Providers

Some providers can compact the conversation on their side instead. Enable it per provider or model with settings.compaction:

{
  "$schema": "https://opencode.ai/config.json",
  "providers": {
    "openai": {
      "settings": { "compaction": { "type": "native" } },
      "models": {
        "gpt-6.1-sol": { "settings": { "compaction": { "type": "summary" } } },
      },
    },
  },
}

A model setting overrides the provider setting. native uses the provider’s compaction; summary uses OpenCode’s own.

With native compaction, OpenCode sends the conversation to the provider’s compaction endpoint. The provider returns an opaque, encrypted item that stands in for the older conversation. Your recent messages and attachments, up to keep.tokens, are kept alongside it:

before   [ older conversation ........................ ][ recent user messages ]
after    [ encrypted checkpoint + recent user messages ]

Summaries

The summary is structured so another agent could pick the work up from it:

## Objective
Finish the authentication migration.

## Next Move
- Update the callback handler.
- Verify the login flow.

It covers the objective and requirements, decisions, completed and active work, blockers and next moves, and relevant files. In the recent conversation kept beside it, long tool output is shortened and attachment data is replaced by a short description.

After compaction, the current versions of your instruction files become the session’s baseline; see Instructions.

Limits

For example, compaction cannot help here:

128k context = 120k fixed instructions and tools + 8k conversation

Migration

V1 used tail-turn and pruning behavior. V2 uses summaries and compaction.keep.tokens:

{
  "compaction": {
    "keep": { "tokens": 15000 }
  }
}

The settings and behavior on this page apply to V2.