Compaction

How /compact works end-to-end — what gets summarized, what's preserved, when it fires automatically, and what the agent sees afterward.

Compaction is how a long session fits back into the model’s context window. /compact asks a dedicated summarizer to fold older turns into a single message, keeping the tail of the conversation intact so the agent stays oriented.

/compact focus on what we tried and what worked

A session can be compacted many times. The platform remembers every original message under compacted_at; the agent sees the summary plus the live tail.

What runs when you type `/compact`

The TUI posts to the runtime, which invokes a separate summarizer — not the agent you’re talking to. The summarizer has no tools and no capability context. It runs against the same model the session is using and returns a summary paragraph.

The result is inserted as a single user-role message:

<conversation-summary messages={N}>
{summary text}
</conversation-summary>

{N} is the number of original messages that were folded. The message’s metadata is tagged {"compaction": True, "trigger": "manual", "messages_compacted": N} so downstream tooling can find it.

In the transcript, the TUI renders this as a one-line divider followed by the tail of the conversation:

The TUI after running /compact — a ── Compacted — 10 messages summarized ── separator sits above the recent turns, which continue as if nothing happened.

The full summary body is kept in a collapsible widget. In compact output mode the body is hidden; flip to expanded with Ctrl+O to read it.

What gets preserved

Compaction always keeps the system prompt and the tail of the conversation. Manual /compact keeps at least the last 6 messages; automatic overflow recovery keeps the last 10. The boundary walker only splits after a simple assistant message with no tool calls — so a tool call and its result are never separated. Thinking blocks inside the kept tail survive intact.

Everything before the boundary is collapsed into the summary. If the session has fewer than the minimum messages, /compact returns status="skipped" and nothing changes.

Automatic compaction on overflow

Dreadnode does not compact on a schedule or token threshold. The only automatic path is overflow recovery: if a model call fails with a context-length error, the agent compacts the oldest-75% of the input budget, then retries the failed turn. Overflow recovery fires at most once per step and only if there are enough messages to compact (at least 10).

If overflow recovery can’t produce a valid boundary or the summarizer itself fails, the original context-length error bubbles up and the turn ends with stop_reason="error".

Guidance

The optional argument to /compact prepends a line to the summarizer’s user message:

/compact focus on which auth endpoints we verified

becomes

Additional summarization guidance:
focus on which auth endpoints we verified

<conversation>
...
</conversation>

Guidance doesn’t replace the summarizer’s system prompt — it’s an extra hint. Leave it blank for a generic summary.

When a prior compaction summary is in the range being re-compacted, the summarizer gets an extra preamble asking it to incorporate and extend the earlier summary rather than discard it. This is automatic; you don’t need to do anything.

Is compaction reversible?

The summary is not reversible within the live session — the agent from here on sees the summary, not the originals. But the platform stores every message with a compacted_at timestamp rather than deleting it. Exports via the API can request include_compacted=True to retrieve the full history; the TUI and CLI don’t expose that flag today.

Failure modes

Situation	Result
Agent is mid-turn	`status="skipped"`, reason `turn_in_progress`. Try again after the turn
Another `/compact` is already running	`status="skipped"`, reason `already_in_progress`
Fewer than 6 messages (or 10 for overflow)	`status="skipped"`, reason `not_enough_messages`
Summarizer model errors	`status="failed"` with the error message. Session transcript is unchanged
Summarizer input won’t fit its own budget	Overflow recovery bails; manual compact returns `skipped`

None of these corrupt the session.

Observable state

The platform tracks compaction_count per session and exposes it on the session usage endpoint alongside two token pairs:

current_* counts only the active era (post-compaction)
total_* keeps accumulating across every era

The platform web UI shows compacted ×N in the session header. The TUI currently does not surface the count — check the web analysis view if you need it.

When to reach for `/compact` vs `/new`

Compaction is the right call when the conversation has been productive but long, and you want the agent to keep its orientation. If the thread has drifted and you’d rather start clean, /new is usually better — start fresh with a focused prompt.