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 resolve com o mesmo padrão pull-first da memória persistente: 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.
# 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=<dir> (pasta local), repo=<git-url> (clone raso) e url=<site> (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. |
| 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 |
vendor/, node_modules/, .terraform/, lockfiles, minificados, binários) e arquivos acima de 1 MiB são ignorados.
# 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
@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, 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.
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 |
@skill:
/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:
Descobre a fonte
@websearch pela documentação oficial (de preferência o repo Markdown do projeto), ou usa um repo/URL/caminho que você indicou.
Achata
@docs-flatten com root=<dir>, repo=<git> ou url=<site> → produz o corpus JSONL. Para um repo de código/infra, adiciona kind=code (uma base por camada: app, infra, gitops).
Cria e anexa
@context create … --mode knowledge → @context attach ….
Consulta
@knowledge search/get para fundamentar a resposta nos trechos recuperados.
@context dá ao agente o mesmo poder de auto-serviço que ele já tem com skills, 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 |
/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 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 — 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.
/config chat knowledge off # desliga a exceção (CHATCLI_CHAT_KNOWLEDGE=false)
/config chat knowledge on # religa (default: on)
Referência rápida
| Superfície | Valor |
|---|
| Criar | /context create <nome> <corpus.jsonl|dir> --mode knowledge |
| Anexar / desanexar | /context attach <nome> / /context detach <nome> |
| Agente faz sozinho | tool @context (create/attach/detach/list/status/delete) |
Fontes do @docs-flatten | root=<dir> · repo=<git> · url=<site> (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
