Skip to main content
Compacting a session replaces its older messages with a summary generated by a model you pick. Use it when a session has grown long enough that the model’s context window is a limiting factor, or when you want to keep working in the same session without carrying every prior turn.

​
When to compact

  • The session has been running long enough that responses are getting slower or hitting context limits.
  • You want to preserve the thread’s history in place instead of starting a new session.
  • You’re finished with an early phase of work (exploration, scaffolding) and want the summary to anchor the next phase.
Compaction is destructive. Once older messages are summarized and removed from the database, you can’t restore them. Start a fresh session instead if you might need the original turns later.

​
Compact a session

  1. Open the session.
  2. In the session header, select Compact.
  3. Pick the model that should generate the summary. The session’s current model is selected by default.
  4. Select Compact to confirm.
The compaction runs in the background. When it finishes, a marker appears in the conversation showing who triggered it and when, and the session continues from the summary. Only the session owner and organization admins can compact a session.

​
Automatic compaction

Sessions can also be compacted automatically by the runtime when the context window fills up. Automatic compactions show up in the conversation the same way, labeled as Compacted automatically instead of attributed to a user.

​
API

You can trigger compaction programmatically:
  • modelId is required and must be a valid providerId/modelId pair for a provider configured in your deployment. See Model providers for how models are registered.
  • Returns 204 No Content on success.
  • Returns 400 Invalid model ID if the model isn’t recognized.
  • Returns 403 Forbidden if you aren’t the session owner or an admin.
  • Returns 409 while the session’s OpenCode runtime is still provisioning, and 410 if the session is archived or deleted.