Context Compaction 컨텍스트 컴팩션

Overview 개요

Long coding sessions generate large conversation histories that eventually exceed the context window. ROACH PI uses a two-layer approach to context management:

긴 코딩 세션은 결국 컨텍스트 윈도우를 초과하는 대화 기록을 생성합니다. ROACH PI는 컨텍스트 관리를 위해 두 계층 접근 방식을 사용합니다:

• Full compaction전체 컴팩션 — Summarizes the entire old conversation into a structured summary, freeing context for new work.전체 이전 대화를 구조화된 요약으로 압축하여 새 작업을 위한 컨텍스트를 확보합니다.
• Microcompaction마이크로컴팩션 — Truncates old tool results to short placeholders before full compaction is needed, extending session lifetime.전체 컴팩션이 필요하기 전에 오래된 도구 결과를 짧은 플레이스홀더로 자르고, 세션 수명을 연장합니다.

How Compaction Works 컴팩션 작동 방식

Phase-aware custom compaction takes over during active workflows. When the context window fills up, instead of using the default summarizer, ROACH PI injects a specialized compaction prompt that is tailored to the current workflow phase.

단계 인식 커스텀 컴팩션이 활성 워크플로 중에 작동합니다. 컨텍스트 윈도우가 꽉 차면 기본 요약기를 사용하는 대신, ROACH PI는 현재 워크플로 단계에 맞춤화된 특수 컴팩션 프롬프트를 주입합니다.

The prompt starts with a critical directive that prevents the model from making tool calls during compaction:

프롬프트는 컴팩션 중 모델이 도구를 호출하지 못하게 하는 중요 지시문으로 시작합니다:

The model is required to produce two XML blocks in its response:

모델은 응답에 두 개의 XML 블록을 생성해야 합니다:

• <analysis> — Chronological thought process analyzing the conversation대화를 분석하는 순차적 사고 과정
• <summary> — The structured summary in the prescribed 9-section format규정된 9개 섹션 형식의 구조화된 요약

After compaction, the <analysis> block is stripped and only the formatted summary is retained in context.

컴팩션 후 <analysis> 블록은 제거되고 형식화된 요약만 컨텍스트에 유지됩니다.

Summary Format 요약 형식

Every compaction summary follows this nine-section structure. The model is given an explicit example template to follow.

모든 컴팩션 요약은 이 9개 섹션 구조를 따릅니다. 모델은 명시적인 예제 템플릿을 제공받습니다.

Workflow Phases 워크플로 단계

Compaction is phase-aware. When an active workflow is running, the compaction prompt is augmented with phase-specific instructions that tell the model what to preserve.

컴팩션은 단계를 인식합니다. 활성 워크플로가 실행 중일 때, 컴팩션 프롬프트는 모델이 보존해야 할 내용을 알려주는 단계별 지시문으로 보강됩니다.

Each non-idle phase injects additional instructions into the compaction prompt, emphasizing what the model must preserve. For example, during planning, the prompt requires the summary to capture task progress, implementation decisions, and the current task state.

각 비유휴(non-idle) 단계는 컴팩션 프롬프트에 추가 지시문을 주입하여 모델이 보존해야 할 내용을 강조합니다. 예를 들어, planning 중에는 프롬프트가 요약에 작업 진행 상황, 구현 결정, 현재 작업 상태를 포함하도록 요구합니다.

Microcompaction 마이크로컴팩션

Microcompaction is a lightweight pre-compaction pass that replaces old tool results with short placeholders. This extends session lifetime by reducing token usage before a full compaction is triggered.

마이크로컴팩션은 오래된 도구 결과를 짧은 플레이스홀더로 교체하는 경량 사전 컴팩션 패스입니다. 전체 컴팩션이 트리거되기 전에 토큰 사용량을 줄여 세션 수명을 연장합니다.

A message is eligible for microcompaction when all of these conditions are met:

메시지는 다음 모든 조건이 충족될 때 마이크로컴팩션 대상이 됩니다:

• role === "toolResult"
• isError !== true (error results are never compacted)(오류 결과는 절대 컴팩션되지 않음)
• toolName is in이 PI_TOOL_NAME_SET (known pi tools only)(알려진 pi 도구만)
• Message age메시지 나이 >= MICROCOMPACT_AGE_MS (1 hour)(1시간)

When compacted, the tool result content is replaced with:

컴팩션되면 도구 결과 콘텐츠가 다음으로 교체됩니다:

Microcompaction is opt-in. It must be explicitly enabled via environment variable.

마이크로컴팩션은 옵트인입니다. 환경 변수를 통해 명시적으로 활성화해야 합니다.

Configuration설정

Plan Execution Interaction계획 실행과의 상호작용

During plan execution (plan-compliance, plan-worker, plan-validator), the workflow phase and goal document are critical for continuity. If a compaction occurs mid-execution:

계획 실행 중(plan-compliance, plan-worker, plan-validator), 워크플로 단계와 목표 문서는 연속성에 중요합니다. 실행 중 컴팩션이 발생하면:

• The current workflow phase is stored in compaction metadata and restored after the summary is generated. 현재 워크플로 단계가 컴팩션 메타데이터에 저장되고, 요약 생성 후 복원됩니다.
• The goal document (if present) is referenced in the compaction prompt so the model anchors the user's intent. 목표 문서(있는 경우)가 컴팩션 프롬프트에 참조되어 모델이 사용자의 의도를 고정합니다.
• Phase-specific instructions ensure that task progress, implementation decisions, and current task state survive the compaction. 단계별 지시문이 작업 진행 상황, 구현 결정, 현재 작업 상태가 컴팩션 후에도 유지되도록 보장합니다.

This means a long-running plan execution will not lose track of its goal or phase even if multiple compactions occur.

즉, 긴 계획 실행 중 여러 컴팩션이 발생해도 목표나 단계를 잃지 않습니다.