Two paths: a guided /vdb-setup interview inside your agent, or the
manual steps below. Both are non-destructive and re-runnable.
The indexer and MCP server are stdlib-heavy. uv recommended; pip works.
Obsidian, Logseq, Foam, or any folder of .md files with YAML frontmatter.
Claude Code, OpenCode, Cursor, or Antigravity. Skills auto-install to each.
Only running the indexer + MCP server? You need just pip install pyyaml.
Everything else (TUI, validation, browser) is an optional extra.
This installs the vdb command onto your PATH.
$ git clone https://github.com/btilford/vault-db-template.git
$ cd vault-db-template
$ mise run setup # uv sync — pyyaml, textual, jsonschema, websocket-client
bootstrap.sh detects Claude Code, OpenCode, Pi, Antigravity, and Gemini, then
installs every skill into a shared hub with per-agent symlinks.
$ ./bootstrap.sh --dry-run # preview $ ./bootstrap.sh # full install $ ./bootstrap.sh --check # installed vs outdated
The Textual TUI collects your vault root + which table groups to enable, and writes
vdb-config.yaml. Full configurator docs →
$ vdb tui # pick packs, set vault path $ vdb config apply --yes # bake paths into the engine copies (optional)
Preferred: let installed vdb resolve the vault at runtime
(--vault > --context > $VDB_VAULT > walk-up to
vdb-config.yaml > registry). Backwards-compat: vdb config apply
writes the path constants into the deployed engine copies for systemd.
Embeddings are heavy and optional — default to --no-embed unless semantic
search is the point.
$ vdb index --full --no-embed # full rebuild, fast $ vdb index --incremental --no-embed # only changed files $ vdb status # resolved vault + why $ sqlite3 vault-index.db ".tables" # inspect
Point your harness at vdb serve (or the standalone server). Stamp an agent name
so multi-agent telemetry is distinguishable.
{
"mcpServers": {
"vault": {
"command": "vdb",
"args": ["serve"],
"env": { "VAULT_AGENT": "claude-code" }
}
}
}
Smoke-test it directly with one JSON-RPC line:
$ echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"vault_status","arguments":{}}}' \
| vdb serve
Generates content matching your config, prints verification commands, cleans up after.
$ vdb fixtures --list # preview $ vdb fixtures # create + verification commands $ vdb fixtures --clean # remove when done
/vdb-setupThe wizard interviews you about your vault, use cases, and agent ecosystem; detects
available models per harness; backs up the existing vault; then generates and implements a
tailored plan. Nothing is written until you approve. Re-runnable — it reads
vault-setup.json and resumes.
Ship the indexer on a systemd timer (Linux) or launchd (macOS) so the DB tracks your vault.
See systemd/ and docs/setup-guide.md for unit files and the macOS
alternative.