O gate que se recusa a compactar: o que compression.checkpoint_required realmente protege


Três horas dentro de uma sessão, a janela de contexto enche, o Hermes compacta, e você segue trabalhando. Dois dias depois você pergunta por que uma decisão foi tomada e recebe uma resposta confiante que, na verdade, é o resumo de um resumo. Nada está corrompido, exatamente — mas a coisa de que você precisava nunca foi escrita em lugar durável nenhum, e o transcript que a guardava foi reescrito.

É essa falha que compression.checkpoint_required existe para impedir. É um instrumento grosseiro: com o gate armado, o Hermes prefere se recusar a compactar a reescrever seu histórico sem backup.

A ideia em uma frase

Compactação tem perda por definição — um transcript longo vira um resumo mais curto mais uma cauda recente. O gate diz: antes de essa reescrita acontecer, alguém precisa ter gravado uma cópia durável do transcript não comprimido e me avisado que gravou.

Quem é “alguém”? Um plugin de provedor de memória. Não o sumarizador, não o banco de dados de sessões, não o modelo.

Como ligar

compression:
  checkpoint_required: true   # padrão: false

ou, de forma equivalente:

hermes config set compression.checkpoint_required true
hermes config get compression.checkpoint_required

Essa é toda a superfície de operação. Tudo abaixo é sobre o que ele muda, porque as consequências são maiores do que um booleano sugere.

O que o gate bloqueia

Com o gate armado, uma tentativa de compactação falha fechada antes de qualquer reescrita com perda:

  • o transcript não comprimido é preservado exatamente como está;
  • a tentativa dá erro com BLOCKED_MISSING_PREREQUISITE e um motivo que nomeia o que faltou;
  • ela pode ser repetida assim que seu store de arquivo se recuperar.

O gate também vincula toda autoridade de compactação, não só o sumarizador do Hermes. A compactação nativa do lado do servidor é suprimida enquanto o gate está armado, a micro-compactação pós-turno é forçada a desligar na inicialização do agent (ela absorve trocas antigas em um resumo rolante sem nenhum gancho de checkpoint no caminho), e o modo de API codex_app_server é recusado na inicialização — esse runtime compacta a própria thread sem uma fronteira pré-compactação confiável, então um checkpoint obrigatório não pode ser garantido ali. O compressor do Hermes, que conhece checkpoints, continua sendo a única autoridade com perda.

Essa última parte é a troca honesta: ligar o gate torna a compactação mais rígida e, em alguns runtimes, impossível. É uma configuração de integridade de dados, não de desempenho.

O que um provedor precisa implementar

O contrato é pequeno e explícito. Um provedor adere declarando a versão 2 da API:

from agent.memory_provider import MemoryProvider

class MyArchivingProvider(MemoryProvider):
    pre_compress_checkpoint_api_version = 2

    def on_pre_compress(self, messages, *, require_checkpoint=False):
        ids = self._archive(messages)   # precisa estar durável antes de retornar
        return f"checkpoint: {ids}"     # encaminhado para o prompt de resumo

require_checkpoint espelha a configuração do operador: quando é True, levantar uma exceção neste método é o que bloqueia a reescrita com perda. Retornar significa “a cópia durável foi gravada” — então sucesso parcial não é uma opção, e a documentação é explícita: levante exceção em qualquer falha em vez de retornar otimisticamente.

Provedores de versão 2 também recebem evidência direta normalizada em vez da lista bruta: apenas linhas de texto do usuário e do assistente. Resultados de ferramenta, mensagens de sistema, o payload tool_calls das mensagens do assistente e resumos de compactação anteriores são filtrados no host. Resumos anteriores são reconhecidos através de um marcador persistente, então uma sessão retomada nunca realimenta resumos derivados no seu arquivo como se fossem evidência original.

Mais um requisito que surpreende as pessoas: checkpoints precisam ser idempotentes. Depois de um bloqueio fail-closed, a próxima tentativa chama on_pre_compress() de novo com o mesmo transcript, e um transcript que cresceu um pouco produz evidência em grande parte sobreposta. Indexe as escritas do arquivo por conteúdo — um digest do transcript, por exemplo — e faça upsert, ou as repetições vão empilhar duplicatas.

O que mudou em 6 de novembro

O gate saiu antes, mas tinha uma aresta afiada que precisou de um follow-up para consertar (PR #149763, mesclado em 6 de novembro de 2026). Dois problemas:

  • Subagentes e forks eram construídos com a memória desativada. delegate_task, o curator, o executor de lotes e os turnos de comentário do Feishu rodam cada um seu próprio transcript, e esses forks eram criados com skip_memory=True. Com o gate armado, a primeira compactação deles falhava com BLOCKED_MISSING_PREREQUISITE — não porque houvesse algo errado com seu provedor, mas porque o fork nunca recebeu um.
  • A poda proativa de resultados de ferramenta ignorava o gate. Ela descarta resultados grandes de ferramenta para recuperar tokens sem uma chamada de LLM, e estava descartando sem checkpoint primeiro — apagando em silêncio evidência que o gate deveria proteger.

Os dois estão corrigidos. Os forks agora mantêm o provedor enquanto o gate está armado, e o host suprime as escritas e o recall deles (eles rodam sob um contexto de subagente em vez de fingir que são você). A poda é retida no ponto de chamada até que exista um checkpoint.

Se você ligou o gate antes dessa correção e viu turnos de subagente morrendo na primeira compactação, é por isso — e vale tentar de novo agora.

Você deve ligar?

Faça uma pergunta: um transcript compactado é recuperável para você hoje?

Se sua resposta é “o resumo basta”, deixe o gate desligado. Ele vem desligado por padrão, e nenhum dos provedores que acompanham o Hermes anuncia a API de checkpoint v2 — ative o gate sem um provedor v2 e você bloqueia toda tentativa de compactação, manual e automática. A inicialização do agent registra um aviso nomeando o provedor ativo, e cada recusa nomeia compression.checkpoint_required como a chave a desativar, então ele falha alto em vez de em silêncio.

Se sua resposta é “temos um arquivo de todas as conversas e precisamos que ele esteja completo”, o gate converte uma perda silenciosa em uma parada barulhenta, que costuma ser o que você quer em um deployment regulado ou de longa duração. Combine-o com um provedor que faça upsert por digest, e coloque no orçamento o fato de que o comportamento da compactação passa a ser determinístico em vez de best-effort.

Para o panorama em volta — quanto da sua janela a compactação recupera e para onde os tokens realmente vão —, o guia de otimização de tokens de contexto é a leitura companheira. E se você vai atualizar de qualquer forma, a página da release v0.23.0 lista as outras mudanças de compactação deste ciclo, incluindo a compactação preparada opcional que escreve o próximo resumo em background.