🦖 VelociRAG

Lightning-fast RAG for AI agents.

_Four-layer retrieval fusion powered by ONNX Runtime. No PyTorch. Sub-200ms warm search. Incremental graph updates. MCP-ready._

---

Most RAG solutions either drag in 2GB+ of PyTorch or limit you to single-layer vector search. VelociRAG gives you four retrieval methods — vector similarity, BM25 keyword matching, knowledge graph traversal, and metadata filtering — fused through reciprocal rank fusion with cross-encoder reranking. All running on ONNX Runtime, no GPU, no API keys. Comes with an MCP server for agent integration, a Unix socket daemon for warm queries, and a CLI that just works.

🚀 Quick Start

MCP Server (Claude, Cursor, Windsurf)

pip install "velocirag[mcp]"
velocirag index ./my-docs
velocirag mcp

Claude Code — add to .mcp.json in your project root:

{

  "mcpServers": {

    "velocirag": {

      "command": "velocirag",

      "args": ["mcp"],

      "env": { "VELOCIRAG_DB": "/path/to/data" }

    }

  }

}

Claude Desktop — add to claude_desktop_config.json:

{

  "mcpServers": {

    "velocirag": {

      "command": "velocirag",

      "args": ["mcp", "--db", "/path/to/data"]

    }

  }

}

Cursor — add to .cursor/mcp.json:

{

  "mcpServers": {

    "velocirag": {

      "command": "velocirag",

      "args": ["mcp", "--db", "/path/to/data"]

    }

  }

}

Python API

from velocirag import Embedder, VectorStore, Searcher
embedder = Embedder()

store = VectorStore('./my-db', embedder)

store.add_directory('./my-docs')

searcher = Searcher(store, embedder)

results = searcher.search('query', limit=5)

CLI

pip install velocirag
velocirag index ./my-docs
velocirag search "your query here"

Search Daemon (warm engine for CLI users)

velocirag serve --db ./my-data        # start daemon (background)
velocirag search "query"              # auto-routes through daemon
velocirag status                      # check daemon health
velocirag stop                        # stop daemon

The daemon keeps the ONNX model + FAISS index warm over a Unix socket. First query loads the engine (~1s), subsequent queries return in ~180ms with full 4-layer fusion.

🎯 Why VelociRAG?

| | VelociRAG | LangChain | LlamaIndex | Chroma | mcp-local-rag |
|---|:---:|:---:|:---:|:---:|:---:|
| Search layers | 4 | 2 | 2 | 1 | 2 |
| Cross-encoder reranking | ✅ | ❌ | ✅ | ❌ | ❌ |
| Knowledge graph | ✅ | ❌ | ✅ | ❌ | ❌ |
| Incremental updates | ✅ | ❌ | ❌ | ❌ | ❌ |
| LLM required for search | ❌ | ⚠️ | ⚠️ | ❌ | ❌ |
| MCP server | ✅ | ❌ | ❌ | ❌ | ✅ |
| GPU required | ❌ | ❌ | ❌ | ❌ | ❌ |
| PyTorch required | ❌ | ✅ | ✅ | ❌ | ❌ |
| Install size | ~80MB | ~750MB+ | ~750MB+ | ~50MB | ~30MB |
| Warm search latency | ~3ms | — | — | ~50ms | ~200ms |

🏗️ How It Works

The 4-layer pipeline:

Query → expand (acronyms, variants)

      → [Vector]   FAISS cosine similarity (384d, MiniLM-L6-v2 via ONNX)

      → [Keyword]  BM25 via SQLite FTS5

      → [Graph]    Knowledge graph traversal

      → [Metadata] Structured SQL filters (tags, status, project)

      → RRF Fusion → Cross-encoder rerank → Results

What each layer catches:

| Query type | Vector | Keyword | Graph | Metadata |
|-----------|:---:|:---:|:---:|:---:|
| Conceptual ("improve error handling") | ✅ | — | — | — |
| Exact match ("ERR_CONNECTION_REFUSED") | — | ✅ | — | — |
| Connected concepts | — | — | ✅ | — |
| Filtered ("#python status:active") | — | — | — | ✅ |
| Combined ("React state management") | ✅ | ✅ | ✅ | ✅ |

✨ Features

- ONNX Runtime — 184ms cold start, 3ms cached. No PyTorch, no GPU
- Four-layer fusion — FAISS vector similarity + SQLite FTS5 (BM25) + knowledge graph + metadata filtering, merged via reciprocal rank fusion
- Cross-encoder reranking — TinyBERT reranker via ONNX Runtime — included in base install, no PyTorch needed. Downloads ~17MB model on first use
- Incremental graph updates — file-centric provenance tracking detects what changed and only rebuilds affected nodes/edges. Cascading deletes maintain consistency across all stores (vector, graph, metadata). Multi-source support with isolated provenance per source
- MCP server — Five tools (search, index, add_document, health, list_sources) for Claude, Cursor, Windsurf
- Search daemon — Unix socket server keeps ONNX model + FAISS index warm between queries
- Knowledge graph — Analyzers build entity, temporal, topic, and explicit-link edges from markdown. Optional GLiNER NER. 418 files in 2.1s
- Smart chunking — Header-aware splitting preserves document structure and parent context
- Query expansion — Acronym registry, casing/spacing variants, underscore-aware tokenization
- Runs anywhere — CPU-only, 8GB RAM, no API keys, no external services

🤖 MCP Server

VelociRAG exposes a Model Context Protocol server for seamless agent integration:

Available tools:
- search — 4-layer fusion search with reranking
- index — Add documents to the knowledge base
- add_document — Insert single document
- health — System diagnostics
- list_sources — Show indexed document sources

The MCP server process stays alive between queries, so models load once and every subsequent search is warm. Works with any MCP-compatible client.

🐍 Python API

Full 4-layer unified search:
```python
from velocirag import (
Embedder, VectorStore, Searcher,
GraphStore, MetadataStore, UnifiedSearch,
GraphPipeline
)