📊 Four Compaction Strategies
Quatro estrategias formam uma escada de custo. Claude Code sempre tenta a mais barata primeiro:
Strategy 1: Microcompact
Limpa conteudo de tool results antigos in-memory. Zero API calls, instantaneo.
Strategy 2: Session Memory Compact
Substitui mensagens antigas por um arquivo de session-memory pre-construido. Zero chamada de sumarizacao.
Strategy 3: Full LLM Compact
Forka sub-agente para escrever sumario estruturado de 9 secoes. Uma chamada API extra.
Strategy 4: Reactive Compact
Disparado por erro 413 prompt-too-long. Remove API rounds da cauda ate caber.
⚡ Thresholds & Token Warning States
| Estado | Buffer | Efeito |
|---|---|---|
| Normal | > 20K tokens | Nenhuma acao |
| Warning | ≤ 20K tokens | Indicador amarelo na UI |
| Auto-Compact | ≤ 13K tokens | Dispara compaction automatica |
| Blocking | ≤ 3K tokens | Bloqueia input do usuario |
Circuit Breaker
Auto-compact rastreia consecutiveFailures e para apos 3. Antes desse fix, um failure mode queimava ~250K chamadas API/dia globalmente.
✂️ Microcompact -- Tool-Result Pruning
Microcompact limpa conteudo de tool results antigos diretamente no array de mensagens in-memory. Nao chama LLM, nao escreve no disco. Tools elegiveis: FileRead, Bash, Grep, Glob, WebSearch, WebFetch, FileEdit, FileWrite.
Path 1: Time-Based MC
Se gap > 60min desde ultimo assistant message, content-clear tool results antigos. Mantem os 5 mais recentes.
Path 2: Cached MC
Enfileira cache_edits para a API aplicar server-side, sem mutar mensagens locais. Preserva prompt cache.
📝 The 9-Section Summary Prompt
O prompt de compaction instrui o modelo a produzir exatamente 9 secoes:
- Primary Request and Intent -- Todos os pedidos explicitos do usuario
- Key Technical Concepts -- Tecnologias, frameworks, design patterns
- Files and Code Sections -- Arquivos examinados/modificados com snippets
- Errors and Fixes -- Cada erro e como foi resolvido
- Problem Solving -- Problemas resolvidos e troubleshooting em andamento
- All User Messages -- Cada mensagem nao-tool-result verbatim. Critico para rastrear mudanca de intencao
- Pending Tasks -- Tarefas atribuidas nao concluidas
- Current Work -- O que estava acontecendo imediatamente antes do compact
- Optional Next Step -- Apenas se diretamente em linha com pedido mais recente
💡 Por que secao 6 importa
"All user messages" e a unica secao que nao pode ser inferida do tool use. Sem ela, o sumario capturaria o que Claude fez mas perderia as mudancas de intencao do usuario.
🧹 Post-Compact Cleanup
Apos compaction bem-sucedida, uma funcao centralizada invalida caches e estado:
resetMicrocompactState() // sempre
getUserContext.cache.clear() // re-read CLAUDE.md (main thread only)
clearSystemPromptSections()
clearClassifierApprovals()
clearSessionMessagesCache()Subagent safety: subagentes rodam no mesmo processo e compartilham estado module-level. O guard isMainThread previne que compaction de subagente corrompa o cache do main thread.
🔎 Reactive Compact & Context Collapse
Quando a janela ja esta acima do limite, o reactive compact e ativado por erro 413 da API. Remove API-round groups do fim mais antigo e tenta novamente.
O feature CONTEXT_COLLAPSE suprime auto-compact quando ativo, operando com thresholds proprios em 90% (commit) e 95% (blocking).
💻 The /context Command
O comando /context mostra quao cheio esta o contexto. Aplica as mesmas transformacoes pre-API que query.ts aplica, para que o usuario veja o que o modelo realmente recebe:
- Fatia para apenas mensagens apos o ultimo compact boundary
- Aplica context-collapse projection se habilitado
- Aplica microcompact para contagem de tokens precisa