Skip to main content
Enquanto o gerenciamento de sessões (/session) salva o histórico da conversa, o gerenciamento de contextos (/context) salva o conteúdo do seu ambiente de trabalho. É a funcionalidade mais poderosa para quem trabalha em múltiplos projetos ou precisa consultar frequentemente a mesma base de código. Um Contexto é um “snapshot” nomeado de um ou mais arquivos e diretórios, processado e salvo em disco para ser reutilizado a qualquer momento.

​
O Ciclo de Vida de um Contexto

A utilização de contextos segue um fluxo simples e poderoso:
1

Criar (/context create)

Você define um conjunto de arquivos e pastas, processa-os com um modo específico (ex: smart, chunked) e salva o resultado com um nome.
2

Anexar (/context attach)

Você “anexa” um ou mais contextos salvos à sua sessão de conversa atual.
3

Usar

Enquanto estiver anexado, o conteúdo do contexto será automaticamente enviado para a IA em todos os seus prompts, fornecendo um conhecimento profundo e contínuo sobre seu projeto.
4

Desanexar (/context detach)

Quando não precisar mais do contexto, você o desanexa para liberar espaço no prompt da IA.

​
Comandos de Gerenciamento de Contexto

Aqui estão todos os subcomandos disponíveis para gerenciar seus contextos.

​
create: Criar um Novo Contexto

Cria e salva um novo contexto a partir de arquivos e diretórios. Sintaxe:
Opções: Exemplo:

​
attach e detach: Anexar e Desanexar da Sessão

Estes comandos controlam quais contextos estão ativos na sua conversa atual.

​
Anexação Avançada de Chunks

Se um contexto foi criado com --mode=chunked, você pode anexar partes específicas dele: Exemplo:

​
--rag: Retrieval Semântico (não despeje dados brutos)

O problema: injetar arquivos inteiros estoura a janela de contexto em qualquer base não-trivial. A flag --rag resolve: em vez do dump bruto, embeda as passagens do contexto e, a cada turno, injeta só as top-K mais relevantes à pergunta atual. Para corpora de documentação ou de código/infra, prefira o --mode knowledge: mesmo princípio, mas sem exigir API key (BM25 keyless), com index card no prompt e a tool @knowledge para o agente investigar.
Como funciona:
1

Segmentação

Os arquivos são divididos em passagens line-aware com overlap (~300 tokens cada) — granularidade fina, distinta do chunk de token-budget. IDs são hash de conteúdo, então arquivos inalterados pulam re-embedding.
2

Embed once, cache em disco

As passagens são embeddadas de forma lazy e persistidas por contexto; passagens editadas/removidas são podadas (nunca servem texto obsoleto).
3

Retrieve no prompt

A query do turno é embeddada e as top-K passagens por cosseno (com floor de relevância) são injetadas.
Requer um embedding provider (CHATCLI_EMBED_PROVIDER — voyage, openai ou bedrock). Sem provider, o --rag faz fallback transparente para conteúdo completo, com um aviso. Setou o provider depois de abrir o ChatCLI? /reload reconstrói e re-conecta na hora.
Auto-RAG para contextos grandes: com um embedding provider configurado, um contexto de 32 KiB ou mais anexado sem flag explícita é automaticamente promovido a retrieval semântico (top-8 passagens por turno) — o mesmo default que a ferramenta @context do agent sempre usou. O upgrade é anunciado na hora do attach; opt-out por chamada com --full/-f ou global com CHATCLI_ATTACH_AUTO_RAG=off. Contextos pequenos e setups sem embeddings mantêm o comportamento verbatim de conteúdo inteiro, sem mudança.
Cache-aware: o conteúdo recuperado é query-driven, então é injetado na zona volátil do prompt — nunca polui o prefixo cacheado. E --rag não combina com --chunk(s) (seleção semântica vs. manual são contraditórias).
Numa medição sintética, o bloco injetado caiu para 44% do tamanho bruto ainda recuperando a passagem certa de uma query por sinônimo — em contextos grandes a economia é muito maior. Reusa o mesmo primitivo vindex do RAG + HyDE — provider-agnostic, OS-agnostic. O único knob de env é o gate do auto-upgrade, CHATCLI_ATTACH_AUTO_RAG (on por padrão).

​
list, show, e inspect: Visualizar Contextos

Estes comandos ajudam você a entender o que há em seus contextos salvos.

​
Outros Comandos de Gerenciamento

Deleta um contexto permanentemente.
Combina múltiplos contextos em um novo, removendo arquivos duplicados.
Exporta um contexto para um arquivo JSON, facilitando o backup e compartilhamento.
Importa um contexto a partir de um arquivo JSON.
Reindexa um contexto a partir dos paths de origem. Cada arquivo carrega um carimbo (tamanho, mtime, hash do conteúdo) da última varredura: um corpus sem mudanças é reportado como em dia e nada é reconstruído — caches de retrieval e vetores continuam válidos — enquanto um arquivo editado, adicionado ou removido dispara uma reconstrução em que só as passagens que de fato mudaram são re-embutidas (ids de passagem são hashes de conteúdo). Um touch sem edição não conta como mudança. Contextos criados antes de os paths de origem serem registrados adotam os paths dos arquivos que contêm no primeiro refresh ou watch (persistidos daí em diante); um /context update <nome> <paths> continua registrando-os explicitamente.
Mantém um contexto em dia com os paths de origem via watcher do sistema de arquivos: diretórios são observados recursivamente (diretórios de ruído como node_modules e .git ignorados, subdiretórios novos incluídos), rajadas de eventos assentam por 1,5 s e viram um único refresh, e o resultado aparece no próximo prompt como contexto <nome> atualizado: N alterados, M adicionados, K removidos. Os watches duram a sessão (e por tenant no gateway) e param na saída.
Mostra estatísticas globais sobre todos os seus contextos (número total, tamanho, etc.).
Orçamento do prefixo. O prefixo do sistema (cartão de modo, anexos, digests, skills, catálogo de tools) pode ocupar metade da janela antes de degradar, numa ordem declarada: corpos de skills viram ponteiros de leitura sob demanda, digests de conhecimento encolhem para o cartão compacto, anexos de conteúdo inteiro viram um cartão-índice que lista os arquivos e como puxá-los (/context attach <nome> --rag). Quando o provedor sabe contar tokens (veja Custo → Contagem de tokens por provedor), o relatório também imprime o tamanho do histórico vivo contado pelo provedor e atualiza a razão aprendida a partir dele. O relatório mostra o orçamento, o uso e o que dobrou; nada dobra enquanto o prefixo cabe. O prefixo do chat também passa a ser reservado do orçamento de compactação, e o ctx N% do rodapé agora é a projeção da próxima requisição (pode passar de 100% logo antes de um auto-compact).Responde “o que está no meu contexto agora e quanto custa cada parte”. Lista cada seção do último system prompt montado (banner de modo, contextos anexados, skills, catálogo MCP, workspace e memória, blocos de recall, contexto dinâmico — seções do prefixo cacheado marcadas com ●), o histórico da conversa por papel com resumos compactados e segmentos recuperáveis via @recall, e os totais: system prompt, histórico, próxima requisição projetada como parcela da janela do modelo e o ponto em que o auto-compact dispara. Os números de tokens usam a razão chars/token aprendida dos relatórios de uso reais do provedor para o modelo ativo (o padrão 4 até o primeiro relatório), convergindo com o ctx% do rodapé.
Exibe uma tela de ajuda específica para os comandos de contexto.

​
Próximos Passos

Você agora conhece os recursos mais poderosos de automação e gerenciamento de contexto do ChatCLI. Para finalizar, vamos documentar as funcionalidades que garantem a portabilidade e a integração da ferramenta em scripts.

Modo Não-Interativo

Use o ChatCLI em scripts, automações e pipelines de CI/CD.

Gerenciamento de Sessões

Salve e restaure históricos de conversa completos.