Compaction

목표

Kiro의 Compaction이 긴 세션을 모델 컨텍스트 한도 안에서 어떻게 유지하는지, 무엇이 보존되고 무엇이 요약되는지, CLI에서 어떻게 수동 트리거·설정하는지 이해합니다.

개념

Compaction은 세션이 커지면 오래된 대화 기록을 자동으로 요약해 긴 세션을 생산적으로 유지합니다. 목표·결정·기술적 진행은 보존되고, 장황한 중간 부분만 압축됩니다.

기능	IDE	CLI	Web	Mobile
자동 compaction	✓	✓	✓	✓
수동 트리거(/compact)	—	✓	—	—
Context usage 미터	✓	✓	✓	✓

동작 방식

대화가 모델의 컨텍스트 한도에 가까워지면 compaction이 자동으로 발동합니다.

1. Summary generation — Kiro가 목표·결정·진행·다음 단계를 담은 구조화된 요약을 만듭니다.
2. Context reduction — 오래된 대화 기록이 요약으로 대체되고, 가장 최근 메시지는 그대로(verbatim) 유지됩니다.
3. Continuation — 세션이 끊김 없이 이어집니다.

V3 CLI 세션에서는 자동 compaction이 도는 동안에도 진행 중인 응답과 Thinking 표시가 계속 보이고, 이미 대기열에 있던 프롬프트는 compaction이 끝나면 자동으로 이어집니다.

보존 vs 요약

항상 보존	요약될 수 있음
작업 상태(완료/진행/대기)	개별 도구 호출 상세
수정한 파일 경로	중간 추론 단계
핵심 결정·제약	이전 메시지의 코드 조각
다음 단계	해결된 이슈의 오류 상세
명시한 의도·요구사항	탐색적 논의

💡 에이전트가 세션 앞부분의 특정 세부를 잊은 것 같으면 다시 말해 주세요. 에이전트가 즉시 반영합니다.

트리거

• IDE / Web / Mobile: compaction은 자동이며 수동 트리거가 없습니다. 채팅 패널의 context usage 미터가 한도에 얼마나 가까운지 보여주고, compaction이 발동하면 미터가 리셋됩니다.
• CLI: 자동 발동 외에 수동으로도 트리거할 수 있습니다.

/compact

누적된 컨텍스트로 세션이 느려지거나, 같은 세션에서 새 작업 단계를 시작하기 전에 /compact를 쓰면 좋습니다.

설정 (CLI)

CLI는 compaction에서 얼마나 많은 컨텍스트를 유지할지 제어하는 두 설정을 제공합니다.

설정	기본값	설명
compaction.excludeMessages	2	verbatim으로 유지할 최근 메시지 쌍의 최소 개수
compaction.excludeContextWindowPercent	2	최근 메시지로 유지할 컨텍스트 윈도의 최소 비율(%)

두 설정 모두 평가되며, 더 보수적인(큰) 값이 적용됩니다. 그래서 연속성을 유지할 충분한 최근 컨텍스트가 항상 남습니다.

제한

Compaction은 단방향입니다. compaction 지점 이전의 전체 대화 기록은 세션 안에서 복구되지 않습니다. 전체 기록을 보존해야 하면 compaction이 일어나기 전에 세션을 export하세요.

해볼 것

1. CLI에서 긴 작업을 진행하며 context usage 미터가 올라가는지 봅니다.
2. 새 작업 단계를 시작하기 전에 /compact를 실행해 요약 후 세션이 이어지는지 확인합니다.
3. 요약 뒤에도 수정한 파일 경로·제약이 유지되는지 점검하고, 빠진 세부가 있으면 다시 말해 반영시킵니다.

더 알아보기

• Compaction
• Kiro 동작 원리 — compaction이 붙는 harness 흐름(6단계: 컨텍스트 관리)
• Memory — 세션 사이로 맥락을 이어가는 보완 기능
• Context Engineering — 맥락을 다루는 전반 전략

---

출처: kiro.dev 공식 문서 "Compaction" (2026-10-26 확인).