Base de conocimiento

La base de conocimiento es lo que hace que las respuestas del agente se sientan fundamentadas — el LLM no tiene que adivinar a partir de la data de entrenamiento porque puede buscar en tus runbooks, tus postmortems pasados y los docs de tu equipo en cada turno.

Forma de almacenamiento

Un vector store, tres tipos de fuente.

Tipo de fuente	De dónde viene	¿Solo lectura?
vault	La colección integrada de playbooks ongridio/vault (96 docs markdown a 2026-05-29)	Sí
repo	URLs git que registras — HTTPS público o SSH vía identidad por-repo	No (edita settings + re-sync)
upload	Uploads directos (md / txt / pdf / docx) vía la página /knowledge de la SPA	No (editar / borrar fila)
manual	Pega markdown vía el editor inline	No

Los cuatro tipos comparten una colección Qdrant (ongrid_knowledge) y un modelo de embedding. Los hits de búsqueda devuelven el campo de payload source_type para que la UI renderice el badge correcto "from vault" / "from your repos".

ADR-028 — knowledge sources, tiered

Por qué una colección: la alternativa (una colección por tipo de fuente) obligaba al LLM a llamar N búsquedas por pregunta para tener cobertura, reventando el presupuesto de tool-call. Una colección + filtro source_type consigue el mismo aislamiento con una sola query.

El cliente Qdrant

Superficie estrecha, en 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)
}

Respaldada por internal/pkg/qdrantx en producción, fake-able en tests. Qdrant viene en el docker-compose; Qdrant externo se soporta vía ONGRID_QDRANT_URL.

El vault

El vault es un repositorio git público (sin auth) que distribuye playbooks de diagnóstico pre-curados. Temas cubiertos (a 2026-05-29):

• Red: recetas de debugging de DNS / TCP / TLS / HTTP.
• Kubernetes: mapas de síntoma-a-causa de pod / node / kubelet.
• Linux: rutas de investigación de proceso / memoria / disco / journald.
• Database: triage de slow-log MySQL, lag de replicación PostgreSQL.
• Diagnostics: 70+ playbooks indexados por síntoma.

ADR-029 añadió cloud sync: el manager jala el vault más reciente en un schedule (default 24h, configurable vía settings de la SPA) y re-embedea ante cambios. El checkout en disco vive bajo /var/lib/ongrid/repos/<vault_id>/; los puntos de qdrant están tagueados source=vault para que un Sync solo borre puntos del vault, nunca los tuyos.

No trates al vault como tu repo

El vault es una fuente integrada — nunca aparece en la página CRUD /knowledge/repos. El código usa isBuiltinVault() / is_builtin para gatear esto; no hagas substring-match de ongridio/vault (ver el feedback de recurring-pitfalls).

Tus propios repos

POST /v1/knowledge/repos con un body { url, name } registra un repositorio git. En el siguiente tick de sync el manager:

1. git clone --depth=1 (o git pull si el directorio ya existe) a /var/lib/ongrid/repos/<id>/.
2. Recorre el árbol por archivos .md / .txt / .rst / .yaml / .yml / .toml / .json.
3. Embedea cada archivo con el modelo de embedding configurado.
4. Reemplaza el conjunto de puntos para ese repo (source=repo, repo_id=<id>) atómicamente.

Auth SSH

Identidad por-repo, gestionada vía la tabla ssh_identities y la página /knowledge/identities de la SPA. La fila Repository NO lleva un campo provider — la tabla de identidad es la única fuente de creds de git (ADR-023).

GIT_SSH_COMMAND se setea por-sync para apuntar al archivo de key de la identidad, así cada clone de repo usa su propia key sin contaminar $HOME/.ssh/.

Auth HTTPS

Los repos HTTPS públicos clonan sin auth. La auth HTTPS privada está parqueada: la ruta original GitHub-PAT se eliminó cuando SSH cubrió los casos de uso realistas. Hasta que aterrice el RepoFetcher de ADR-018, usa SSH para privados.

Uploads

La página /knowledge/upload acepta:

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

Cada upload se convierte en una fila en knowledge_docs y un punto en qdrant con source=upload. La edición inline y el delete funcionan por-fila desde el árbol "Organization knowledge".

Búsqueda

El LLM obtiene un BaseTool query_knowledge — schema en query_knowledge_basetool.go. Args: query, filtro opcional source_type, top_k opcional. Devuelve: una lista de hits {score, source, title, snippet, url?}.

A la persona coordinator se le indica llamar a esto temprano para cualquier pregunta "cómo hago" / "por qué pasa X" / "cuál es el runbook para Y" — el costo de una búsqueda de conocimiento es mucho menor que una investigación de 5 tools que aterriza en la misma respuesta que el playbook ya tenía.

La UI de chat también expone un botón Quick Action "Search knowledge" para que los operadores peguen el mismo índice sin pasar por chat.

Ver también

• Skills — query_knowledge es uno de los 18 BaseTools bridged en el registry de skills.
• RCA — la persona investigator que llama a la búsqueda de conocimiento como tool de primer recurso.
• Arquitectura — dónde se sienta Qdrant en el stack L1.