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

# Gerenciamento de Contexto Persistente

> Domine o gerenciamento de contextos para salvar, anexar e reutilizar snapshots de projetos, tornando sua interação com a IA mais rápida e poderosa.

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:

<Steps>
  <Step title="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.
  </Step>

  <Step title="Anexar (/context attach)">
    Você "anexa" um ou mais contextos salvos à sua sessão de conversa atual.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Desanexar (/context detach)">
    Quando não precisar mais do contexto, você o desanexa para liberar espaço no prompt da IA.
  </Step>
</Steps>

***

## 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:**

```bash theme={"system"}
/context create <nome-do-contexto> <caminho_1> [caminho_2...] [opções]
```

**Opções:**

| Flag | Descrição |
| :- | :- |
| `--mode <modo>` ou `-m` | Define como os arquivos serão processados. Modos: `full`, `summary`, `chunked`, `smart` ou [`knowledge`](/pt/context/knowledge-base) (corpora de docs ou de código/infra como base de conhecimento RAG keyless). |
| `--description <texto>` ou `-d` | Adiciona uma descrição textual para ajudar a identificar o contexto. |
| `--tags <tag1,tag2>` ou `-t` | Adiciona tags para facilitar a filtragem e organização. |
| `--force` ou `-f` | Sobrescreve um contexto existente com o mesmo nome. |

**Exemplo:**

```bash theme={"system"}
# 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.

| Comando | Descrição |
| :- | :- |
| `/context attach <nome-do-contexto>` | Anexa um contexto à sessão. |
| `/context detach <nome-do-contexto>` | Remove um contexto da sessão. |
| `/context attached` | Lista 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:

| Flag | Descriçã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). |
| `--full` (ou `-f`) | **Attach de conteúdo inteiro, explícito** — desativa o upgrade automático para RAG em contextos grandes (abaixo). |

**Exemplo:**

```bash theme={"system"}
# 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)

<Info>**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`](/pt/context/knowledge-base): mesmo princípio, mas **sem exigir API key** (BM25 keyless), com index card no prompt e a tool `@knowledge` para o agente investigar.</Info>

```bash theme={"system"}
# 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:**

<Steps>
  <Step title="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.
  </Step>

  <Step title="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).
  </Step>

  <Step title="Retrieve no prompt">
    A query do turno é embeddada e as top-K passagens por cosseno (com floor de relevância) são injetadas.
  </Step>
</Steps>

<Warning>**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.</Warning>

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

<Tip>**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).</Tip>

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](/pt/agents/harness/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.

| Comando | Descrição |
| :- | :- |
| `/context list` | Lista 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

<AccordionGroup>
  <Accordion title="/context delete <nome>">
    Deleta um contexto permanentemente.
  </Accordion>

  <Accordion title="/context merge <novo-nome> <ctx1> <ctx2>">
    Combina múltiplos contextos em um novo, removendo arquivos duplicados.
  </Accordion>

  <Accordion title="/context export <nome> <caminho.json>">
    Exporta um contexto para um arquivo JSON, facilitando o backup e compartilhamento.
  </Accordion>

  <Accordion title="/context import <caminho.json>">
    Importa um contexto a partir de um arquivo JSON.
  </Accordion>

  <Accordion title="/context refresh <nome>">
    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.
  </Accordion>

  <Accordion title="/context watch <nome> [off] · watch list · unwatch <nome>">
    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.
  </Accordion>

  <Accordion title="/context metrics">
    Mostra estatísticas globais sobre todos os seus contextos (número total, tamanho, etc.).
  </Accordion>

  <Accordion title="/context status">
    **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](/pt/providers/cost-tracking#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é.
  </Accordion>

  <Accordion title="/context help">
    Exibe uma tela de ajuda específica para os comandos de contexto.
  </Accordion>
</AccordionGroup>

***

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

<CardGroup cols={2}>
  <Card title="Modo Não-Interativo" icon="terminal" href="/pt/usage/non-interactive-mode">
    Use o ChatCLI em scripts, automações e pipelines de CI/CD.
  </Card>

  <Card title="Gerenciamento de Sessões" icon="clock-rotate-left" href="/pt/context/session-management">
    Salve e restaure históricos de conversa completos.
  </Card>
</CardGroup>

***


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.