> ## 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/features/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). |

**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/features/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. É **opt-in**: sem `--rag`, o anexo se comporta exatamente como antes (zero regressão).</Warning>

<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/features/quality/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.

| 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 metrics">
    Mostra estatísticas globais sobre todos os seus contextos (número total, tamanho, etc.).
  </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/features/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/features/session-management">
    Salve e restaure históricos de conversa completos.
  </Card>
</CardGroup>

***