vaultspec-rag 0.2.1

GPU-accelerated RAG module for vaultspec vault search

vaultspec-rag

---

Semantic search for your vaultspec vault and project codebase

vaultspec-rag adds GPU-accelerated search to projects managed by vaultspec-core. It indexes your .vault/ documents -- research notes, architecture decisions, plans, execution logs -- alongside your source code. Query both with natural language so your AI tools find relevant context on their own.

---

Getting started

Prerequisites

• Python 3.13 or later
• uv
• A CUDA GPU with at least 3 GB VRAM (mandatory -- no CPU fallback)
• vaultspec-core

Install

uv add vaultspec-rag

This pulls in vaultspec-core and all GPU dependencies.

Verify

vaultspec-rag --version

Index and search

vaultspec-rag indexes two sources: vault (.vault/ documents) and code (project source files).

vaultspec-rag index                          # both
vaultspec-rag index --type vault             # vault only
vaultspec-rag index --type code              # code only

vaultspec-rag search "architecture decision"
vaultspec-rag search --type code "error handling"

---

Using the MCP server

The Model Context Protocol (MCP) server gives AI assistants direct access to vault and codebase search. It runs in two transport modes with different project-resolution rules.

stdio mode -- one process per project. The MCP client launches vaultspec-search-mcp as a subprocess, scoped to a single workspace via VAULTSPEC_RAG_ROOT. Use this for Claude Desktop, Claude Code, and similar single-project AI tools.

{
  "mcpServers": {
    "vaultspec-rag": {
      "command": "vaultspec-search-mcp",
      "env": {
        "VAULTSPEC_RAG_ROOT": "/path/to/your/project"
      }
    }
  }
}

HTTP mode -- one daemon, many projects. Start vaultspec-rag server service start as a background daemon, then connect any MCP client to http://127.0.0.1:8766/mcp. The daemon has no default project; every tool call must include project_root. Use this to share one GPU-loaded service across workspaces.

See the MCP integration reference for the full tool list, both modes' contracts, and choosing between them.

---

Further reading

Guide	What it covers
Usage modes	Ad-hoc vs. service operation
CLI commands	Command tree, flags, --port fast path
Configuration	Precedence, environment variables, .vaultragignore
Service management	Background daemon, health endpoint, model warmup
Python API	Facade functions for programmatic use
Architecture overview	Access layers, GPU lifecycle, multi-project support
Models	Embedding stack and model cards

---

Getting help

Open an issue on GitHub.

---

Contributing and license

Contributions welcome -- bug reports, feature ideas, or pull requests. vaultspec-rag uses the MIT License.