Vault — persistent AI memory

The Vault is the cognitive heart of Korva. It runs on every developer machine as a single Go binary (korva-vault) that simultaneously exposes:

1. An MCP server over stdio (JSON-RPC 2.0) for AI agents to call.
2. A REST API on localhost:7437 for the CLI, the Beacon dashboard and external tooling.
3. An optional TUI (korva-vault -mode tui) — a Bubbletea interface with Dashboard / Explorer / Sessions tabs.

Everything is persisted to a local SQLite database (~/.korva/vault/observations.db) using modernc.org/sqlite (pure Go, no CGO, no system dependencies).

Run modes

korva-vault accepts a -mode flag (default: both):

What gets stored

The core table is observations. Every save lands there with an ULID primary key and a content_hash for deduplication:

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]
)

A virtual observations_fts table (FTS5) indexes title, content and tags, kept in sync with triggers. Vault search runs against this index in milliseconds even on tens of thousands of rows.

Observation types

Every save declares a type — used for filtering and as a hint to the AI:

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

Three permission profiles for MCP

The same Vault exposes different sets of MCP tools depending on the KORVA_MCP_PROFILE:

See the full list at MCP tools reference.

Privacy filter at the boundary

Every observation passes through internal/privacy.Filter before any SQL INSERT. Built-in patterns redact:

• password, passwd, pwd, token, secret, api_key, private_key, client_secret, HashiCorp ROLE_ID / SECRET_ID tokens
• Authorization: Bearer <…> headers
• Anything inside <private>…</private> blocks (case-insensitive, multi-line)

You can add project-specific patterns via vault.private_patterns in korva.config.json.

Deduplication

Re-saving the same observation in the same session_id is silently dropped — content_hash collisions never duplicate the row. This prevents loops where an AI agent re-emits the same output multiple times during a long task.

SDD state per project

The Vault also tracks Spec-Driven Development state per project (sdd_state table) and quality gates (quality_checkpoints). The transitions apply → verify and verify → archive are gated: the AI cannot advance without a passing vault_qa_checkpoint. See Forge.

Embedded Beacon dashboard

The release binary is built with -tags embedui and contains the full React 19 Beacon dashboard. Visit http://localhost:7437 while the vault is running to browse observations, manage sessions, edit scrolls and (with admin.key) administer Teams, Audit Log and Skills Hub.

Operational defaults

These PRAGMAs are applied on connection:

WAL mode is essential — it allows readers (search queries) to never block writers (save operations) and vice-versa.

Environment variables

Next

• MCP tools reference
• Sentinel — the commit-time validator
• Self-hosting the Vault