> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sideren.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Compaction.

> Long conversations outgrow a model's context window. Compaction replaces the older turns with a summary so the conversation can keep going. Use the OpenAI or Anthropic compaction features you already know, or turn it on for chat completions with one header.

## How it works

A compaction is one summary request. The model reads the conversation as it stands and writes a
summary that lets it carry on from the same point. From then on, the summary stands in for the
turns it covers.

The summary request is billed like any other request, on the model you asked for. It reuses the
conversation's system prompt and tools, so on models that cache input most of it is read from
cache.

Pick the shape that matches the API you call:

| You call | Use |
| - | - |
| OpenAI Responses | `POST /v1/responses/compact`, or `context_management` on `/v1/responses` |
| Anthropic Messages | `compaction: {"type": "summarize"}`, or the `compact_20260112` context edit |
| OpenAI Chat Completions | the `x-sideren-context: compact` header |

## OpenAI Responses

### Compact on demand

Send the conversation to `POST /v1/responses/compact`, either as `input` items or as a stored
chain with `previous_response_id`. Pass the same `instructions` and `tools` you use for the rest
of the conversation.

```bash theme={null}
curl https://api.sideren.io/v1/responses/compact \
  -H "Authorization: Bearer $SIDEREN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4-mini",
    "input": [
      {"role": "user", "content": "Plan a trip to Kyoto."},
      {"role": "assistant", "content": "Day 1: Fushimi Inari at sunrise..."}
    ]
  }'
```

The reply has one compaction item:

```json theme={null}
{
  "id": "cmp_7f27...",
  "object": "response.compaction",
  "created_at": 1760000000,
  "model": "gpt-5.4-mini",
  "output": [{ "id": "cmpi_7f27...", "type": "compaction", "encrypted_content": "sdn1.c..." }],
  "usage": { "input_tokens": 1200, "input_tokens_details": { "cached_tokens": 1024 }, "output_tokens": 80, "total_tokens": 1280 }
}
```

Put the item in your next `input`, followed by the next turn. You can keep the older items or drop
them: the newest compaction item stands in for everything before it, so they are not sent again.
`encrypted_content` opens only for the API key that made it.

### Compact at a threshold

Add `context_management` to an ordinary `/v1/responses` request:

```json theme={null}
{
  "model": "gpt-5.4-mini",
  "context_management": [{ "type": "compaction", "compact_threshold": 200000 }],
  "input": [...]
}
```

When the input reaches `compact_threshold` tokens (default 200,000, and never later than 90% of
the model's window), we summarize the conversation first and the model answers from the
summary. The reply's `output` then starts with the compaction item; when streaming, it arrives as
output item 0 before the answer. Append the output to your next request as usual. With
`previous_response_id`, send only the new turn.

## Anthropic Messages

### Compact on demand

Send the conversation with `compaction`:

```json theme={null}
{
  "model": "claude-sonnet-5-5",
  "max_tokens": 4096,
  "messages": [...],
  "compaction": { "type": "summarize" }
}
```

The reply is one `compaction` block with `stop_reason: "compaction"`. Its usage is reported in
`usage.iterations`; the top-level `input_tokens` and `output_tokens` are zero. Streamed, the whole
block arrives in one `content_block_start`. Add `instructions` to replace the summary prompt.

Send the block back exactly as it came, first in `messages`, in place of the turns it summarizes.

### Compact at a threshold

Add the compaction edit to `context_management`:

```json theme={null}
{
  "context_management": {
    "edits": [{ "type": "compact_20260112", "trigger": { "type": "input_tokens", "value": 150000 } }]
  }
}
```

The trigger counts input tokens: 150K by default, and at least 50K. When it fires, the
reply's content starts with a `compaction` block and then the answer, and `usage.iterations` lists
the summary (`compaction`) and the answer (`message`). With `"pause_after_compaction": true` the
reply is the block alone, with `stop_reason: "compaction"`.

Append the reply's full content to your messages, as you would any reply. A compaction block
stands in for everything before it, wherever it sits.

`clear_tool_uses_20250919` and `clear_thinking_20251015` work as documented by Anthropic: cleared
tool results become a short placeholder, the calls stay, and `context_management.applied_edits`
reports what was cleared.

## Chat Completions

Chat Completions has no compaction standard. Add one header to let us manage it:

```bash theme={null}
-H "x-sideren-context: compact"
```

Past the line, we summarize the older part of the chat and keep the newest turns word for word.
Keep sending your full history every turn. We remember the summary for the conversation, so later
turns reuse it and keep the prompt cache warm, and we write a new one only when the chat grows past
the line again. The reply header `x-sideren-compacted` says how many of your messages the summary
stood in for, and `usage` counts what was actually sent.

| Parameter | Default | Meaning |
| - | - | - |
| `at` | the model's long-context price line, less 16K; else 80% of its window | Prompt tokens at which to summarize. |
| `keep` | a quarter of `at` | Newest tokens kept word for word. |

```bash theme={null}
-H "x-sideren-context: compact; at=120000; keep=30000"
```

Without the header we change nothing. `x-sideren-context: full` keeps the full context.

## Coding agents

Codex, Claude Code, OpenCode, Kilo Code, the Sideren CLI and others compact on their own, with
their own summary request. We recognize those requests and give them priority: a compaction stays
on its model and on the route that already holds the conversation's cache, and it is never pushed
aside when that route is busy.

If an agent's summary request is bigger than the model's window, or bigger than your plan's input
cap, we shrink it to fit (the oldest tool output goes first) instead of refusing it, so the
session can always compact its way out.

On a plan with an input cap, `GET /v1/models` with your key shows that cap as each model's
`context_window`, so agents that size themselves from it compact before the cap. The model's full
window stays in `sideren.max_context_window`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.