{
  "markdown": "# 🦖 VelociRAG\n\n**Lightning-fast RAG for AI agents.**\n\n_Four-layer retrieval fusion powered by ONNX Runtime. No PyTorch. Sub-200ms warm search. Incremental graph updates. MCP-ready._\n\n---\n\nMost 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.\n\n## 🚀 Quick Start\n\n### MCP Server (Claude, Cursor, Windsurf)\n\n```bash\npip install \"velocirag[mcp]\"\nvelocirag index ./my-docs\nvelocirag mcp\n```\n\n**Claude Code** — add to `.mcp.json` in your project root:\n```json\n{\n  \"mcpServers\": {\n    \"velocirag\": {\n      \"command\": \"velocirag\",\n      \"args\": [\"mcp\"],\n      \"env\": { \"VELOCIRAG_DB\": \"/path/to/data\" }\n    }\n  }\n}\n```\nThen open `/mcp` in Claude Code and enable the `velocirag` server. If using a virtualenv, use the full path to the binary (e.g. `.venv/bin/velocirag`).\n\n**Claude Desktop** — add to `claude_desktop_config.json`:\n```json\n{\n  \"mcpServers\": {\n    \"velocirag\": {\n      \"command\": \"velocirag\",\n      \"args\": [\"mcp\", \"--db\", \"/path/to/data\"]\n    }\n  }\n}\n```\n\n**Cursor** — add to `.cursor/mcp.json`:\n```json\n{\n  \"mcpServers\": {\n    \"velocirag\": {\n      \"command\": \"velocirag\",\n      \"args\": [\"mcp\", \"--db\", \"/path/to/data\"]\n    }\n  }\n}\n```\n\n### Python API\n\n```python\nfrom velocirag import Embedder, VectorStore, Searcher\n\nembedder = Embedder()\nstore = VectorStore('./my-db', embedder)\nstore.add_directory('./my-docs')\nsearcher = Searcher(store, embedder)\nresults = searcher.search('query', limit=5)\n```\n\n### CLI\n\n```bash\npip install velocirag\nvelocirag index ./my-docs\nvelocirag search \"your query here\"\n```\n\n### Search Daemon (warm engine for CLI users)\n\n```bash\nvelocirag serve --db ./my-data        # start daemon (background)\nvelocirag search \"query\"              # auto-routes through daemon\nvelocirag status                      # check daemon health\nvelocirag stop                        # stop daemon\n```\n\nThe 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.\n\n## 🎯 Why VelociRAG?\n\n- **4-layer search** — vector + BM25 keyword + knowledge graph + metadata, fused with RRF\n- **No LLM needed** — search runs entirely on local models (MiniLM + TinyBERT, ~80MB total)\n- **No GPU needed** — pure ONNX inference, runs on any machine\n- **~3ms warm search** — daemon keeps models + indices warm over Unix socket\n- **Incremental indexing** — add files without rebuilding the whole index\n- **MCP server** — plug into Claude, Cursor, Windsurf, any MCP client\n\n### Related Projects\n\n- **[Memkoshi](https://github.com/HaseebKhalid1507/memkoshi)** — Agent memory system. Uses VelociRAG as its search engine.\n- **[Stelline](https://github.com/HaseebKhalid1507/Stelline)** — Session intelligence. Crafts memories from conversation logs.\n- **[Glyph](https://github.com/HaseebKhalid1507/Glyph)** — MCP security scanner and runtime protection.\n\n## 🏗️ How It Works\n\n**The 4-layer pipeline:**\n```\nQuery → expand (acronyms, variants)\n      → [Vector]   FAISS cosine similarity (384d, MiniLM-L6-v2 via ONNX)\n      → [Keyword]  BM25 via SQLite FTS5\n      → [Graph]    Knowledge graph traversal\n      → [Metadata] Structured SQL filters (tags, status, project)\n      → RRF Fusion → Cross-encoder rerank → Results\n```\n\n**What each layer catches:**\n\n| Query type | Vector | Keyword | Graph | Metadata |\n|-----------|:---:|:---:|:---:|:---:|\n| Conceptual (\"improve error handling\") | ✅ | — | — | — |\n| Exact match (\"ERR_CONNECTION_REFUSED\") | — | ✅ | — | — |\n| Connected concepts | — | — | ✅ | — |\n| Filtered (\"#python status:active\") | — | — | — | ✅ |\n| Combined (\"React state management\") | ✅ | ✅ | ✅ | ✅ |\n\n## ✨ Features\n\n- **ONNX Runtime** — 184ms cold start, 3ms cached. No PyTorch, no GPU\n- **Four-layer fusion** — FAISS vector similarity + SQLite FTS5 (BM25) + knowledge graph + metadata filtering, merged via reciprocal rank fusion\n- **Cross-encoder reranking** — TinyBERT reranker via ONNX Runtime — included in base install, no PyTorch needed. Downloads ~17MB model on first use\n- **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\n- **MCP server** — Five tools (search, index, add_document, health, list_sources) for Claude, Cursor, Windsurf\n- **Search daemon** — Unix socket server keeps ONNX model + FAISS index warm between queries\n- **Knowledge graph** — Analyzers build entity, temporal, topic, and explicit-link edges from markdown. Optional GLiNER NER. 418 files in 2.1s\n- **Smart chunking** — Header-aware splitting preserves document structure and parent context\n- **Query expansion** — Acronym registry, casing/spacing variants, underscore-aware tokenization\n- **Runs anywhere** — CPU-only, 8GB RAM, no API keys, no external services\n\n## 🤖 MCP Server\n\nVelociRAG exposes a Model Context Protocol server for seamless agent integration:\n\n**Available tools:**\n- `search` — 4-layer fusion search with reranking\n- `index` — Add documents to the knowledge base\n- `add_document` — Insert single document\n- `health` — System diagnostics\n- `list_sources` — Show indexed document sources\n\nThe MCP server process stays alive between queries, so models load once and every subsequent search is warm. Works with any MCP-compatible client.\n\n## 🐍 Python API\n\n**Full 4-layer unified search:**\n```python\nfrom velocirag import (\n    Embedder, VectorStore, Searcher,\n    GraphStore, MetadataStore, UnifiedSearch,\n    GraphPipeline\n)\n\n# Build the full stack\nembedder = Embedder()\nstore = VectorStore('./search-db', embedder)\ngraph_store = GraphStore('./search-db/graph.db')\nmetadata_store = MetadataStore('./search-db/metadata.db')\n\n# Index with graph + metadata\nstore.add_directory('./docs')\npipeline = GraphPipeline(graph_store, embedder, metadata_store)\npipeline.build('./docs', source_name='my-docs')\n\n# Unified search across all layers\nsearcher = Searcher(store, embedder)\nunified = UnifiedSearch(searcher, graph_store, metadata_store)\nresults = unified.search(\n    'machine learning algorithms',\n    limit=5,\n    enrich_graph=True,\n    filters={'tags': ['python'], 'status': 'active'}\n)\n```\n\n**Quick semantic search:**\n```python\nfrom velocirag import Embedder, VectorStore, Searcher\n\nembedder = Embedder()\nstore = VectorStore('./db', embedder)\nstore.add_directory('./docs')\nsearcher = Searcher(store, embedder)\nresults = searcher.search('neural networks', limit=10)\n```\n\n**Incremental graph updates:**\n```python\nfrom velocirag import Embedder, GraphStore, GraphPipeline\n\n# First run — full build, populates provenance\ngs = GraphStore('./db/graph.db')\npipeline = GraphPipeline(gs, embedder=Embedder())\npipeline.build('./docs', source_name='my-docs')  # full build\n\n# Subsequent runs — only changed files get reprocessed\npipeline.build('./docs', source_name='my-docs')  # incremental (automatic)\n\n# Force full rebuild\npipeline.build('./docs', source_name='my-docs', force_rebuild=True)\n\n# Multi-source graphs\npipeline.build('./project-a', source_name='project-a')\npipeline.build('./project-b', source_name='project-b')  # isolated provenance\n\n# Deleted files automatically cascade across all stores\n# (vector, FTS5, graph, metadata) on next build\n```\n\n## 💻 CLI Reference\n\n```bash\n# Index documents (graph + metadata built by default)\nvelocirag index <path> [--no-graph] [--no-metadata] [--gliner] [--full-graph] [--force]\n                       [--source NAME] [--db PATH]\n\n# Search across all layers (auto-routes through daemon if running)\nvelocirag search <query> [--limit N] [--threshold F] [--format text|json]\n\n# Search daemon\nvelocirag serve [--db PATH] [-f]         # start daemon (-f for foreground)\nvelocirag stop                            # stop daemon\nvelocirag status                          # check daemon health\n\n# Metadata queries\nvelocirag query [--tags TAG] [--status S] [--project P] [--recent N]\n\n# System health and status\nvelocirag health [--format text|json]\n\n# Start MCP server\nvelocirag mcp [--db PATH] [--transport stdio|sse]\n```\n\n**Options:**\n- `--no-graph` — Skip knowledge graph build\n- `--no-metadata` — Skip metadata extraction\n- `--full-graph` — Build graph WITH semantic similarity edges (~2GB extra RAM)\n- `--source NAME` — Label for multi-source provenance isolation\n- `--force` — Clear and rebuild from scratch\n- `--gliner` — Use GLiNER for entity extraction (requires `pip install \"velocirag[ner]\"`)\n\n## 📊 Performance\n\nReal benchmarks on [ByteByteGo/system-design-101](https://github.com/ByteByteGoHq/system-design-101) (418 files, 1,001 chunks):\n\n| Metric | Value |\n|--------|-------|\n| **Index (418 files)** | **13.6s** |\n| **Search (warm, 5 results)** | **35–90ms** |\n| **Graph build (light)** | **2.1s** → 2,397 nodes, 8,717 edges |\n| **Incremental update (1 file)** | **1.3s** |\n| **Reranker** | Cross-encoder TinyBERT via ONNX |\n| **Install size** | ~80MB (no PyTorch) |\n| **RAM usage** | <1GB with all models loaded |\n\nProduction deployment (6,300+ chunks, 3 sources, 950 files):\n\n| Metric | Value |\n|--------|-------|\n| **Full search (warm)** | **16ms avg, 2ms min** |\n| **Full search (first run)** | **22ms avg, 4ms min** |\n| **Search P50 / P95** | **17ms / 55ms** |\n| **Hit rate (100-query benchmark)** | **99/100** |\n| **Graph** | 3,125 nodes, 132,320 edges |\n| **Reranker** | Cross-encoder TinyBERT via ONNX |\n| **RAM** | <1GB with all models loaded |\n\n## ⚙️ Configuration\n\n| Environment Variable | Default | Description |\n|---------------------|---------|-------------|\n| `VELOCIRAG_DB` | `./.velocirag` | Database directory |\n| `VELOCIRAG_SOCKET` | `/tmp/velocirag-daemon.sock` | Daemon socket path |\n| `NO_COLOR` | — | Disable colored output |\n\n**Dependencies (all included in base install):**\n- `onnxruntime` — ONNX inference (embedder + reranker)\n- `tokenizers` + `huggingface-hub` — model loading\n- `faiss-cpu` — vector similarity search\n- `networkx` + `scikit-learn` — knowledge graph + topic clustering\n- `numpy`, `click`, `pyyaml`, `python-frontmatter`\n\n**Optional extras:**\n- `pip install \"velocirag[mcp]\"` — MCP server (adds `fastmcp`)\n- `pip install \"velocirag[ner]\"` — GLiNER entity extraction (adds `gliner`, requires PyTorch)\n\n## 📚 References\n\nVelociRAG builds on these foundational works:\n\n**Core Fusion & Retrieval**\n> **Reciprocal Rank Fusion** — Cormack, G. V., Clarke, C. L. A., & Büttcher, S. (2009). \"Reciprocal Rank Fusion outperforms Condorcet and individual Rank Learning Methods.\" _SIGIR '09_.  \n> Core fusion algorithm for merging results across retrieval layers.\n\n> **BM25** — Robertson, S. E., Walker, S., Jones, S., Hancock-Beaulieu, M., & Gatford, M. (1994). \"Okapi at TREC-3.\" _TREC-3_.  \n> Keyword search foundation via SQLite FTS5.\n\n**Embeddings & Neural IR**\n> **Sentence-BERT** — Reimers, N., & Gurevych, I. (2019). \"Sentence-BERT: Sentence Embeddings using Siamese BERT-Networks.\" _EMNLP 2019_. [paper](https://arxiv.org/abs/1908.10084)  \n> Dense embedding architecture using `all-MiniLM-L6-v2`.\n\n> **MiniLM** — Wang, W., Wei, F., Dong, L., Bao, H., Yang, N., & Zhou, M. (2020). \"MiniLM: Deep Self-Attention Distillation for Task-Agnostic Compression of Pre-Trained Transformers.\" _NeurIPS 2020_. [paper](https://arxiv.org/abs/2002.10957)  \n> Efficient transformer distillation for production embedding models.\n\n**Reranking & Neural Models**\n> **Cross-Encoder Reranking** — Nogueira, R., & Cho, K. (2019). \"Passage Re-ranking with BERT.\" _arXiv:1901.04085_. [paper](https://arxiv.org/abs/1901.04085)  \n> Cross-attention reranking with TinyBERT on MS MARCO.\n\n> **TinyBERT** — Jiao, X., et al. (2020). \"TinyBERT: Distilling BERT for Natural Language Understanding.\" _Findings of EMNLP 2020_. [paper](https://arxiv.org/abs/1909.10351)  \n> Compressed BERT for fast reranking inference.\n\n**Vector Search & Systems**\n> **FAISS** — Johnson, J., Douze, M., & Jégou, H. (2019). \"Billion-scale similarity search with GPUs.\" _IEEE Transactions on Big Data_. [paper](https://arxiv.org/abs/1702.08734)  \n> High-performance vector similarity search engine.\n\n> **GLiNER** — Zaratiana, U., Nzeyimana, A., & Holat, P. (2023). \"GLiNER: Generalist Model for Named Entity Recognition using Bidirectional Transformer.\" _arXiv:2311.08526_. [paper](https://arxiv.org/abs/2311.08526)  \n> Generalist NER for knowledge graph entity extraction (optional dependency).\n\n## 📄 License\n\n[MIT](LICENSE) — Use it anywhere, build anything.\n\n**Need agent integration help?** Check [AGENTS.md](AGENTS.md) for machine-readable project context.\n\n---\n\n_Built for agents who think fast and remember faster._\n\n<!-- mcp-name: io.github.HaseebKhalid1507/velocirag -->\n",
  "bytes": 13048,
  "sha": "163fbfeeb75823583b1796dbd85e233d9dc66c7333ae3c526ea3f195628c6550",
  "repo_slug": "haseebkhalid1507/velocirag",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_haseebkhalid1507_velocirag_ede33913/readme"
}