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

Keep Vault Graph state outside your Vault:

vg init --vault /path/to/llm-wiki --state ~/.vault-graph
vg index --state ~/.vault-graph
vg status --state ~/.vault-graph
vg search --state ~/.vault-graph "GraphRAG"
vg context --state ~/.vault-graph "Implement GraphRAG MVP"

The first index builds local metadata, keyword, vector, and graph projections. Vault Graph uses local storage and local embeddings by default; it does not require hosted services for normal use.

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

After indexing your Vault, register this stdio server in the agent's MCP config:

{
  "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.

Recommended Easy Setup

The accepted onboarding target is a one-command setup flow:

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

This command:

• uses ~/.vault-graph as the default state path when --state is omitted
• registers the Vault path
• runs indexing
• prepares MCP registration for the selected agent
• prints the MCP server command or writes it only to an explicit agent config path

The lower-level MCP commands should remain available for explicit control:

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

These commands are implemented product features. Their implementation design lives at docs/superpowers/specs/2026-06-24-cli-todo-command-implementation-design.md:

vg setup --vault /path/to/llm-wiki --agent codex
vg mcp register --agent codex --state ~/.vault-graph --config-path /path/to/agent-config.json
vg mcp config --agent codex --state ~/.vault-graph --print
vg watch
vg ask "question"
vg serve --http

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.