Compaction Warning

Compaction Warning

The session's token budget crosses a configured threshold. A warning fires; the user decides whether to compact, stop, or continue.

---

Setup

• Session has been active long enough that message history is large.
• Compaction thresholds configured (defaults: warn at 80% of model context, require at 95%).
• The Compaction tool is registered (see Context-Compaction reference).

See Compaction and Memory.

---

Sequence

sequenceDiagram
    autonumber
    participant Core as message loop
    participant Assem as Context Assembly
    participant UI as TUI
    participant User
    participant Tool as Compaction tool
    participant LLM as provider

    Core->>Assem: compose request for turn T
    Assem->>Assem: tally tokens
    Assem-->>Core: at 82% of budget
    Core->>Core: audit CompactionWarning
    Core->>UI: "warning banner:<br/>82% context used"
    UI->>User: render banner
    User->>UI: /compact
    UI->>Core: invoke Compaction tool
    Core->>Tool: compact message history
    Tool->>LLM: summarize via LLM
    LLM-->>Tool: summary
    Tool-->>Core: compacted history
    Core->>Assem: recompose for turn T+1
    Assem-->>Core: at 34% of budget
    Core->>UI: warning cleared

Loading

---

Thresholds

Threshold	Default	Effect
warn	80% of model context window	Warning banner; audit event; session continues.
require	95%	Session refuses to COMPOSE_REQUEST until compacted or the user explicitly overrides. The override records a CompactionOverridden audit event.

Configurable per session in settings.json. A user who wants to work near the cliff sets warn higher; a cautious user sets it lower.

---

What the user can do

Action	Result
Run /compact	Invoke the Compaction tool; history summarized; threshold recovered.
Run /reset	Clear history and start from the current user input. Destructive — the user is confirmed first.
Continue typing	The warning remains; the next turn fires with the same state. At require, the next turn refuses.
Override at require	The turn proceeds; audit records the override. This exists because some workflows need one final answer before a forced compact.

---

What compaction is not

• Not automatic. Core does not silently summarize history. The user authorizes the operation.
• Not free. Compaction itself calls the LLM — one round trip. The cost is visible in usage.
• Not lossless. A summary is a summary; specific earlier exchanges are no longer verbatim. Workflows that require verbatim history (legal, compliance) should configure retention outside the context window (e.g., a logger sink).
• Not SM-specific. A compaction affects session message history. SM state slots and stage-local data are unaffected.

---

Role of the Compaction tool

The Context-Compaction reference tool is the bundled implementation. An alternative tool with a different summarization strategy (e.g., extractive rather than abstractive) replaces it by the normal extension replacement rules — see Tools.

Compaction is a tool, not a core feature, because strategies differ. Shipping one does not preclude swapping it.

---

Warning UX without compaction available

If the session's tool registry does not contain a Compaction tool (user disabled it, or a workflow explicitly excludes it), the warning still fires. The diagnostic suggests /reset as the alternative — the only mechanism that returns the session below threshold without invoking the LLM.

A session that hits require with no Compaction tool and no /reset refuses COMPOSE_REQUEST until the user takes action. The session is not killed; it is paused.

---

Audit

Event	When
CompactionWarning	Threshold warn crossed.
CompactionRequired	Threshold require crossed.
CompactionOverridden	User bypassed require for one turn.
CompactionApplied	Compaction tool completed successfully.

---

Related pages

• Compaction and Memory
• Context Assembly
• Context-Compaction tool
• Settings Shape
• Audit Trail