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.
Mostra estatísticas globais sobre todos os seus contextos (número total, tamanho, etc.).
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.