A camada é reversível por design: redução com perda só acontece quando o conteúdo original é primeiro gravado num store local (CCR) e um marcador é embutido no prompt. O modelo recupera o original verbatim com
@recall. Abaixo de um limiar de tamanho, a saída é byte-idêntica à de antes.Por que isso importa
Um único@search em uma base grande, um go test ./... verboso ou uma resposta de API JSON podem injetar dezenas de milhares de tokens no contexto — a maioria redundante. Sem compressão, esse volume:
- Estoura a janela de contexto e força compactação agressiva (que perde informação).
- Multiplica o custo a cada turno do loop ReAct.
- Quebra o cache de prefixo do provedor quando conteúdo volátil entra cru.
Como funciona
Um ContentRouter detecta o tipo de conteúdo (ou confia em uma dica da tool de origem) e roteia para o compressor certo. Cada compressor é determinístico e específico de um tipo:CCR — Contextual Compression Retrieval
Quando um compressor descarta parte de um payload, o original completo é gravado num store local e um marcador<<ccr:HASH>> é embutido na saída. O store é:
- Content-addressed (chave = hash SHA-256 do conteúdo) → dedup natural: o mesmo conteúdo é gravado uma vez só.
- Bounded (cap de tamanho via LRU + TTL) e crash-safe (sem índice corruptível — o diretório é o índice).
- Validado no boundary: chaves são validadas como hex de largura fixa antes de virar caminho de arquivo (sem path traversal).
@recall e recebe o original byte-idêntico.
Compactação com perda zero
O CCR não se limita ao router de compressão: todo caminho de compactação lossy do agent loop arquiva antes de cortar. A camada expõe uma operaçãoArchive — gravação verbatim no store, sem heurísticas de compressão — usada por:
- Microcompact: tool results antigos degradados a previews head+tail ou summaries de uma linha embutem um marcador
<<ccr:KEY>>apontando para o original arquivado. Os marcadores sobrevivem entre níveis — quando um preview depois vira summary, o marcador permanece no summary. - Encolhimento de emergência de payload (context recovery): quando um limite de corpo de proxy/WAF força a truncagem dura de conteúdo de mensagens, cada mensagem é arquivada uma vez antes do primeiro corte e o conteúdo encolhido mantém um marcador de recall.
Archive é idempotente por construção: conteúdo que já carrega um marcador CCR é recusado (o original dele está gravado sob aquela chave), então rodadas repetidas de compactação nunca duplicam entradas no store. Efeito líquido: nenhum caminho de compactação do ChatCLI descarta bytes de forma irrecuperável enquanto a camada está ativa — a janela da conversa fica pequena, o conhecimento continua alcançável.
Tools @compress e @recall
tool
Comprime um payload sob demanda. Aceita
{"content":"...","hint":"auto|log|search|diff|json|code|prose"} e devolve a forma reduzida com o original preservado no CCR. O subcomando {"cmd":"stats"} reporta a economia da sessão.tool
Recupera o original completo de um marcador
<<ccr:KEY>>. Tolerante por design — aceita a chave nua de 16-hex, o marcador inteiro e as variantes de paste-back que os modelos realmente produzem (ccr:KEY sem os colchetes angulares, colchete simples, hex maiúsculo, marcador no meio de texto, campos JSON alternativos como marker ou id). Múltiplos marcadores numa chamada retornam cada original em uma seção rotulada, com misses por chave reportados no lugar. Uma chave única continua retornando o original byte-idêntico. Use quando a visão comprimida omitiu algo necessário.Markers de
@recall aparecem em qualquer lugar onde o ChatCLI arquivou bytes antes de uma reescrita lossy — outputs de tool comprimidos, tool results antigos microcompactados, mensagens encolhidas em emergência e blocos de skill envelhecidos (o ciclo de vida de skills colapsa guidance mid-loop stale para um stub carregando seu marker). Uma ferramenta recupera todos.Compressão automática em todos os modos
Redução de tokens de saída
Complementar à compressão de entrada, o ChatCLI reduz os tokens que o modelo gera:- Verbosity steering — uma diretiva estática (cache-friendly) injetada no prefixo cacheado do system prompt instrui o modelo a cortar preâmbulo, repetição da pergunta e cerimônia, e a liderar com a resposta/ação. Níveis:
full(desligado),concise(padrão),minimal. - Effort routing (opt-in) — um classificador de complexidade keyless baixa o esforço de raciocínio em prompts triviais. Só baixa para prompts claramente triviais e só quando nenhum esforço foi escolhido — nunca sobrepõe escolha de skill/usuário e nunca aumenta, então não degrada tarefas difíceis.
/config output (veja abaixo).
Compressão de imagem (vision)
Imagens são encolhidas antes de irem para modelos com visão — veja a página de Entrada de Visão. Resumo: downscale da maior aresta para 1568px (o que os provedores já fazem server-side, então é token-equivalente) + re-encode JPEG de fotos, preservando transparência (PNG), sem nunca inflar o payload. Keyless, puro-Go.Configuração
/config compression
/config output
Variáveis de ambiente
A economia de cada turno aparece no footer do chat (ex.:
🗜 12K saved); o acumulado da sessão fica em /config compression stats, junto com a taxa de acerto do @recall.
Garantias (nunca degradar)
- Resultado irreversível ou que não encolhe → passthrough verbatim (o router rejeita).
- Sem CCR disponível (modo lossless / sem store) → compressores com perda não descartam nada.
- Idempotente: conteúdo já comprimido (com marcador) não é re-comprimido.
- Erros de tool vão verbatim para o modelo poder depurar.