Compact a Long Session

Compaction summarises the older part of a conversation so a long session keeps working. Kiro does it automatically when the context fills, and the CLI lets you trigger it yourself with /compact.

When to use this

Compact when a session has run long and you want to keep going with the same task. Do not compact to tidy up: it is one-way, and the detail you lose is gone. If you are moving to a different task, a new session is better than a compacted old one.

Steps

1. Notice the signs early. Slower turns, the agent forgetting a decision from earlier, or an error about the context limit all point the same way.
2. Save anything you will need. Compaction cannot be undone, so export or copy the parts of the transcript that matter.
3. Run /compact in the CLI at a natural break, such as after a task finishes rather than in the middle of one. Manual compaction is a CLI feature; the IDE, Web, and Mobile compact automatically.
4. Know what survives. Compaction keeps task status, file paths, decisions, and next steps. It summarises tool output, old code snippets, and resolved errors. Anything you need verbatim should be in a file, not in the chat.
5. Tune the protection if automatic compaction is cutting too close to the present. compaction.excludeMessages (default 2) keeps that many recent messages out of the summary, and compaction.excludeContextWindowPercent (default 2) keeps that share of the window. The more conservative of the two wins.
6. Trim the context instead when the problem is loaded files rather than conversation length. /context show reports token usage per file, and /context remove drops a rule.
7. Start a new session for a new task. A fresh session is cheaper and clearer than a session carrying a summary of unrelated work.

Check it worked

After compaction, ask the agent to restate the current task and the next step. Both should survive, because both are in the “keep” list. Then ask about a specific line of code discussed twenty turns ago. That detail may be gone, and knowing which is which is the point of the exercise.

Common problems

• “Context limit exceeded unexpectedly.” Update first. A compaction loop that caused this error was fixed in IDE v1.0.138. If it persists, compact deliberately, or start a fresh session with only the files you need.
• The agent forgot a decision. Write decisions into a file or a steering file rather than relying on chat history to hold them.
• You lost the transcript you needed. Compaction is one-way. In the CLI, /chat save exports a session before you compact it.
• Compaction fires too often. The loaded context is too large. Remove context rules, or use a model with a larger window.
• You wanted the conversation back. Rewind forks a CLI conversation at an earlier turn, but it cannot recover history that compaction already summarised. See Checkpoints and rewind.

Related

• Undo with checkpoints and rewind covers the other recovery tools.
• Kiro CLI Guide lists the context and session commands.
• Troubleshooting covers the error messages in full.