> ## Documentation Index > Fetch the complete documentation index at: https://chatcli.edilsonfreitas.com/llms.txt > Use this file to discover all available pages before exploring further. # Compressão de Contexto (CCR) > Camada de compressão content-aware e reversível: encolhe saída de tools, logs, diffs, JSON, código e prosa antes do modelo — keyless, pura-Go, sem perder informação. Inclui redução de tokens de saída e compressão de imagem. O ChatCLI tem uma camada nativa de **compressão de contexto** que reduz drasticamente os tokens consumidos pelos payloads volumosos que um agente lê (resultados de busca, logs, diffs, JSON, código) e gera (verbosidade da resposta) — **sem nunca perder informação** e **sem nenhuma dependência externa**: tudo é Go puro da biblioteca padrão, keyless, sem cgo, sem modelo treinado e sem rede. 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: 1. Estoura a janela de contexto e força compactação agressiva (que perde informação). 2. Multiplica o custo a cada turno do loop ReAct. 3. Quebra o cache de prefixo do provedor quando conteúdo volátil entra cru. A camada de compressão ataca isso na origem, mantendo só o que o modelo precisa para agir e mandando o resto para o store reversível. *** ## 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: | Tipo de conteúdo | Estratégia | Redução típica | Auto-dispara? | | - | - | - | - | | Resultados de busca (grep/ripgrep) | `search` — agrupa por arquivo, mantém primeira/última + linhas de erro, caps | \~78–92% | Sim | | Logs de build/test/runtime | `log` — mantém erros, stack traces, warnings dedupados, summary; descarta ruído | \~92–99% | Sim | | Diffs unified (git) | `diff` — mantém +/-, apara contexto, caps de hunks/arquivos | \~87% | Sim | | Arrays JSON grandes | `json-crush` — compacta whitespace (lossless) + amostra de itens com sentinela | \~96% | Sim | | Código-fonte | `code-ast` — esqueleto (assinaturas, sem corpos) via `go/ast` + heurística | \~41% | **Não** (só explícito) | | Prosa / Markdown (web/docs) | `prose` — dedup de boilerplate, colapsa blank-runs, apara seções | \~44% | Só web/explícito | **Código nunca é comprimido automaticamente.** Apagar o corpo de um arquivo que o agente está prestes a editar seria nocivo. O `code-ast` só roda quando explicitamente pedido (`@compress` com `hint=code`). A prosa só auto-dispara em conteúdo de **web** (`@webfetch`/`@websearch`/`@wikipedia`) — material de referência — nunca em leitura de arquivo local. ### CCR — Contextual Compression Retrieval Quando um compressor descarta parte de um payload, o **original completo** é gravado num store local e um marcador `<>` é 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). Se o modelo precisar do detalhe descartado, ele chama `@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ção `Archive` — 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 `<>` 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](/pt/context/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. O `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` 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. Recupera o original completo de um marcador `<>`. 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. Ambas entram automaticamente no completer e na palette. 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](/pt/extensions/skill-registry#budget-de-injeção-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 | Modo | Onde a compressão engata | | - | - | | **agent / coder** | Saída de cada tool é comprimida no chokepoint do loop, antes de entrar no histórico (cobre o caminho structured-native e o legacy). Erros vão verbatim para o modelo poder depurar. | | **chat** | Na compactação de histórico: feedback de tool volumoso e **contexto anexado** são reduzidos de forma reversível (CCR) em vez de truncados — ganho principal do chat, que é tool-less. | | **sub-agents / workers** | Agentes delegados comprimem sua saída pelo **mesmo store compartilhado**. Como o CCR é content-addressed, conteúdo idêntico lido por agentes irmãos é gravado uma vez só (**dedup cross-agent**) e recuperável de qualquer um deles. | *** ## 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. Controle em runtime via `/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](/pt/usage/vision-input). 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 compression # painel: modo, perfil, threshold, store CCR, economia — cada linha com a sua variável (CHATCLI_COMPRESSION, _PROFILE, _THRESHOLD, _CCR_DIR, _CCR_MAX_MB, _CCR_TTL); o /config conhece o default e a origem de cada uma /config compression lossy # redução total, reversível via @recall (padrão) /config compression lossless # apenas reduções lossless (sem descartar linhas) /config compression off # desativa /config compression stats # resumo de economia por estratégia /config compression prune # cura o store CCR agora (TTL + cap de tamanho) /config compression profile conservative|default|aggressive # agressividade /config compression threshold # limiar de acionamento ``` ### `/config output` ``` /config output # painel: verbosidade + effort routing /config output concise # corta cerimônia, mantém substância (padrão) /config output minimal # menos tokens corretos possível /config output full # sem steering /config output effort on|off # roteamento de esforço por complexidade (opt-in) ``` ### Variáveis de ambiente | Variável | Descrição | Padrão | | - | - | - | | `CHATCLI_COMPRESSION` | Modo: `off`, `lossless`, `lossy-with-ccr` | `lossy-with-ccr` | | `CHATCLI_COMPRESSION_PROFILE` | Agressividade: `conservative`, `default`, `aggressive` | `default` | | `CHATCLI_COMPRESSION_THRESHOLD` | Bytes abaixo dos quais a saída é byte-idêntica (passthrough) | `4000` | | `CHATCLI_COMPRESSION_CCR_DIR` | Diretório do store CCR | `~/.chatcli/ccr` | | `CHATCLI_COMPRESSION_CCR_MAX_MB` | Cap de tamanho do store em MiB (`0` = sem cap) | `256` | | `CHATCLI_COMPRESSION_CCR_TTL` | TTL das entradas do CCR (duração Go; `0` = sem TTL) | `168h` | | `CHATCLI_OUTPUT_VERBOSITY` | Verbosity steering: `full`, `concise`, `minimal` | `concise` | | `CHATCLI_OUTPUT_EFFORT_ROUTING` | Effort routing por complexidade (opt-in) | `off` | 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. Para ver os ganhos na prática: rode um `@search`/grep grande ou um `go test` verboso no `/agent`, observe a saída comprimida + o marcador `<>`, depois `@recall` para confirmar o original byte-idêntico, e `/config compression stats` para a economia da sessão. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.