Vault Graph

Status: Active public release

Vault Graph is a read-only, rebuildable knowledge access layer over Vault.

It helps humans and agents search Vault, trace decisions, inspect project memory, and build task-specific context packs without turning retrieval output into durable knowledge.

Vault remains the source of truth. Vault Graph reads, indexes, retrieves, and explains Vault-derived context. It does not publish wiki pages, mutate raw sources, edit Vault documents, or replace Vault's validation workflow.

Install

Prerequisites:

• Python 3.12+
• uv

Install from PyPI:

uv tool install vault-graph
vg --help

Development install from a source checkout:

git clone git@me.github.com:cutehackers/vault-graph.git
cd vault-graph
uv sync
uv run --python 3.12 vg --help

Optional local command install from a source checkout:

uv tool install -e .
vg --help

Quick Start

Run one setup command after installation:

vg setup --vault /path/to/llm-wiki --agent codex --mcp

By default, setup uses ~/.vault-graph for local state, registers the Vault, runs indexing, and registers the vault-graph stdio MCP server in the Codex config at $CODEX_HOME/config.toml or ~/.codex/config.toml. Existing Codex config is backed up before the vault-graph server entry is changed. Keep this state directory outside your Vault.

Then use the indexed Vault:

vg ask --state ~/.vault-graph "What changed recently?"
vg search --state ~/.vault-graph "GraphRAG"
vg context --state ~/.vault-graph "Implement GraphRAG MVP"
vg status --state ~/.vault-graph

Vault Graph builds local metadata, keyword, vector, and graph projections. It uses local storage and local embeddings by default; it does not require hosted services for normal use. The first indexing run may download the pinned local embedding model and cache it outside your Vault. Restart your agent after MCP registration so it can load the new server.

Common Commands

Commands that accept --vault-id operate on one registered Vault. Commands that accept --all-vaults expand to all enabled registered Vaults. Commands without either option use the active Vault.

Connect An Agent Through MCP

MCP server installation and MCP server registration are different things:

• installation makes the vg command available
• registration tells an agent how to start vg serve --mcp

For Codex, the easiest supported path is:

vg setup --vault /path/to/llm-wiki --agent codex --mcp

For explicit control, render or register the stdio server manually:

{
  "mcpServers": {
    "vault-graph": {
      "command": "vg",
      "args": [
        "serve",
        "--mcp",
        "--state",
        "/path/to/.vault-graph"
      ]
    }
  }
}

The current Codex-style example lives at docs/superpowers/specs/phase-5/codex-local-stdio-config.example.json.

Once connected, the agent can use these MCP tools:

• search_vault
• build_context_pack
• find_related
• get_decision_trace
• check_index_status
• explain_result
• summarize_project_memory
• get_open_questions
• get_recent_changes
• ask_vault

Vault Graph provides evidence-first working context and evidence-first answers through ask_vault and vg ask.

For explicit MCP control:

vg mcp register --agent codex --state ~/.vault-graph --config-path /path/to/agent-config.json
vg mcp register --agent codex --state ~/.vault-graph --config-path ~/.codex/config.toml
vg mcp config --agent codex --state ~/.vault-graph --print

Guarantees

Vault Graph user-facing features preserve these guarantees:

• read-only access to Vault
• local-first operation without mandatory hosted services
• evidence-first retrieval, context packs, and answers
• clear separation between stated facts and inferred links
• warnings for stale, missing, contested, or deprecated material
• reproducible indexes that can be deleted and rebuilt from Vault
• Vault-scoped identity for multiple registered Vault roots
• visible backend health and index freshness status
• durable knowledge publication only through Vault

More Documentation

• docs/FEATURES.md: user-facing feature catalog
• docs/SPEC.md: product specification and architecture
• docs/DESIGN.md: design goals and boundaries
• docs/PUBLISHING.md: PyPI release workflow and permissions
• docs/TODO.md: explicit deferred work and scale-up backlog

License

Vault Graph is distributed under the MIT License. See LICENSE.