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.
  • União, fundida por ranking — o top-k do próprio índice vetorial (sobre todas as passagens já embutidas) se junta ao pool do BM25, e a união é fundida por reciprocal rank fusion (rankings são comparáveis entre corpora, então um corpus de um único hit não pontua mais 1.0 por construção); uma passagem que diz a mesma coisa com outras palavras aparece mesmo quando o BM25 tem outros resultados. A query é embutida uma vez por turno e reaproveitada em todos os corpora anexados; o reranker via LLM manda a instrução uma vez como system message e contabiliza o uso como gasto de fundo.
  • Piso BM25 — hits léxicos abaixo de 5% do score do melhor hit saem do pool de candidatos, então uma pergunta que mal casa com o corpus devolve uma lista curta e honesta em vez de k passagens de ruído.
  • Estágio de rerank opcional (CHATCLI_KNOWLEDGE_RERANK, padrão off) — reordena a cabeça do pool fundido (até 24 passagens) antes do corte. mmr é keyless: relevância marginal máxima sobre sobreposição de tokens, então as passagens devolvidas cobrem partes diferentes do corpus em vez de quase-duplicatas do melhor hit. llm pede ao modelo de compactação (CHATCLI_COMPACT_MODEL, senão o cliente da sessão) uma ordem listwise, limitada por timeout de 8 s; qualquer falha mantém a ordem fundida.
  • Pesos por corpus — /context attach <nome> --weight 1.5 escala os scores daquela base quando hits de várias bases anexadas são mesclados (1.0 é neutro). O peso é persistido com os anexos da sessão.
  • Folding de acentos e stemming leve (opt-in) — CHATCLI_KNOWLEDGE_NORMALIZE=fold faz configuração e configuracao serem o mesmo termo; stem também dobra terminações comuns pt/en (configurações → configuracao, deploys → deploy, queries → query, rapidamente → rapida) sem tocar em identificadores curtos como s3 ou oauth2. O padrão off mantém o ranking byte-exato; mudar o modo reindexa o corpus (o modo faz parte do fingerprint do índice), e as buscas no transcript usam o mesmo tokenizer.
  • Embeddings locais e keyless — CHATCLI_EMBED_PROVIDER=ollama usa um servidor Ollama local (OLLAMA_HOST, padrão http://localhost:11434; modelo CHATCLI_EMBED_MODEL, padrão nomic-embed-text, dimensão aprendida no primeiro uso) para o boost semântico sem API key e sem custo.
  • Aquecimento, não latência na primeira pergunta — anexar uma base de conhecimento (ou --rag) e todo refresh que mudou algo embutem as passagens faltantes em background, em lotes, então a primeira pergunta depois disso não paga o embedding do corpus no turno. Ids de passagem são hashes de conteúdo: um refresh embute só o que mudou. O índice vetorial é escrito com rename atômico e fsync. Retrieval e aquecimento compartilham um único loop limitado (64 passagens por requisição ao provedor) atrás de um single-flight por contexto, então uma pergunta que chega durante o aquecimento espera por ele em vez de embutir os mesmos ids duas vezes. Um lote que o provedor rejeita é pulado e o resto ainda entra; o cache vetorial guarda cada lote que voltou antes de uma falha. Conteúdo binário (bytes NUL, UTF-8 inválido) e bundles minificados nunca chegam ao embedder, uma linha longa demais é cortada sem partir runa num teto fixo, e passagens truncadas mantêm a faixa de linhas da citação verdadeira.
  • Um budget por turno — as passagens recuperadas de todas as bases anexadas compartilham um budget (~24 K caracteres, em ordem de prioridade); passagens já emitidas por uma base de maior prioridade (mesmo id, ou o mesmo conteúdo no mesmo lugar) são descartadas, e a última base recebe o que sobra em vez de nada.
  • Citações estruturadas — todo cabeçalho de passagem termina com cite as [caminho:início-fim] e o bloco pede ao modelo que referencie passagens assim, então uma resposta pode ser rastreada até as linhas exatas.
  • Custo de embedding visível — toda chamada de embedding é medida (tokens estimados por caracteres na tarifa de lista do provedor) e aparece no /cost como Embeddings: N chamada(s) · ~T tokens · $x; Ollama mede a $0.
  • Passagens conscientes de estrutura — contextos criados a partir de agora cortam passagens em headings, linhas em branco e declarações (func, def, class, …) na parte final da janela, e a linha de fronteira abre a próxima passagem. Contextos existentes mantêm suas passagens de janela fixa e seus vetores; nada é re-embutido pelas suas costas.

​
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