vaultspec-rag

The semantic search component for vault and code.

Grep finds a concept only when you already know its name. Why code looks the way it does is often written in a decision record that's hard to find. vaultspec-rag searches a repository's source code and its decision records by meaning. Run it from the command line, or connect an AI assistant through the Model Context Protocol (MCP), so the assistant finds both the code and the decisions behind it. Search combines a model that matches meaning with one that matches exact terms, then reranks the results. An optional paid service, Typesafe, can refine the ranking.

One background service per machine runs the models on the local graphics processing unit (GPU), because they're too slow to be useful on a central processing unit (CPU). A host installation starts that service; a client installation only sends it requests. The architecture overview explains how the pieces fit.

Install · Use it · Docs · Help

Use it with vaultspec-core or independently in another repository. To index PDFs and other formats, connect a converter.

What you need

• Python 3.13 or 3.14 with uv, or a prebuilt binary.
• A supported GPU: an NVIDIA GPU with CUDA, NVIDIA's GPU computing platform, on Linux or Windows, or Apple silicon on macOS. vaultspec-rag doesn't run on a CPU or on AMD GPUs.
• Enough memory for a resource profile. The default profile needs 16 GiB of system memory and, on CUDA, 12 GiB of free GPU memory. The smaller embedded-local profile needs 8 GiB of system memory and 6 GiB of free GPU memory.
• Several gigabytes of disk for a one-time model download.
• By default, search also uses the sparse model naver/splade-v3, which matches exact terms. It needs a Hugging Face account that has accepted the model's non-commercial licence. The dense-only setup uses only the meaning model. It needs no Hugging Face login and gives up exact-term matching.

The installation requirements list the full figures, and the glossary defines the terms used here.

Install

• If vaultspec-rag isn't installed on this machine yet, install the host. It serves every repository on the machine and gives AI assistants the search tools.
• If a host installation already runs the service, add a client to any uv-managed Python project that must list vaultspec-rag as a dependency. A client installs no GPU packages or models and sends every request to the host's service on the same machine.

The installation guide covers every route, and its troubleshooting, upgrade, and removal sections cover what comes after.

Host installation

Install the host once, as a standalone tool; it serves every repository on the machine. The [gpu] extra adds PyTorch and the model libraries, and [mcp] adds the MCP adapter that AI assistants launch. The Windows and Linux commands record the CUDA package index in the tool's installation receipt, so uv tool upgrade keeps resolving the GPU build.

Windows x64 and Linux x86_64 or aarch64 (glibc 2.28 or newer):

uv tool install --python 3.13 "vaultspec-rag[gpu,mcp]" --index https://download.pytorch.org/whl/cu130 --index-strategy unsafe-first-match

Apple silicon macOS, which uses Metal rather than CUDA:

uv tool install --python 3.13 "vaultspec-rag[gpu,mcp]"

Upgrade later with uv tool upgrade vaultspec-rag, then restart the service so it runs the new release; if uv reports an entry point it could not overwrite because the file is in use, the release is installed and the running launcher keeps working. An installation made without the two index options resolves a CPU-only PyTorch at its next upgrade; vaultspec-rag server doctor reports that and prints the two commands that repair it in place, which pin the GPU build describes. If uv reports that its executables directory isn't on your PATH, run uv tool update-shell and open a new terminal.

By default, search needs access to the sparse model. If you can't accept its licence, set VAULTSPEC_RAG_SPARSE_ENABLED=0 in your user environment and skip to the repository setup. Otherwise, accept the licence on the model page, then log in:

uvx --from huggingface_hub hf auth login

Alternatively, set HF_TOKEN in your user environment.

From the root of each repository you want to search, run the repository setup. It doesn't reinstall the tool:

vaultspec-rag install --no-torch-config

The setup adds the AI-assistant integration and creates the .vault/ folder for decision records. On the first repository, it also downloads the search models and Qdrant, the index server; later repositories reuse both. The first run downloads several gigabytes. --no-torch-config leaves the repository's own PyTorch configuration alone, because the tool already carries its PyTorch.

Start the service. It loads the models and waits until it's ready:

vaultspec-rag server start

The service doesn't start by itself after a reboot, so run vaultspec-rag server start again then. To stop it, run vaultspec-rag server stop.

Check the installation:

vaultspec-rag server doctor

Check that the report detects your GPU and finds every configured model and the Qdrant binary. If it reports a problem, use the installation troubleshooting guide.

Client in a Python project

A client lets a project's own AI-assistant configuration launch the search tools from the project environment, so collaborators get them with uv sync. Each collaborator still needs their own host installation at the release the project pins.

1. In the host installation, run this command and note the release on the Service release: line:

   vaultspec-rag server status --verbose
   

2. From the project root, add the client pinned to that release:

   uv add --dev "vaultspec-rag[mcp]==<release>"
   

3. Set up the project. --mode dev makes the AI assistant launch the search tools from the project environment, even if the host installation set up the project first. A client skips PyTorch configuration and all downloads.

   uv run vaultspec-rag install --mode dev
   

4. Confirm the client reaches the service. uv run vaultspec-rag server doctor must show release: <release> (matches this client) and report PyTorch as not needed for this client installation. If the release doesn't match, repeat step 2 with the release from step 1.

Run the client as uv run vaultspec-rag, and start or stop the service from the host installation. When you upgrade the host, move each client to the same release with the upgrade steps.

Use it

Index and search

From the root of each repository you want to search, index it. The command queues indexing jobs and prints their IDs:

vaultspec-rag index

Follow progress with vaultspec-rag server jobs --watch, and wait until the jobs finish before searching. Afterwards, the service watches for file changes and updates the index automatically.

Search source code with --type code, or decision records with --type vault. Results list file paths with their matching passages:

vaultspec-rag search "parse query text into filters" --type code

A client runs the same commands with the uv run prefix. If results are missing or incomplete, check the index and adjust the query. The getting-started tutorial walks through a first search, and AI assistant setup connects your AI assistant. See index maintenance for rebuilding or removing indexed content.

Optional Typesafe classification

Set VAULTSPEC_RAG_TYPESAFE_API_KEY in the service account's environment before starting the server to opt into paid Typesafe classification. A valid, funded key enables query interpretation and reranking using the full result content, including removal of confidently irrelevant hits. The server sends queries and candidate content to Typesafe; without a usable key, search keeps its existing local ranking.

server start and server status show the running server's enrollment and whether a recent evaluation succeeded. No separate enable flag is needed. See activation, fallback, and status meanings before enabling it. The local search models and GPU are still required.

Other ways to install

To have one Python project's environment run the service, install the host as a project dependency. Unlike a client, this adds the GPU packages to the project.

Without a Python toolchain, use the prebuilt Windows, Linux, or Apple silicon macOS binaries.

Remove vaultspec-rag

Follow the removal guide to preview project changes, choose whether to clean up indexes, and remove the package.

Refine searches

• Choose query terms.
• Filter by language, path, or document type.
• Investigate missing results and index coverage.
• Monitor indexing jobs.

Use it from an AI assistant

Follow MCP setup to connect your coding agent. The default toolset includes tools that change or delete indexes. To restrict access, see withholding the mutating tools.

Use an on-disk index

By default, the service keeps its index in managed Qdrant, a separate process. The optional local-only backend keeps the index in each repository's .vault/ folder instead. It still needs a GPU and the models. To use it, set VAULTSPEC_RAG_INDEX_SUPPORT_PROFILE=embedded-local in the environment that starts the service, because the default resource profile refuses the local-only backend.

Switching backends doesn't migrate your existing index. Follow backend setup to switch.

Read PDFs and other formats

Converters extract content from unsupported formats for indexing. See converter setup.

Converters run without a sandbox, with the permissions of the account running RAG. They can access files and the network. They can run during explicit indexing, watched changes, and agent-triggered reindexing.

Before indexing, inspect .vaultragpreprocess.toml and its commands. Use vaultspec-rag preprocess status to inspect configuration without running converters. See security and disable options.

Scripting it

For JSON output and result handling, follow scripting and automation.

Documentation

• Run your first search
• Installation and troubleshooting
• Worked searches
• Commands and flags
• Configuration reference
• Architecture and indexing internals
• Release notes

Status and help

vaultspec-rag is Beta. Report issues with your version, operating system, GPU, command, and error output. Redact credentials and private content before posting.

Related projects

• vaultspec-core: Decision-driven harness for coding agents, and humans.
• vaultspec-dashboard: The human-facing visual workspace for a Vaultspec project.

License

vaultspec-rag is released under the MIT License.