Metadata-Version: 2.4
Name: vault-graph
Version: 0.1.3
Summary: Read-only, rebuildable knowledge access layer over Vault.
Project-URL: Homepage, https://github.com/cutehackers/vault-graph
Project-URL: Repository, https://github.com/cutehackers/vault-graph
Project-URL: Issues, https://github.com/cutehackers/vault-graph/issues
Author: Jun Hyoung Lee
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Text Processing :: Indexing
Requires-Python: >=3.12
Requires-Dist: chromadb<2.0,>=1.5.9
Requires-Dist: fastapi<1,>=0.115
Requires-Dist: fastembed<1.0,>=0.8.0
Requires-Dist: huggingface-hub<1.0,>=0.31
Requires-Dist: mcp<2,>=1.27
Requires-Dist: pyyaml>=6.0.2
Requires-Dist: rustworkx<1.0,>=0.17
Requires-Dist: typer>=0.12.5
Requires-Dist: uvicorn<1,>=0.30
Description-Content-Type: text/markdown

# 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`](https://docs.astral.sh/uv/)

Install from PyPI:

```bash
uv tool install vault-graph
vg --help
```

Development install from a source checkout:

```bash
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:

```bash
uv tool install -e .
vg --help
```

## Quick Start

Run one setup command after installation:

```bash
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:

```bash
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

| Goal | Command |
| --- | --- |
| Register a Vault | `vg init --vault /path/to/llm-wiki --state ~/.vault-graph` |
| Add another Vault | `vg vault add work --path /path/to/other-vault --state ~/.vault-graph` |
| List Vaults | `vg vault list --state ~/.vault-graph` |
| Index the active Vault | `vg index --state ~/.vault-graph` |
| Index one Vault | `vg index --vault-id work --state ~/.vault-graph` |
| Index all Vaults | `vg index --all-vaults --state ~/.vault-graph` |
| Check health | `vg status --state ~/.vault-graph` |
| Search evidence | `vg search --state ~/.vault-graph "query"` |
| Include graph signals | `vg search --include-graph --state ~/.vault-graph "query"` |
| Ask with evidence | `vg ask --state ~/.vault-graph "question"` |
| Build a context pack | `vg context --state ~/.vault-graph "goal"` |
| Find related items | `vg related --state ~/.vault-graph GraphRAG` |
| Trace a decision | `vg decision-trace --state ~/.vault-graph GraphRAG` |

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:

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

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

```json
{
  "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`](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:

```bash
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`](docs/FEATURES.md): user-facing feature catalog
- [`docs/SPEC.md`](docs/SPEC.md): product specification and architecture
- [`docs/DESIGN.md`](docs/DESIGN.md): design goals and boundaries
- [`docs/PUBLISHING.md`](docs/PUBLISHING.md): PyPI release workflow and permissions
- [`docs/TODO.md`](docs/TODO.md): explicit deferred work and scale-up backlog

## License

Vault Graph is distributed under the MIT License. See [`LICENSE`](LICENSE).
