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).
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.
- 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.
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) |
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 |
delete {name} | Remove a base do disco |
/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) |
| 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, prefira --mode knowledge.
Próximos passos
