Vault — memoria persistente para IA

El Vault es el corazón cognitivo de Korva. Corre en cada máquina de developer como un único binario Go (korva-vault) que expone simultáneamente:

1. Un servidor MCP sobre stdio (JSON-RPC 2.0) para que los agentes de IA lo invoquen.
2. Una API REST en localhost:7437 para la CLI, el dashboard Beacon y herramientas externas.
3. Una TUI opcional (korva-vault -mode tui) — una interfaz Bubbletea con tabs Dashboard / Explorer / Sessions.

Todo se persiste a una base de datos SQLite local (~/.korva/vault/observations.db) usando modernc.org/sqlite (Go puro, sin CGO, sin dependencias del sistema).

Modos de ejecución

korva-vault acepta un flag -mode (default: both):

Qué se guarda

La tabla principal es observations. Cada save aterriza ahí con una clave primaria ULID y un content_hash para deduplicación:

observations(
  id          TEXT PRIMARY KEY,        -- ULID
  session_id  TEXT,
  project     TEXT,
  team        TEXT,
  type        TEXT NOT NULL,           -- decision|pattern|bugfix|...
  title       TEXT NOT NULL,
  content     TEXT NOT NULL,
  tags        TEXT NOT NULL DEFAULT '[]',
  author      TEXT,
  created_at  TEXT NOT NULL DEFAULT (datetime('now')),
  content_hash TEXT NOT NULL           -- SHA256(title|content|project)[:32]
)

Una tabla virtual observations_fts (FTS5) indexa title, content y tags, mantenida en sync con triggers. La búsqueda del Vault corre contra este índice en milisegundos incluso sobre decenas de miles de filas.

Tipos de observación

Cada save declara un type — usado para filtrado y como pista para la IA:

decision, pattern, bugfix, learning, context, antipattern, task, feature, refactor, discovery.

Tres perfiles de permisos para MCP

El mismo Vault expone diferentes conjuntos de herramientas MCP según KORVA_MCP_PROFILE:

Lista completa en Referencia de herramientas MCP.

Filtro de privacidad en la frontera

Cada observación pasa por internal/privacy.Filter antes de cualquier INSERT SQL. Patrones built-in que redactan automáticamente:

• password, passwd, pwd, token, secret, api_key, private_key, client_secret, tokens de HashiCorp ROLE_ID / SECRET_ID
• Headers Authorization: Bearer <…>
• Cualquier cosa dentro de bloques <private>…</private> (case-insensitive, multilínea)

Puedes añadir patrones específicos del proyecto vía vault.private_patterns en korva.config.json.

Deduplicación

Re-guardar la misma observación en el mismo session_id se descarta silenciosamente — las colisiones de content_hash nunca duplican la fila. Esto previene loops donde un agente de IA re-emite el mismo output múltiples veces durante una tarea larga.

Estado SDD por proyecto

El Vault también trackea el estado de Spec-Driven Development por proyecto (tabla sdd_state) y las compuertas de calidad (quality_checkpoints). Las transiciones apply → verify y verify → archive están bloqueadas con compuertas: la IA no puede avanzar sin un vault_qa_checkpoint que pase. Ver Forge.

Dashboard Beacon embebido

El binario de release se construye con -tags embedui y contiene el dashboard React 19 Beacon completo. Visita http://localhost:7437 mientras el vault está corriendo para explorar observaciones, gestionar sesiones, editar scrolls y (con admin.key) administrar Teams, Audit Log y Skills Hub.

Defaults operativos

Estos PRAGMAs se aplican en cada conexión:

El modo WAL es esencial — permite que los lectores (queries de búsqueda) nunca bloqueen a los escritores (operaciones de save) y viceversa.

Variables de entorno

Siguiente

• Referencia de herramientas MCP
• Sentinel — el validador en tiempo de commit
• Self-hosting del Vault