# Context Compaction

Context compaction prevents your conversation from exceeding the AI's context window by intelligently summarizing older messages while preserving recent context.

## Why Compaction Matters

Every AI model has a limited context window — the maximum amount of text it can process at once. Long conversations can exceed this limit, causing errors or degraded responses. Compaction automatically manages this by:

- Tracking cumulative token usage per chat panel
- Triggering compaction when usage approaches the threshold
- Summarizing older messages while keeping recent ones intact

## How It Works

```
[Message 1] [Message 2] ... [Message N-4] [Message N-3] [Message N-2] [Message N-1] [Message N]
     |           |              |              |              |             |             |
     +--- Older messages -------+              +--- Preserved (last 4) ----+-------------+
     |                                         |
     v                                         v
  Summarized into a compact                 Kept as-is for
  context summary                           full detail
```

### Token Tracking

Mysti tracks cumulative token usage for each panel:
- **Input tokens**: Tokens sent to the model
- **Output tokens**: Tokens received from the model
- **Cache read tokens**: Tokens served from cache
- **Cache creation tokens**: Tokens stored in cache

### Threshold Triggering

When the fill level exceeds the configured threshold (default 75%), compaction is triggered automatically. A cooldown period (30 seconds) prevents rapid repeated compactions.

## Compaction Strategies

### Native CLI (`native-cli`)

For providers that support built-in compaction (currently Claude Code):

- Sends the `/compact` command to the CLI
- The provider handles summarization natively
- Generally produces the best results since the provider understands its own context format

### Client-Side Summarization (`client-summarize`)

For other providers:

- Mysti identifies older messages (beyond the preserved count)
- Summarizes them into a condensed context block
- Replaces the original messages with the summary
- Preserves the last N messages (default 4) in full

## Brainstorm Agent Tracking

In Brainstorm Mode, each agent's token usage is tracked independently using composite keys:
- Main panel: `panelId`
- Brainstorm agents: `panelId-brainstorm-agentId`

This ensures accurate tracking even when multiple agents are active simultaneously.

## Compaction Status

The system reports its status through these states:

| Status | Description |
|--------|-------------|
| `idle` | No compaction needed |
| `evaluating` | Checking if compaction is needed |
| `compacting` | Compaction in progress |
| `complete` | Compaction finished successfully |
| `error` | Compaction failed |

## Configuration

| Setting | Default | Description |
|---------|---------|-------------|
| `mysti.compaction.enabled` | `true` | Enable automatic context compaction |
| `mysti.compaction.threshold` | `75` | Trigger compaction at this % of context window |

## Provider Support

| Provider | Strategy | Notes |
|----------|----------|-------|
| Claude Code | `native-cli` | Uses built-in `/compact` command |
| Codex | `client-summarize` | Client-side summarization |
| Gemini | `client-summarize` | Client-side summarization |
| Cline | `client-summarize` | Client-side summarization |
| Copilot | `client-summarize` | Client-side summarization |
| Cursor | `client-summarize` | Client-side summarization |
| OpenClaw | `client-summarize` | Client-side summarization |

## Tips

1. **Leave compaction enabled** — it prevents errors from context overflow
2. **Lower the threshold** (e.g., 60%) for providers with smaller context windows
3. **Raise the threshold** (e.g., 90%) if you want to maximize context before compacting
4. **Watch for compaction events** in the chat — they indicate long conversations
5. **Start a new conversation** if you notice quality degrading after multiple compactions