vaultspec-rag 0.2.18

GPU-accelerated RAG module for vaultspec vault search

vaultspec-rag - semantic search for a vaultspec-core workspace

vaultspec-rag is the semantic search companion to vaultspec-core, and the RAG in the name stands for retrieval-augmented generation - the pattern of pulling relevant snippets out of your own files so an agent can answer with grounded context. It indexes the markdown documents in your vault and the source code that sits beside them, then lets you search them by meaning rather than by exact keyword match. A query for "how do we handle file locks during indexing" finds a decision record that discusses concurrent writes and per-root locks, even though it never uses the word "indexing."

Requirements

• Python 3.13 or newer
• uv as the package manager
• An NVIDIA GPU with CUDA support
• About 3 GB of free GPU memory
• Linux or Windows

macOS, AMD GPUs, and Apple Silicon are not supported. For the reasoning behind the hardware floor, see the architecture overview.

Quickstart

uv add vaultspec-rag
uv run vaultspec-rag install
uv run vaultspec-rag index
uv run vaultspec-rag search "your question here"

The install step prepares the GPU build inside your project, index reads your vault and code into a local search index, and search returns ranked results for the query you pass. The first run is slower than later runs because of one-time model downloads. For a guided walkthrough against a real query, follow the getting started guide.

What's a vault?

A vault is a .vault/ directory of markdown files - research notes, architecture decision records, plans, and execution logs - that vaultspec-core creates and manages. If you don't have one yet, set one up there first.

vaultspec-rag adds exactly one capability on top of that: semantic search over the vault and the source code beside it. Vault creation, document templates, frontmatter validation, and the spec-driven workflow all stay in vaultspec-core.

Both packages live side by side in the same project. You can use vaultspec-core on its own without ever installing vaultspec-rag. vaultspec-rag without vaultspec-core has nothing to search.

Documentation

Getting started

• Getting started - install, index, and run your first query end to end.
• Installation - GPU build details, supported platforms, and recovery steps.

Daily use

• Search and index - run searches, refresh the index, and scope queries.
• Service mode - keep models warm in a background service for faster queries.
• MCP integration - expose search to Claude Code and other MCP clients.
• Automation - reindex on file changes and wire searches into scripts.

Reference

• CLI reference - every command, subcommand, and flag.
• Configuration - settings, environment variables, and defaults.
• Glossary - terms used across the docs and the codebase.

Concepts

• Architecture - how the index is built, why the GPU is required, and how the pieces fit together.

Support and help

File bugs and ask questions on the GitHub issue tracker.

A useful bug report includes your vaultspec-rag version, your operating system, your GPU model, the exact command you ran, and the full stderr output.

What changed

See the changelog for release notes and version history.

License

vaultspec-rag is released under the MIT License. See LICENSE for the full text.