vaultspec-rag
The semantic search component for vault and code.
Search code and feature records by meaning through the command line or Model Context Protocol (MCP). Inference runs on your GPU.
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
For the Python installation below, use Python 3.13 or 3.14 and uv. Local indexing and search require NVIDIA CUDA on Linux or Windows, or Apple silicon on macOS. CPU inference and AMD GPUs are unsupported.
Check the memory and disk requirements before installing. That section also covers the smaller resource profile.
Install
Install a standalone tool for use across repositories. Choose the command for your platform. These CUDA commands use Python 3.13 and pin the GPU wheel so later tool upgrades retain it.
Windows x64:
uv tool install --python 3.13 "vaultspec-rag[gpu,mcp]" --with "torch @ https://download.pytorch.org/whl/cu130/torch-2.13.0%2Bcu130-cp313-cp313-win_amd64.whl"
Linux x86_64 (glibc 2.28 or newer):
uv tool install --python 3.13 "vaultspec-rag[gpu,mcp]" --with "torch @ https://download.pytorch.org/whl/cu130/torch-2.13.0%2Bcu130-cp313-cp313-manylinux_2_28_x86_64.whl"
Apple silicon macOS:
uv tool install --python 3.13 "vaultspec-rag[gpu,mcp]"
For other Python versions or Linux architectures, see GPU wheel selection.
If uv reports that its executables directory is missing from PATH, follow its
instructions before continuing. For an existing tool installation, follow the
upgrade and repair instructions before
replacing its environment.
Once installation succeeds, open the repository you want to search and run:
vaultspec-rag install --no-torch-config
This installs the repository's agent integration, downloads the three search models,
and provisions Qdrant, the index server. The GPU packages are already installed, so
--no-torch-config leaves the project's PyTorch configuration alone. The first setup
downloads several gigabytes; subsequent projects share the models and server binary.
Check the installation:
vaultspec-rag server doctor
Check that the report detects your GPU and finds all three models and the Qdrant binary. If it reports a problem, use the installation troubleshooting guide.
Use it
Start the service to load the models. The command waits until it is ready:
vaultspec-rag server start
Index the repository from its root:
vaultspec-rag index
Wait for indexing to finish before searching. Use vaultspec-rag server jobs --watch
to follow progress. The service watches for file changes and updates the index
automatically afterwards.
Search source code with --type code, or feature records with --type vault:
vaultspec-rag search "parse query text into filters" --type code
If results are missing or incomplete, check the index and adjust the query.
One service handles all your repositories. Run index in each repository you want
to search. See index maintenance for rebuilding or
removing indexed content.
Other ways to install
For a Python project that should carry the dependency, run:
uv add "vaultspec-rag[gpu]"
uv run vaultspec-rag install --sync
Approve the PyTorch configuration prompt. On Linux and Windows, --sync applies the
CUDA package source; macOS uses the standard MPS-capable wheel. Prefix subsequent
commands with uv run, for example uv run vaultspec-rag server start.
Without a Python toolchain, use the prebuilt Windows or Linux binaries.
Remove RAG
Follow the removal guide to preview project changes, choose whether to clean up indexes, and remove the package.
Write a query that finds it
Describe the behaviour and include names or terms the code would use. The description finds conceptual matches; the specific terms help distinguish them. See query examples for choosing words and interpreting weak matches.
Narrow the results
For code, add --include-path "src/**" to limit results to a source directory, or
--language python to select a language. For decision records, use
--type vault --doc-type adr. See search filters for excluding
tests, generated files, and other noise.
Check on the index
vaultspec-rag status tells you what's indexed, where it's stored, and which GPU it's
using. vaultspec-rag server doctor tells you whether the service, models, and search
server are ready.
To watch indexing as it happens, vaultspec-rag server jobs --watch opens a live view of
the running service. You get progress per job, what's waiting on the GPU, and the log for
whichever job you select.
If the index has fallen behind, run vaultspec-rag index again - it only picks up what
changed. See verify the index.
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, vaultspec-rag uses managed Qdrant in a separate process. The optional local-only backend keeps an embedded on-disk index inside the RAG process. It still requires a GPU and models.
Switching backends does not migrate your existing index. Follow backend setup.
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.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file vaultspec_rag-0.4.24.tar.gz.
File metadata
- Download URL: vaultspec_rag-0.4.24.tar.gz
- Upload date:
- Size: 6.2 MB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
uv/0.12.10 {"installer":{"name":"uv","version":"0.12.10","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
c720267f2af35ca666ff6938d76f51a2b71361ca88e9ebfea080fc7d1994c191
|
|
| MD5 |
e8cedd2b179c1e434ba4611302e3de7d
|
|
| BLAKE2b-256 |
57291f431bd764dbb2fdc0c442e8452e5f75da959e3349c97d0b24c7d0ed4c77
|
File details
Details for the file vaultspec_rag-0.4.24-py3-none-any.whl.
File metadata
- Download URL: vaultspec_rag-0.4.24-py3-none-any.whl
- Upload date:
- Size: 1.4 MB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
uv/0.12.10 {"installer":{"name":"uv","version":"0.12.10","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
8cf04b3db01d49a5c177f0ac705706736f0c8e3e98ce82863695510ab5025a74
|
|
| MD5 |
8ede0b1b23349a81e7a74b3bacc6a37d
|
|
| BLAKE2b-256 |
c603293c11b9ab469c49855ed09dd0ae2967be5850f20b0f0e30babdb64d6152
|
