Compactação de Contexto em Agentes de IA: Como Hermes, Codex, Claude Code e OpenCode gerenciam a janela de memória

Quando você usa um agente de IA para uma sessão longa de programação, algo inevitável acontece: a conversa cresce, os tool results se acumulam e o contexto se aproxima do limite do modelo. O agente começa a “esquecer” coisas — o system prompt, instruções iniciais, decisões importantes. E, no pior caso, a API retorna um erro context_length_exceeded e a sessão morre.

A solução se chama compactação de contexto (context compaction). Não se trata de expandir a memória do modelo, mas de aprender a esquecer com precisão: conservar o essencial, descartar o ruído e fazer isso gastando o mínimo de tokens possível no processo.

Este artigo analisa como quatro sistemas de agentes de IA implementam essa funcionalidade crítica. Hermes Agent, Codex CLI, Claude Code e OpenCode têm abordagens radicalmente distintas — desde a dupla camada de segurança do Hermes até as três fases progressivas do Claude Code — mas todos convergem em um padrão comum.

O que é compactação de contexto e por que isso importa?

Cada turno em uma conversa com um agente de IA adiciona tokens ao histórico. O system prompt (com definições de ferramentas, instruções, memória persistente), as mensagens do usuário, as respostas do assistente, as tool calls e os tool results — tudo se acumula.

Em uma sessão típica de depuração, os tool results representam ~80% dos tokens totais. Uma busca com grep pode retornar 2.000 tokens; ler um arquivo de 300 linhas soma 3.500; uma execução de testes com stack traces adiciona outros 3.000. Esses dados foram críticos durante a depuração, mas uma vez que o bug está resolvido, são lastro.

Sem compactação, o agente tem três opções, todas ruins:

1. Falhar com um erro de contexto excedido, perdendo todo o progresso
2. Ignorar instruções iniciais porque o contexto foi tomado por tool results
3. Custar uma fortuna porque cada turno custa tokens de input proporcionais ao histórico acumulado

A compactação resolve isso substituindo o histórico intermediário (tool results antigos, conversa resolvida, depuração concluída) por um resumo estruturado, preservando a cabeça (system prompt + primeira troca) e a cauda (turnos recentes). É um investimento: você gasta alguns centavos em um LLM barato para gerar o resumo e economiza esse custo em cada turno futuro.

Hermes Agent: o sistema de dupla camada

Hermes Agent, desenvolvido pela Nous Research, tem o sistema de compactação melhor documentado e mais configurável dos quatro. Sua arquitetura usa duas camadas independentes que operam em diferentes pontos do fluxo.

Camada 1: Gateway Session Hygiene (85% do contexto)

Esta camada vive em gateway/run.py e é executada antes de o agente processar uma mensagem recebida. É uma rede de segurança para sessões que crescem sem controle entre turnos — por exemplo, uma sessão do Telegram que acumula mensagens enquanto o agente não está ativo.

• Limiar: fixo em 85% do contexto do modelo
• Fonte de tokens: usa tokens reais informados pela API se disponíveis; fallback para estimativa por caracteres
• Disparo: somente quando len(history) >= 4 e a compressão está habilitada
• Propósito: capturar sessões que escaparam ao compressor do agente

O limiar do gateway está intencionalmente mais alto que o do agente. Colocá-lo em 50% (igual ao do agente) causava compressões prematuras em cada turno de sessões gateway longas.

Camada 2: Agent ContextCompressor (50% do contexto, configurável)

Esta é a camada principal, em agent/context_compressor.py. É executada dentro do tool loop do agente com acesso a contagens precisas de tokens da API.

Configuração típica:

compression:
  threshold: 0.50          # Fração do contexto que dispara a compressão
  target_ratio: 0.20       # Qual fração do threshold preservar como cauda
  protect_last_n: 20       # Mínimo de mensagens recentes protegidas

Para um modelo com 200K de contexto, a compressão é disparada ao atingir ~100K tokens. A cauda protegida recebe ~20K tokens, e o resumo tem um orçamento de até 10K tokens.

Algoritmo de 4 fases

A mágica está em como ContextCompressor.compress() transforma 45 mensagens e ~95K tokens em 25 mensagens e ~45K tokens.

Fase 1: Podar tool results antigos (sem LLM, custo ~zero)

Os tool results >200 caracteres que estão fora da cauda protegida são substituídos por um placeholder: [Old tool output cleared to save context space]. Isso libera uma enorme quantidade de tokens sem precisar chamar nenhum modelo.

O agente lembra que executou um comando, mas não o output exato. Se precisar do detalhe, pode reexecutá-lo.

Fase 2: Determinar limites

[0..2]   ← protege primeiras 3 mensagens (system + primeira troca)
[3..N]   ← turnos do meio → serão resumidos
[N..end] ← cauda protegida (por budget de tokens OU protect_last_n)

A proteção de cauda caminha para trás a partir do final acumulando tokens até esgotar o orçamento. Se o orçamento protegeria menos mensagens que protect_last_n, usa-se o mínimo fixo.

Os limites são alinhados para não dividir grupos tool_call/tool_result. O método _align_boundary_backward() caminha para trás através de tool results consecutivos para encontrar a mensagem assistant pai.

Fase 3: Resumo estruturado via LLM auxiliar

A seção intermediária é enviada a um modelo auxiliar (configurável, tipicamente mais barato que o principal) com um template de 8 seções:

## Goal
[O que o usuário está tentando alcançar]

## Constraints & Preferences
[Preferências, estilo de código, decisões importantes]

## Progress
### Done
[Trabalho concluído — caminhos específicos, comandos, resultados]
### In Progress
[Trabalho em andamento]
### Blocked
[Bloqueios ou problemas encontrados]

## Key Decisions
[Decisões técnicas importantes e por quê]

## Relevant Files
[Arquivos lidos, modificados ou criados]

## Next Steps
[O que deve acontecer em seguida]

## Critical Context
[Valores específicos, mensagens de erro, detalhes de configuração]

O orçamento do resumo escala com o conteúdo a ser compactado: content_tokens × 0,20, com mínimo de 2.000 e máximo de min(context_length × 0,05, 12.000).

Fase 4: Montar mensagens compactadas

Uma nova lista de mensagens é construída:

• Mensagens de cabeça (com uma nota adicionada ao system prompt na primeira compressão: “Alguns turnos anteriores foram compactados…”)
• Mensagem de resumo (com papel escolhido para evitar violações de papéis consecutivos)
• Cauda (mensagens recentes sem modificação)

_sanitize_tool_pairs() limpa pares órfãos: tool results que referenciam calls removidos são eliminados, tool calls cujo resultado foi removido recebem um stub.

Recompressão iterativa

Em compressões subsequentes, o resumo anterior é passado ao LLM com instruções de atualizá-lo, não resumir do zero. Itens passam de “In Progress” para “Done”, novo progresso é adicionado e informações obsoletas são removidas.

Prompt Caching (Anthropic)

Hermes também integra Prompt Caching para modelos Anthropic, em agent/prompt_caching.py. A estratégia system_and_3 coloca 4 breakpoints de cache:

• Breakpoint 1: System prompt (sempre estável)
• Breakpoints 2-4: Últimas 3 mensagens não-system (rolling window)

Isso reduz custos de input ~75% em conversas multi-turno sem sacrificar informações.

Codex CLI: o handoff summary

OpenAI Codex CLI adota uma abordagem mais simples, porém igualmente eficaz: uma única camada de compressão que substitui tudo por um resumo “handoff”.

Design de rota dupla

Codex oferece dois caminhos de compressão:

• Rota local (compact.rs): o cliente chama um LLM para gerar o resumo. Funciona com qualquer provedor de modelos.
• Rota remota (compact_remote.rs): chama o endpoint interno da OpenAI responses/compact. O servidor da OpenAI lida com a compressão, provavelmente com modelos especializados e cache interno.

Em ambos os casos, a compressão requer uma chamada LLM. A diferença é onde ela é executada: a rota local orquestra tudo a partir do cliente; a remota terceiriza a etapa de “gerar resumo” para a OpenAI.

O prompt de compressão

You are performing a CONTEXT CHECKPOINT COMPRESSION. Create a handoff
summary for another LLM that will resume the task.

Include:
- Current progress and key decisions made
- Important context, constraints, or user preferences
- What remains to be done (clear next steps)
- Any critical data, examples, or references needed to continue

Be concise, structured, and focused on helping the next LLM seamlessly
continue the work.

A palavra-chave é handoff — não são atas de reunião, mas um briefing para que o próximo modelo possa retomar o trabalho sem perder o ritmo.

Preservação de mensagens do usuário

Uma característica distintiva do Codex: preserva as mensagens do usuário na íntegra. Apenas compacta respostas do assistente e resultados de ferramentas. Isso significa que o agente sempre pode ver o que o usuário disse originalmente, embora reduza a eficiência da compressão quando as mensagens do usuário são longas.

Fallback: head trimming

Se após a compressão ainda faltar espaço, o Codex recorre ao head trimming — corta a partir das mensagens mais antigas. Isso é destrutivo e é considerado último recurso.

Claude Code: três camadas de precisão

Anthropic’s Claude Code tem o sistema mais sofisticado dos quatro, com três camadas progressivas que vão do mais barato ao mais custoso.

Claude Code não é open source. Esta análise se baseia em engenharia reversa da comunidade e materiais públicos.

Camada 1: Tool Result Trimming (custo LLM = zero)

Esta camada é executada automaticamente antes de cada request. Sem chamadas ao LLM — é puramente um motor de regras local.

A lógica:

• Protege os resultados das tool calls mais recentes
• Tool results antigos → substituídos por [Old tool result content cleared]

O agente lembra que executou uma busca, mas não o resultado. Se precisar do detalhe, pode reexecutar o comando. É amnésia seletiva, não esquecimento total.

Camada 2: Cache-Friendly Strategy

Esta é a vantagem única do Claude Code. A Anthropic suporta Prompt Cache: se o prefixo da sua mensagem para a API coincidir com o request anterior, o servidor reutiliza computações prévias, reduzindo drasticamente custo e latência.

Ao limpar mensagens, o Claude Code deliberadamente evita modificar a primeira metade da sequência. Prefere cortar do final, mantendo o início idêntico para maximizar cache hits.

O trade-off: menor eficiência de limpeza, mas máxima taxa de cache. Para tarefas longas (refatorar um módulo completo), isso se traduz em economias significativas — você paga apenas pelo conteúdo novo no final.

Camada 3: Structured LLM Summary (último recurso, 9 seções)

Quando as duas primeiras camadas não são suficientes, o resumo completo é disparado. O limiar de autocompactação é: janela efetiva - 13.000 tokens.

Antes de chamar o LLM, o sistema tenta Session Memory Compact — usar informações estruturadas já na memória da sessão. Somente quando isso não é possível, cai para o resumo LLM tradicional, que gera 9 seções fixas:

1. Intenção original do usuário
2. Conceitos técnicos centrais
3. Arquivos e código relevantes
4. Erros encontrados e como foram corrigidos
5. Cadeia lógica de resolução de problemas
6. Resumo de todas as mensagens do usuário
7. Tarefas pendentes
8. O que está sendo trabalhado agora
9. Próximos passos sugeridos

O prompt exige citações textuais de frases-chave do original, não paráfrases. Isso previne o “context drift” — que o modelo sutilmente se desvie do significado original ao recontar.

Pós-compressão

Após compactar, o Claude Code executa uma série de passos de reconstrução de estado:

• Injeta um lead-in: “This session continues from a previous conversation…”
• Releitura automática de até 5 arquivos editados recentemente (orçamento de 50K tokens, 5K por arquivo)
• Redeclara tool definitions e skill definitions
• As especificações em CLAUDE.md (system prompt) permanecem intactas

Também há um fallback passivo: se a API retornar prompt_too_long, inicia compressão reativa e tenta novamente. Pausa após 3 falhas consecutivas para evitar loops infinitos.

OpenCode: stepped governance com ocultação não destrutiva

OpenCode (arquivado, anteriormente sst/opencode) oferece a estratégia mais equilibrada, implementada em session/compaction.ts com Effect-TS.

Passo 1: Prune (ocultar, não excluir)

A primeira ação não é excluir — é marcar. OpenCode adiciona um timestamp compacted = Date.now() às mensagens antigas, tornando-as invisíveis em requests subsequentes. Os dados continuam no banco de dados.

Regras:

• Só é executado se puder liberar >20K tokens
• Sempre preserva os últimos 40K tokens como colchão de segurança
• Tool outputs do tipo skill nunca são podados
• Protege o conteúdo completo dos últimos 2 turnos do usuário

Esta é uma decisão de design visionária: os dados não são realmente perdidos. Deixa espaço para futuras auditorias, rollbacks ou funcionalidades de histórico.

Passo 2: LLM Summary de 5 seções

Se após o prune ainda houver problemas, o OpenCode usa um agente oculto dedicado (sem interromper o usuário) que gera um resumo com 5 seções fixas:

1. O que foi feito
2. O que está sendo trabalhado agora
3. Arquivos modificados
4. Próximos passos
5. Decisões técnicas importantes

Auto-replay da última mensagem

A característica mais inteligente do OpenCode: após a compactação, o sistema reenvia automaticamente a última mensagem do usuário. O usuário nem percebe que a compressão ocorreu — sua última mensagem é reprocessada, o agente responde, como se nada tivesse acontecido.

OpenCode também segue o idioma do usuário: se a conversa for em português, o resumo é gerado em português.

Tabela comparativa

O padrão comum

Apesar das diferenças, os quatro sistemas convergem em um padrão compartilhado:

1. Poda barata primeiro: antes de chamar o LLM, todos têm uma fase de limpeza mecânica (tool results → placeholder/ocultação). Isso libera 50-80% do espaço sem gastar um token.
2. Cabeça e cauda sempre protegidas: o system prompt e as mensagens recentes nunca são tocados. O que se resume é a seção intermediária, onde está o trabalho já concluído.
3. Resumo estruturado: formato livre não funciona. Todos usam templates com seções fixas (entre 4 e 9) que guiam o modelo sumarizador.
4. Modelo auxiliar mais barato: ninguém usa o modelo principal para resumir. A compactação é delegada a um modelo secundário (frequentemente 10-100× mais barato).
5. Pós-processamento: após compactar, todos fazem algo para evitar que o agente se “desoriente” — reenviar a última mensagem, reler arquivos, injetar prefixos.

Vale a pena? A matemática do investimento

A compactação de contexto gasta tokens agora para economizar depois. Faz sentido?

Para um modelo como DeepSeek V4 Flash a $0,28/1M tokens de output:

• Custo de uma compactação: gerar um resumo de ~2.000 tokens → ~$0,0006
• Economia por turno posterior: um histórico compactado de 45K tokens vs 95K tokens → economia de $0,014 por turno apenas em input
• Ponto de equilíbrio: após ~1 turno, a compactação já se pagou
• Retorno em 20 turnos: 20× mais barato que sem compactação

Para um modelo premium como Claude Opus 4.8 a $25/1M tokens de output:

• Custo de compactação: ~$0,05 (modelo auxiliar mais barato)
• Economia por turno: ~$1,25
• Retorno em 20 turnos: 25× mais barato

A compactação não é um luxo — é um requisito econômico para que os agentes de IA possam trabalhar em sessões longas sem arruinar seus custos de API.

Implicações para o desenvolvimento de agentes

Se você está construindo seu próprio agente ou escolhendo um existente, estas são as perguntas certas:

• Quantas camadas de compressão você precisa? Uma camada (como Codex) é suficiente para sessões curtas. Duas camadas (como Hermes) dão segurança contra escapes. Três camadas (como Claude Code) otimizam custos em sessões muito longas.
• A irreversibilidade é importante? OpenCode é o único que não destrói dados. Se você faz auditorias ou precisa de rollbacks, sua abordagem de timestamp é superior.
• Você usa Anthropic? A integração Prompt Cache do Claude Code ou Hermes pode reduzir seus custos ~75% em sessões multi-turno.
• O modelo auxiliar importa? Muito. Se seu modelo auxiliar tiver uma janela de contexto menor que o principal, as compactações falharão silenciosamente (Hermes documenta isso como “a causa mais comum de degradação”).

No final, os quatro sistemas demonstram que a melhor gestão de contexto não é expandir a memória do modelo, mas aprender a esquecer com precisão.

Fonte principal: Hermes Agent Documentation — Context Compression and Caching | Código-fonte: Hermes Agent, Codex CLI, OpenCode (arquivado)