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 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
To share a version with collaborators, add RAG as a project dependency.
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.
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, 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
Metadata
1 maintainer
Release files for vaultspec-rag 0.4.25
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| vaultspec_rag-0.4.25.tar.gz | 6.1 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| vaultspec_rag-0.4.25-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 7.5 MB
Release files / vaultspec_rag-0.4.25.tar.gz
| Download URL | vaultspec_rag-0.4.25.tar.gz |
|---|---|
| Size | 6.1 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b4df9d0de511c890e8e569afbfd4a1f495d60531b8b3121c8a0be77fa0dc353d
|
|
BLAKE2b-256 checksum How to use checksums |
c39dadb2c790574c2e109861042f97ec7ccaa95aa99880723c3b3256bb198e8a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is 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":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / vaultspec_rag-0.4.25-py3-none-any.whl
| Download URL | vaultspec_rag-0.4.25-py3-none-any.whl |
|---|---|
| Size | 1.4 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
7d55da6ad11e57a168ca5dd95c9ea27fbee600e4e3482d0f5f1ee92fd004682e
|
|
BLAKE2b-256 checksum How to use checksums |
47024240bd135ea479ebea0e83da972b681c8b907d345f5e788499d54c3d68cc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is 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":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
