vaultspec-rag 0.3.4

GPU-accelerated semantic search for your docs and source code: hybrid dense + sparse RAG on a local Qdrant backend, served to Claude Code and other MCP clients.

vaultspec-rag

Semantic search for vault records, source code, and extracted documents.

Get started · Product · Documentation · Family · Support

A vaultspec-core project accumulates a durable record of decisions, plans, research, and the code they produced. vaultspec-rag searches that record, conventional source code, and explicitly routed extracted documents by meaning, not by keyword.

Search "file lock concurrent write per-root" and vaultspec-rag surfaces the decision that governs it, even when the document never uses those exact words. It is the retrieval layer of the project: it finds and ranks the grounding, and a client such as a coding agent reads it.

The terminal renders on this page are real output from this repository's vault and code searches and its service diagnostics. The same runtime exposes independent document search for explicitly routed extractor output. The architecture overview explains how it works; the glossary defines the terms used across the docs.

Getting started

vaultspec-rag needs an NVIDIA GPU with CUDA support (about 3 GB free) and Python 3.13+ on Linux or Windows; macOS, AMD GPUs, and Apple Silicon are not supported. See the architecture overview for why the hardware floor sits where it does.

Install

Try it now with no project setup, straight from PyPI:

uvx vaultspec-rag install

Runs install in an ephemeral uv tool environment: it enrolls the current directory as a workspace, provisions the GPU PyTorch build, downloads the search models, and fetches the pinned Qdrant server binary, asking once before touching any config. Good for a first try. A bare uvx run does not pin the GPU torch build across invocations the way the project-dependency and standalone-tool paths do, so switch to one of those once you're keeping vaultspec-rag around.

Add vaultspec-rag to your project and set it up:

uv add vaultspec-rag
uv run vaultspec-rag install
uv sync

install configures the GPU PyTorch build, downloads the search models, and provisions the managed search server. uv sync then pulls in that GPU build. The models total a few gigabytes, so the first download takes several minutes, but it runs only once.

To install as a standalone tool instead, pin the GPU torch wheel in the tool receipt so uv tool upgrade keeps the CUDA build. A bare uv tool install re-resolves torch to a CPU-only wheel on every upgrade, and --index is not recorded in tool receipts, so the --with pin is the durable fix:

uv tool install "vaultspec-rag[mcp]" --with "torch @ https://download.pytorch.org/whl/cu130/torch-2.13.0%2Bcu130-cp313-cp313-win_amd64.whl"
uvx vaultspec-rag install

On Linux, use the matching manylinux_2_28_x86_64 wheel from the same index.

See the installation guide for tool-environment repair and upgrade caveats.

Index and search

1. Start the server:

   uv run vaultspec-rag server start
   

2. Index your project:

   uv run vaultspec-rag index
   

3. Search:

   uv run vaultspec-rag search "concept plus the domain terms"
   

The first run builds the index. After that, the running service watches your files and reindexes changes automatically, so the index stays current without another command. Check readiness at any time with server doctor:

See the getting started guide for the full walkthrough.

Capabilities

Capability	What it gives you
Hybrid search	Dense (semantic) and sparse (keyword) matching, cross-encoder reranked
Independent search	Search vault, code, or extracted document content, or combine all three
Managed or local backend	A supervised Qdrant server for throughput, or --local-only for a zero-server setup
MCP integration	Search, reindex, clean, and inspect vault, code, and document domains
Live reindexing	The running service watches your files and reindexes changes automatically
Preprocessing hooks	Route project-defined extractor output explicitly to code or document indexing

See search and index for the full filter set, MCP integration for client setup, and preprocessing hooks for the extraction rule syntax and its trust model.

The vaultspec family

• vaultspec-core - Beta - The agent harness: the pipeline, the vault, and the CLI that drives them.
• vaultspec-rag - Beta - Semantic search across vault, code, and document domains.
• vaultspec-dashboard - Beta - The application that runs it all as a UI.
• vaultspec-a2a - Beta - Headless agent-to-agent orchestration.

Documentation

Getting started guide

• Getting started - install, index, and run your first query end to end.
• Installation - the GPU build, dependency provisioning, and recovery steps.

Daily use

• Search and index - run searches and refresh the index.
• Service mode - keep models warm in a background service for faster queries.
• Backends - the managed Qdrant server versus local-only mode.
• MCP integration - wire search into Claude Code and other MCP clients.
• Automation - JSON output and scripting.
• Preprocessing hooks - connect project-defined extractors for PDFs, spreadsheets, and other formats.

Reference

• CLI reference - every command and flag.
• Configuration - settings, environment variables, and defaults.
• Service discovery - the service.json contract for integrators.
• Glossary - terms used across the docs.

Concepts

• Architecture - how it works, why a GPU is required, and the server and local-only modes.
• Indexing - indexing and retrieval internals.

Status, help, and license

vaultspec-rag is Beta. File bugs and ask questions on the GitHub issue tracker.

A good bug report carries five things: your vaultspec-rag version, your operating system, your GPU model, the exact command you ran, and the full stderr output. With those, a maintainer can reproduce the fault. Without them, the report is hard to act on.

The changelog holds release notes and version history. vaultspec-rag is released under the MIT License.