> ## 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. # Knowledge Base (RAG keyless) > Transforme corpora de documentação ou repositórios de código/infra (Terraform, Kubernetes/Argo) em base de conhecimento: index card de ~900 tokens no prompt, retrieval híbrido BM25 + embeddings por turno, e a tool @knowledge para o agente investigar — tudo sem API key. Um corpus de documentação de **6MB** vira **\~1,5M de tokens** se anexado inteiro — estoura a janela de qualquer modelo no primeiro turno. O modo `knowledge` do [`/context`](/pt/features/persistent-context) resolve com o mesmo padrão pull-first da [memória persistente](/pt/features/bootstrap-memory): a conversa recebe só um **index card** (o que a base cobre), e o conteúdo é **recuperado sob demanda** — automaticamente a cada turno e, no agente, iterativamente via tool `@knowledge`. ```bash theme={"system"} # 1. Achate a doc (ex.: plugin @docs-flatten) → JSONL @docs-flatten --repo https://github.com/org/docs.git --format jsonl --output docs.jsonl # 2. Indexe como knowledge base (JSONL nativo; diretórios também funcionam) /context create minha-doc docs.jsonl --mode knowledge # 3. Anexe — custo fixo de ~900 tokens/turno, com 6MB ou 60MB /context attach minha-doc ``` | | Attach tradicional (`full`) | `--mode knowledge` | | --------------- | ------------------------------------- | ------------------------------------------------------- | | Custo no prompt | corpus inteiro (\~1,5M tokens p/ 6MB) | **index card (\~900 tokens, fixo)** | | Conteúdo | empurrado de uma vez | **puxado por relevância, a cada turno** | | API key | — | **nenhuma** (BM25 puro-Go; embeddings = boost opcional) | | Conhecimento | truncado/estourado | íntegro, pesquisável e citável por `source` | *** ## Como funciona ### Ingestão nativa do JSONL (docs-flatten) Cada linha do JSONL vira um **documento virtual** preservando `source`, título e proveniência (`repoUrl`/`commit`) — em vez de entrar como um blob de texto único. Linhas malformadas são contadas e puladas, nunca fatais. Diretórios comuns também viram knowledge base (scanner normal, até 100MB). O `@docs-flatten` aceita **três fontes** para o mesmo JSONL: `root=` (pasta local), `repo=` (clone raso) e `url=` (crawl raso mesmo-domínio para docs que só existem como site HTML, sem repo de Markdown). ### Código e infraestrutura (`kind=code`) Além de documentação, o `@docs-flatten` ingere **repositórios de código-fonte, Terraform e GitOps (Kubernetes/Argo)** — no mesmo schema JSONL, então o knowledge mode não muda nada do lado de baixo. O parâmetro `kind` controla o que entra e como é fatiado: | `kind` | O que ingere | | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `docs` (default) | Só Markdown/MDX. Comportamento legado — fluxos de doc existentes nunca passam a engolir código por acidente. | | `code` | **Também** código-fonte, Terraform, YAML Kubernetes/Argo e shell, fatiados **por estrutura** (funções, recursos, manifests) com título de símbolo/recurso. É o modo "aponte para um repo de app/infra/GitOps". | | `auto` | Por arquivo: Markdown fica Markdown, código/config fatia por estrutura, outro texto vira janela. | O **fatiamento é agnóstico de linguagem** — não depende de uma lista de palavras-chave por linguagem, então não quebra ao trocar de stack: | Arquivos | Unidade de chunk | Título | | ----------------------------------------------------- | -------------------------------------- | ------------------------------------------ | | `.go .java .kt .ts .rs .cs .cpp .swift .scala .php` … | declaração de topo (balanço de chaves) | símbolo (`HandleCheckout`, `OrderService`) | | `.tf .tfvars .hcl` | bloco Terraform | `tipo.nome` (`aws_eks_cluster.main`) | | `.yaml .yml` | documento (`---`) | `Kind/nome` (`Rollout/checkout-api`) | | `.py .rb` | `def`/`class` de topo (indentação) | símbolo | | `.sh .bash` | função / bloco top-level | nome da função | | qualquer outro texto | janela por tamanho | caminho do arquivo | O título é **metadado best-effort**: se a heurística não reconhecer a linguagem, ele cai na linha de assinatura limpa — **o conteúdo é sempre indexado e buscável**, um título perdido nunca custa recall. Ruído é pulado por default (`vendor/`, `node_modules/`, `.terraform/`, lockfiles, minificados, binários) e arquivos acima de **1 MiB** são ignorados. ```bash theme={"system"} # Uma base por camada — app, infra e gitops @docs-flatten root=./app kind=code format=jsonl output=app.jsonl @docs-flatten root=./infra kind=code format=jsonl output=infra.jsonl # blocos .tf @docs-flatten root=./argo kind=code format=jsonl output=argo.jsonl # manifests .yaml /context create app app.jsonl --mode knowledge /context create infra infra.jsonl --mode knowledge /context create argo argo.jsonl --mode knowledge /context attach app && /context attach infra && /context attach argo ``` Com as três bases anexadas, o `@knowledge search` faz **fan-out sobre todas** (cada hit marcado pela base de origem), então o modelo **conecta as camadas**: *"o Rollout `checkout-api` não sobe — conecte o manifesto do Argo, o node group do Terraform e o health check no código do serviço"*. Você **não precisa** classificar o repo manualmente. O default é `docs` por segurança, mas o agente escolhe `kind=code` sozinho: pela intenção (o schema do tool descreve o uso), pela orientação do pipeline autônomo (abaixo), e por um **hint auto-corretivo** — rodar o default `docs` num repo sem Markdown devolve *"parece um repo de código, rode com `kind=code`"*, e ele se corrige no mesmo turno. ### Index card (o que entra no prompt) O attach injeta apenas um **TOC determinístico e budget-bounded** — nome, escala, origem e a lista de documentos — que vive no prefixo **cacheado** do prompt (estável byte a byte entre turnos). O modelo sabe *o que existe* sem pagar pelo conteúdo: ``` 📚 KNOWLEDGE BASE: minha-doc Origin: https://github.com/org/docs.git @ abc123def456 Scale: 87 document(s), 412 passage(s), ~1.5M tokens of source material (NOT in context) Table of contents: - guide/install.md (4 passages) — Install - guide/deploy.md (12 passages) — Deploying to production … ``` ### Retrieval híbrido (keyless-first) A cada turno, os trechos relevantes à pergunta são injetados num bloco **volátil** (fora do prefixo cacheado): * **BM25 puro-Go** — sempre disponível, **sem API key**, neutro pt/inglês. É o piso. O tokenizer quebra `snake_case`, `kebab-case` e `camelCase`/`PascalCase` em sub-palavras (mantendo o token inteiro), então um identificador como `getUserName` ou `aws_eks_cluster` é achado por `user`, `eks` etc. — recall sobre código sem perder match exato. * **Embeddings** ([Voyage/OpenAI/Bedrock](/pt/features/quality/rag-hyde), se configurados) — boost semântico, fundido por ranking normalizado (0.55/0.45). Falha de embedding **degrada para o léxico** com warn; nunca quebra o turno. *** ## Tool `@knowledge` — o agente investiga a base No **agent** e no **coder**, os index cards entram no system prompt e a tool `@knowledge` permite **investigação iterativa** — buscar, ler documentos inteiros em páginas, navegar a estrutura: | Subcomando | O que faz | | ----------------------------- | ---------------------------------------------------------------------------- | | `search {query, top_k?, kb?}` | Passagens ranqueadas (híbrido) com citação de `source` | | `get {source, offset?, kb?}` | Lê um documento inteiro, em páginas de \~3K tokens com offset de continuação | | `toc {prefix?, kb?}` | Lista os documentos da base (filtro por prefixo de path) | | `list` | Bases anexadas à sessão e suas escalas | O caso de uso que fecha o ciclo — **criar skills a partir da doc** com a tool [`@skill`](/pt/features/skill-authoring): ``` /agent cria uma skill de deploy baseada na seção de produção da doc → @knowledge search "deploy production" → @knowledge get "guide/deploy.md" → @skill create deploy-prod … ``` *** ## Pipeline autônomo — o agente constrói a base sozinho (`@context`) Os passos acima (achatar → criar → anexar) o **agente faz por você**. Quando ele topa com uma lacuna de conhecimento — uma lib, framework ou API que não domina — em vez de chutar ou parar para perguntar, ele monta a própria base: `@websearch` pela documentação oficial (de preferência o repo Markdown do projeto), ou usa um repo/URL/caminho que você indicou. `@docs-flatten` com `root=`, `repo=` ou `url=` → produz o corpus JSONL. Para um repo de código/infra, adiciona `kind=code` (uma base por camada: app, infra, gitops). `@context create … --mode knowledge` → `@context attach …`. `@knowledge search/get` para fundamentar a resposta nos trechos recuperados. A tool **`@context`** dá ao agente o mesmo poder de auto-serviço que ele já tem com [skills](/pt/features/skill-authoring), mas para conhecimento: | Subcomando | O que faz | | ---------------------------------------- | --------------------------------------------------------------------------------------------------- | | `create {name, paths[], mode?}` | Constrói uma base a partir de um corpus.jsonl, diretório ou arquivos (mode `knowledge` por default) | | `update {name, paths?, mode?, …}` | Re-ingere/modifica uma base existente | | `attach {name, rag?, priority?}` | Anexa à sessão; `rag` liga retrieval semântico top-K | | `detach {name}` | Remove o anexo da sessão (a base fica no disco) | | `list` / `status` | Lista todas as bases / mostra o que está anexado nesta sessão | | `show {name}` / `inspect {name, chunk?}` | Metadados de uma base / visão profunda (arquivos, chunks) | | `merge {name, sources[]}` | Combina bases numa nova (deduplicado) | | `export {name, path}` / `import {path}` | Salva/carrega uma base em arquivo portável | | `metrics` | Resumo do store: total de bases, anexadas, tamanho, por modo | | `delete {name}` | Remove a base do disco | A tool espelha **toda** a superfície do `/context`, então o agente lida com os contextos de ponta a ponta. As subcomandos de inspeção (`list`, `status`, `show`, `inspect`, `metrics`) são read-only. **Você continua no controle:** tudo que o agente anexa aparece no `/context attached` e no `@context status`; remova com `/context detach` ou simplesmente peça ("desanexa a doc do react"). O `attach` detecta embeddings automaticamente — knowledge mode usa BM25 keyless + vetores quando configurados, e reporta qual modo está ativo. No `/agent` o agente faz tudo isso sozinho; no `/coder`, as operações que mexem em estado passam pela confirmação de política. O modo **`url`** do `@docs-flatten` é o que fecha o ciclo para docs que **só existem como site HTML** (sem repo de Markdown): um crawl raso, mesmo-domínio, reaproveitando o motor de fetch do [`@webfetch`](/pt/features/web-tools) e emitindo o mesmo JSONL. Bounded por `maxPages`/`maxDepth` — sem truncamento silencioso. *** ## No chat também (exceção read-only) O chat continua [tool-less por design](/pt/features/interactive-ask) — mas a consulta à knowledge base é a **segunda exceção sancionada** (ao lado do `ask_user`), pela mesma razão: **não executa nada, só lê** o que você anexou. Anexe a base e converse normalmente; quando os trechos automáticos não bastam, o modelo puxa mais sozinho (até 4 pulls por turno: search → get → próxima página) antes de responder. ```bash theme={"system"} /config chat knowledge off # desliga a exceção (CHATCLI_CHAT_KNOWLEDGE=false) /config chat knowledge on # religa (default: on) ``` Funciona no caminho de tools **nativo** (API key) e no transporte **XML** (providers OAuth) — como todo o resto, agnóstico aos 14 providers. *** ## Referência rápida | Superfície | Valor | | ------------------------- | ------------------------------------------------------------------------------------------------------------------- | | Criar | `/context create --mode knowledge` | | Anexar / desanexar | `/context attach ` / `/context detach ` | | Agente faz sozinho | tool `@context` (`create`/`attach`/`detach`/`list`/`status`/`delete`) | | Fontes do `@docs-flatten` | `root=` · `repo=` · `url=` (crawl) | | Tipo do `@docs-flatten` | `kind=docs` (default, só Markdown) · `kind=code` (código/Terraform/YAML/shell, fatiado por estrutura) · `kind=auto` | | Custo por turno | index card (\~900 tokens, cacheado) + top-K volátil | | Toggle no chat | `/config chat knowledge on\|off\|toggle` (`CHATCLI_CHAT_KNOWLEDGE`, default `on`) | | Embeddings (opcional) | `CHATCLI_EMBED_PROVIDER=voyage\|openai\|bedrock` — sem provider, BM25 cobre tudo | | Limites | 100MB / 5.000 documentos por base; `get` paginado em \~12K chars | **Knowledge vs `--rag`:** o `/context attach --rag K` existente é vetor-puro (exige embedding provider) e só faz push por turno. O modo `knowledge` funciona **sem chave nenhuma**, dá ao modelo o índice do corpus e adiciona o lado pull (`@knowledge`) — para corpora de documentação ou de código/infra, prefira `--mode knowledge`. ## Próximos passos