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

# Context compaction

> What happens when the conversation gets long.

When your conversation gets close to the model's context window, SoulForge compacts it — summarizes older messages into a concise state, preserves the recent ones verbatim. The conversation continues; nothing is lost.

Compaction fires automatically at 70% of the context window. You can also run it manually:

```
/compact
```

## Two strategies

<Tabs>
  <Tab title="V2 (default) — instant, usually free">
    SoulForge tracks structured state — files touched, decisions, discoveries, tool results — as the conversation happens. When compaction fires, this state is already built. Most sessions compact in zero LLM calls.

    Best for: typical coding sessions.
  </Tab>

  <Tab title="V1 — LLM summary">
    Sends the older half of the conversation to a cheap model and replaces it with a prose summary.

    Best for: design-heavy sessions where nuanced reasoning matters more than structured data.
  </Tab>
</Tabs>

Switch with `/compact settings` or in config.

## Config

```json theme={null}
{
  "compaction": {
    "strategy": "v2",
    "triggerThreshold": 0.7,
    "keepRecent": 4
  }
}
```

| Field              | Default | What it does                             |
| ------------------ | ------- | ---------------------------------------- |
| `strategy`         | `"v2"`  | `"v2"` or `"v1"`                         |
| `triggerThreshold` | `0.7`   | Auto-compact at this fraction of context |
| `keepRecent`       | `4`     | Recent messages kept verbatim            |
| `maxToolResults`   | `30`    | Rolling window of tool results (V2)      |
| `llmExtraction`    | `true`  | Allow a cheap gap-fill pass (V2)         |

## Which model compacts

Assign a cheap model in the [task router](/recipes/task-router):

```json theme={null}
{
  "taskRouter": {
    "compact": "google/gemini-2.5-flash"
  }
}
```

For V2, this model only runs the optional gap-fill. For V1, it does the whole summary.

## Signals

* Context bar shows compaction strategy + slot count.
* Compacting spinner during an active compaction.
* System message reports before/after context percentages.