Pular para o conteúdo principal
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: 
/context create <nome-do-contexto> <caminho_1> [caminho_2...] [opções]
Opções:
FlagDescrição
--mode <modo> ou -mDefine como os arquivos serão processados. Modos: full, summary, chunked, smart ou knowledge (corpora de docs como base de conhecimento RAG keyless).
--description <texto> ou -dAdiciona uma descrição textual para ajudar a identificar o contexto.
--tags <tag1,tag2> ou -tAdiciona tags para facilitar a filtragem e organização.
--force ou -fSobrescreve um contexto existente com o mesmo nome.
Exemplo: 
# Cria um contexto 'api-core' com o modo smart, descrição e tags
/context create api-core ./src/services ./docs/api \
  --mode smart \
  --description "Contexto com o núcleo da API e documentação" \
  --tags golang,api

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

Estes comandos controlam quais contextos estão ativos na sua conversa atual.
ComandoDescrição
/context attach <nome-do-contexto>Anexa um contexto à sessão.
/context detach <nome-do-contexto>Remove um contexto da sessão.
/context attachedLista todos os contextos atualmente anexados.

​
Anexação Avançada de Chunks

Se um contexto foi criado com --mode=chunked, você pode anexar partes específicas dele:
FlagDescrição
--chunk <N>Anexa apenas o chunk de número N.
--chunks <N,M,...>Anexa uma lista de chunks específicos.
--priority <num>Define a ordem em que os contextos anexados são enviados (menor número = maior prioridade).
--rag [K] (ou --retrieve, -r)Retrieval semântico: injeta só as top-K passagens relevantes ao turno, em vez do conteúdo bruto. K opcional (default 8).
Exemplo: 
# Anexa apenas os chunks 1 e 3 do contexto 'legado-db' com alta prioridade
/context attach legado-db --chunks 1,3 --priority 10

​
--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, 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.
# Anexa 'api-core' em modo retrieval — só as passagens relevantes por turno
/context attach api-core --rag
# Ou controle o K (nº de passagens):
/context attach api-core --rag 12
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. É opt-in: sem --rag, o anexo se comporta exatamente como antes (zero regressão).
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, sem novos env vars.

​
list, show, e inspect: Visualizar Contextos

Estes comandos ajudam você a entender o que há em seus contextos salvos.
ComandoDescrição
/context listLista todos os contextos disponíveis, com metadados básicos.
/context show <nome>Exibe informações detalhadas de um contexto, incluindo a lista completa de arquivos.
/context inspect <nome>Fornece uma análise estatística profunda do contexto, como distribuição de tipos de arquivo, contagem de linhas e análise de tamanho dos chunks. Use --chunk N para inspecionar um chunk específico.

​
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.