Base de conhecimento

A base de conhecimento é o que faz as respostas do agent parecerem fundamentadas — o LLM não precisa adivinhar a partir do treinamento porque consegue buscar seus runbooks, seus postmortems passados, e a documentação da equipe em cada turn.

Formato de armazenamento

Um único vector store, três tipos de fonte.

Tipo de fonte	De onde vem	Read-only?
vault	A coleção embutida de playbooks ongridio/vault (96 documentos markdown em 2026-05-29)	Sim
repo	URLs git que você registra — HTTPS público ou SSH via identidade por repo	Não (editar settings + re-sync)
upload	Uploads diretos (md / txt / pdf / docx) via a página /knowledge do SPA	Não (editar / deletar linha)
manual	Colar markdown via o editor inline	Não

Os quatro tipos compartilham uma coleção Qdrant (ongrid_knowledge) e um modelo de embedding. Hits de busca retornam o campo de payload source_type para que a UI renderize o badge "do vault" / "dos seus repos" correto.

ADR-028 — fontes de conhecimento, em camadas

Por que uma única coleção: a alternativa (uma coleção por tipo de fonte) forçava o LLM a chamar N buscas por pergunta para conseguir cobertura, estourando o budget de tool-call. Uma única coleção + filtro source_type consegue o mesmo isolamento com uma só query.

O client Qdrant

Superfície estreita, em internal/manager/biz/knowledge/usecase.go:62:

type QdrantClient interface {
    EnsureCollection(ctx context.Context, name string, dim int) error
    EnsurePayloadIndex(ctx context.Context, collection, field, schema string) error
    Upsert(ctx context.Context, collection string, points []qdrantx.Point) error
    DeleteByFilter(ctx context.Context, collection string, mustMatch map[string]any) error
    DeleteByID(ctx context.Context, collection string, id uint64) error
    GetPoints(ctx context.Context, collection string, ids []uint64) ([]qdrantx.SearchHit, error)
    Search(ctx context.Context, collection string, vector []float32, opts qdrantx.SearchOpts) ([]qdrantx.SearchHit, error)
    Scroll(ctx context.Context, collection string, opts qdrantx.ScrollOpts) (*qdrantx.ScrollResult, error)
}

Implementado por internal/pkg/qdrantx em produção, fake-ável em testes. Qdrant vem no docker-compose; Qdrant externo é suportado via ONGRID_QDRANT_URL.

O vault

O vault é um repositório git público (sem auth) que distribui playbooks de diagnóstico pré-curados. Tópicos cobertos (em 2026-05-29):

• Rede: receitas de debugging de DNS / TCP / TLS / HTTP.
• Kubernetes: mapas de sintoma-para-causa de pod / node / kubelet.
• Linux: caminhos de investigação de processo / memória / disco / journald.
• Banco de dados: triagem de slow-log MySQL, lag de replicação PostgreSQL.
• Diagnósticos: 70+ playbooks indexados por sintoma.

ADR-029 adicionou sync com a nuvem: o manager puxa o vault mais recente em um schedule (padrão 24h, configurável via settings do SPA) e re-embeda em mudanças. O checkout em disco vive sob /var/lib/ongrid/repos/<vault_id>/; os pontos qdrant são marcados com source=vault para que um Sync apenas delete pontos do vault, nunca os seus.

Não trate o vault como seu repo

O vault é uma fonte built-in — ele nunca aparece na página CRUD /knowledge/repos. O código usa isBuiltinVault() / is_builtin para gatear isso; não faça substring-match em ongridio/vault (veja o feedback de recurring-pitfalls).

Seus próprios repos

POST /v1/knowledge/repos com body { url, name } registra um repositório git. No próximo tick de sync o manager:

1. git clone --depth=1 (ou git pull se o diretório já existe) para /var/lib/ongrid/repos/<id>/.
2. Percorre a árvore em busca de arquivos .md / .txt / .rst / .yaml / .yml / .toml / .json.
3. Embeda cada arquivo com o modelo de embedding configurado.
4. Substitui o conjunto de pontos desse repo (source=repo, repo_id=<id>) atomicamente.

SSH auth

Identidade por repo, gerenciada via a tabela ssh_identities e a página /knowledge/identities do SPA. A linha Repository NÃO carrega um campo provider — a tabela de identity é a única fonte de credenciais git (ADR-023).

GIT_SSH_COMMAND é setado por sync apontando para o arquivo da chave da identidade, então cada clone de repo usa sua própria chave sem poluir $HOME/.ssh/.

HTTPS auth

Repos HTTPS públicos clonam sem auth. Auth HTTPS privado está parqueado: o caminho original via PAT do GitHub foi removido quando o SSH passou a cobrir os casos de uso realistas. Até o RepoFetcher do ADR-018 aterrissar, use SSH para privado.

Uploads

A página /knowledge/upload aceita:

Formato	Extractor
.md, .txt	Leitura crua + chunk
.pdf	docextract (internal/pkg/docextract)
.docx	docextract

Cada upload vira uma linha em knowledge_docs e um ponto no qdrant com source=upload. Edit e delete inline funcionam por linha pela árvore "Organization knowledge".

Busca

O LLM ganha um BaseTool query_knowledge — schema em query_knowledge_basetool.go. Args: query, filtro opcional source_type, opcional top_k. Retorna: lista de hits {score, source, title, snippet, url?}.

A persona coordinator é instruída a chamar isto cedo para toda pergunta tipo "como faço" / "por que X acontece" / "qual o runbook para Y" — o custo de uma busca de conhecimento é muito menor que uma investigação de 5 ferramentas que cai na mesma resposta que o playbook já tinha.

A UI de chat também expõe um botão Quick Action "Search knowledge" de modo que operadores possam atingir o mesmo índice sem passar pelo chat.

Veja também

• Skills — query_knowledge é um dos 18 BaseTools com ponte exposta no skill registry.
• RCA — a persona investigator que chama busca de conhecimento como ferramenta de primeira opção.
• Arquitetura — onde o Qdrant se encaixa na stack L1.