Skip to main content
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.

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

Knowledge bases também são nós no grafo de conhecimento (kind kbcontext, ligadas pelas suas tags): @memory map as conta, @memory neighbors consegue navegar até elas, e elas viajam no cache persistido do grafo. Veja Bootstrap e Memória › Grafo de conhecimento.
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:

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

​
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: O caso de uso que fecha o ciclo — criar skills a partir da doc com a tool @skill:

​
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:
1

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

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).
3

Cria e anexa

@context create … --mode knowledge → @context attach ….
4

Consulta

@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, mas para conhecimento: 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 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.
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

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

Contextos Persistentes

RAG + HyDE

Criação de Skills

Bootstrap e Memória