Compaction keeps long sessions productive by automatically summarizing older conversation history as your session grows. Your goals, decisions, and technical progress are preserved - only the verbose middle gets compressed.
| Capability | IDE | CLI | Web | Mobile |
|---|---|---|---|---|
| Automatic compaction | ✓ | ✓ | ✓ | ✓ |
Manual trigger (/compact) | — | ✓ | — | — |
| Context usage meter | ✓ | ✓ | ✓ | ✓ |
When your conversation approaches the model's context limit, compaction triggers automatically:
- Summary generation - Kiro creates a structured summary capturing your goals, decisions, progress, and next steps
- Context reduction - Older conversation history is replaced by the summary, while your most recent messages are kept verbatim
- Continuation - The session continues from where you left off with no interruption
In V3 CLI sessions, the active response and Thinking indicator remain visible while automatic compaction runs. Prompts already queued continue automatically when compaction finishes.
In Kiro CLI 3.1.0 or later, V3 sessions run PreCompact Hooks before compaction and PostCompact Hooks after it. A PreCompact Hook can refuse the compaction; a PostCompact Hook receives the summary. See Hook types.
Your goals, decisions, file modifications, and stated constraints survive compaction. What gets compressed is intermediate output - tool call details, exploratory discussion, and resolved error messages.
You've been working on a refactoring task for 45 minutes - the agent has modified 12 files, run tests, and fixed three build errors. Context usage is at 80%.
Compaction fires. The summary captures: which files were modified, what tests pass, the remaining 2 files to refactor, and your constraint that "all changes must be backward-compatible." The last two exchanges (your most recent instruction and the agent's response) stay verbatim.
The agent continues immediately. It knows what's done, what's next, and what your rules are - without carrying 45 minutes of intermediate tool output.
| Always preserved | May be summarized |
|---|---|
| Task status (done / in-progress / pending) | Individual tool call details |
| File paths modified | Intermediate reasoning steps |
| Key decisions and constraints | Code snippets in earlier messages |
| Next steps | Error details from resolved issues |
| Your stated intent and requirements | Exploratory discussion |
Compaction is automatic in the IDE. There is no manual trigger.
The context usage meter in the chat panel shows how close you are to the model's limit. When compaction fires, the meter resets to reflect the freed space and the session continues.
The CLI exposes settings that control when automatic compaction starts and how much context is retained:
| Setting | Default | Description |
|---|---|---|
compaction.autoCompactionThreshold | 80 | Context usage percentage at which automatic compaction starts in a V3 session (Kiro CLI 3.3.0 or later). A number from 0 to 100 with at most two decimal places |
compaction.excludeMessages | 2 | Minimum number of recent message pairs to retain verbatim |
compaction.excludeContextWindowPercent | 2 | Minimum percentage of the context window to keep as recent messages |
The two exclusion settings are evaluated together, and the more conservative (larger) value wins. This ensures enough recent context is always available for the agent to maintain continuity.
In Kiro CLI 3.3.0 or later, a V3 session can also set the threshold from /settings. Open Compaction to turn automatic compaction on or off, see the threshold the current session uses, and edit the Global default. The editor shows the range the agent harness accepts and its default; the value you save applies to the next session you start or load. kiro-cli settings compaction.autoCompactionThreshold <value> accepts 0 to 100, and an interactive session applies the range the agent harness advertises. A compaction.autoCompactionThreshold value in a workspace .kiro/settings/cli.json overrides the global default for that workspace. See In-session settings.
Compaction is one-way. The full conversation history before the compaction point is not recoverable within the session. If you need to preserve the complete history, export your session before compaction occurs.
In IDE 0.x, this feature was called "Summarization." The behavior was similar (auto-trigger at 80% context usage) but created a new session with compacted context rather than continuing in the same session. See 0.x reference for the legacy behavior.
Compaction