VelociRAG

RAG ultrarrápido para agentes de IA. Fusión de 4 capas (vectorial, BM25, gráfica, metadatos), ONNX Runtime, búsqueda en menos de 200 ms, sin PyTorch.

GitHub

Prueba este MCPPatrocinado

Documentación

🦖 VelociRAG

RAG ultrarrápido para agentes de IA.

Fusión de recuperación de cuatro capas impulsada por ONNX Runtime. Sin PyTorch. Búsqueda en caliente en menos de 200 ms. Actualizaciones incrementales de grafos. Listo para MCP.

La mayoría de las soluciones RAG o arrastran más de 2 GB de PyTorch o te limitan a una búsqueda vectorial de una sola capa. VelociRAG te ofrece cuatro métodos de recuperación — similitud vectorial, coincidencia de palabras clave BM25, recorrido de grafos de conocimiento y filtrado de metadatos — fusionados mediante fusión de rango recíproco con reordenamiento de codificador cruzado. Todo ejecutándose en ONNX Runtime, sin GPU, sin claves de API. Incluye un servidor MCP para integración con agentes, un daemon de socket Unix para consultas en caliente y una CLI que simplemente funciona.

🚀 Inicio rápido

Servidor MCP (Claude, Cursor, Windsurf)

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

Claude Code — añade a .mcp.json en la raíz de tu proyecto:

{
  "mcpServers": {
    "velocirag": {
      "command": "velocirag",
      "args": ["mcp"],
      "env": { "VELOCIRAG_DB": "/path/to/data" }
    }
  }
}

Luego abre /mcp en Claude Code y habilita el servidor velocirag. Si usas un virtualenv, usa la ruta completa al binario (p. ej., .venv/bin/velocirag).

Claude Desktop — añade a claude_desktop_config.json:

{
  "mcpServers": {
    "velocirag": {
      "command": "velocirag",
      "args": ["mcp", "--db", "/path/to/data"]
    }
  }
}

Cursor — añade a .cursor/mcp.json:

{
  "mcpServers": {
    "velocirag": {
      "command": "velocirag",
      "args": ["mcp", "--db", "/path/to/data"]
    }
  }
}

API de Python

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"

Daemon de búsqueda (motor en caliente para usuarios de CLI)

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

El daemon mantiene el modelo ONNX + el índice FAISS en caliente a través de un socket Unix. La primera consulta carga el motor (~1 s), las consultas posteriores se devuelven en ~180 ms con fusión completa de 4 capas.

🎯 ¿Por qué VelociRAG?

Búsqueda de 4 capas — vector + palabras clave BM25 + grafo de conocimiento + metadatos, fusionados con RRF
Sin necesidad de LLM — la búsqueda se ejecuta completamente en modelos locales (MiniLM + TinyBERT, ~80 MB en total)
Sin necesidad de GPU — inferencia ONNX pura, se ejecuta en cualquier máquina
Búsqueda en caliente ~3 ms — el daemon mantiene modelos e índices en caliente a través de socket Unix
Indexación incremental — añade archivos sin reconstruir todo el índice
Servidor MCP — conéctalo a Claude, Cursor, Windsurf, cualquier cliente MCP

Proyectos relacionados

Memkoshi — Sistema de memoria para agentes. Usa VelociRAG como su motor de búsqueda.
Stelline — Inteligencia de sesiones. Crea recuerdos a partir de registros de conversaciones.
Glyph — Escáner de seguridad MCP y protección en tiempo de ejecución.

🏗️ Cómo funciona

El pipeline de 4 capas:

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

Qué captura cada capa:

Tipo de consulta	Vector	Palabras clave	Grafo	Metadatos
Conceptual ("mejorar el manejo de errores")	✅	—	—	—
Coincidencia exacta ("ERR_CONNECTION_REFUSED")	—	✅	—	—
Conceptos conectados	—	—	✅	—
Filtrada ("#python estado:activo")	—	—	—	✅
Combinada ("gestión de estado en React")	✅	✅	✅	✅

✨ Características

ONNX Runtime — 184 ms de arranque en frío, 3 ms en caché. Sin PyTorch, sin GPU
Fusión de cuatro capas — similitud vectorial FAISS + SQLite FTS5 (BM25) + grafo de conocimiento + filtrado de metadatos, fusionados mediante fusión de rango recíproco
Reordenamiento de codificador cruzado — reordenador TinyBERT mediante ONNX Runtime — incluido en la instalación base, sin necesidad de PyTorch. Descarga un modelo de ~17 MB en el primer uso
Actualizaciones incrementales de grafos — el seguimiento de procedencia centrado en archivos detecta qué cambió y solo reconstruye los nodos/aristas afectados. Las eliminaciones en cascada mantienen la coherencia en todos los almacenes (vector, grafo, metadatos). Soporte de múltiples fuentes con procedencia aislada por fuente
Servidor MCP — cinco herramientas (search, index, add_document, health, list_sources) para Claude, Cursor, Windsurf
Daemon de búsqueda — servidor de socket Unix que mantiene el modelo ONNX + el índice FAISS en caliente entre consultas
Grafo de conocimiento — los analizadores construyen aristas de entidades, temporales, temáticas y de enlaces explícitos a partir de Markdown. NER GLiNER opcional. 418 archivos en 2,1 s
Fragmentación inteligente — la división consciente de encabezados preserva la estructura del documento y el contexto principal
Expansión de consultas — registro de acrónimos, variantes de mayúsculas/espaciado, tokenización consciente de guiones bajos
Funciona en cualquier lugar — solo CPU, 8 GB de RAM, sin claves de API, sin servicios externos

🤖 Servidor MCP

VelociRAG expone un servidor de Protocolo de Contexto de Modelo para una integración perfecta con agentes:

Herramientas disponibles:

search — búsqueda de fusión de 4 capas con reordenamiento
index — añade documentos a la base de conocimiento
add_document — inserta un documento único
health — diagnóstico del sistema
list_sources — muestra las fuentes de documentos indexados

El proceso del servidor MCP permanece activo entre consultas, por lo que los modelos se cargan una vez y cada búsqueda posterior está en caliente. Funciona con cualquier cliente compatible con MCP.

🐍 API de Python

Búsqueda unificada completa de 4 capas:

from velocirag import (
    Embedder, VectorStore, Searcher,
    GraphStore, MetadataStore, UnifiedSearch,
    GraphPipeline
)

# Build the full stack
embedder = Embedder()
store = VectorStore('./search-db', embedder)
graph_store = GraphStore('./search-db/graph.db')
metadata_store = MetadataStore('./search-db/metadata.db')

# Index with graph + metadata
store.add_directory('./docs')
pipeline = GraphPipeline(graph_store, embedder, metadata_store)
pipeline.build('./docs', source_name='my-docs')

# Unified search across all layers
searcher = Searcher(store, embedder)
unified = UnifiedSearch(searcher, graph_store, metadata_store)
results = unified.search(
    'machine learning algorithms',
    limit=5,
    enrich_graph=True,
    filters={'tags': ['python'], 'status': 'active'}
)

Búsqueda semántica rápida:

from velocirag import Embedder, VectorStore, Searcher

embedder = Embedder()
store = VectorStore('./db', embedder)
store.add_directory('./docs')
searcher = Searcher(store, embedder)
results = searcher.search('neural networks', limit=10)

Actualizaciones incrementales de grafos:

from velocirag import Embedder, GraphStore, GraphPipeline

# First run — full build, populates provenance
gs = GraphStore('./db/graph.db')
pipeline = GraphPipeline(gs, embedder=Embedder())
pipeline.build('./docs', source_name='my-docs')  # full build

# Subsequent runs — only changed files get reprocessed
pipeline.build('./docs', source_name='my-docs')  # incremental (automatic)

# Force full rebuild
pipeline.build('./docs', source_name='my-docs', force_rebuild=True)

# Multi-source graphs
pipeline.build('./project-a', source_name='project-a')
pipeline.build('./project-b', source_name='project-b')  # isolated provenance

# Deleted files automatically cascade across all stores
# (vector, FTS5, graph, metadata) on next build

💻 Referencia de CLI

# Index documents (graph + metadata built by default)
velocirag index <path> [--no-graph] [--no-metadata] [--gliner] [--full-graph] [--force]
                       [--source NAME] [--db PATH]

# Search across all layers (auto-routes through daemon if running)
velocirag search <query> [--limit N] [--threshold F] [--format text|json]

# Search daemon
velocirag serve [--db PATH] [-f]         # start daemon (-f for foreground)
velocirag stop                            # stop daemon
velocirag status                          # check daemon health

# Metadata queries
velocirag query [--tags TAG] [--status S] [--project P] [--recent N]

# System health and status
velocirag health [--format text|json]

# Start MCP server
velocirag mcp [--db PATH] [--transport stdio|sse]

Opciones:

--no-graph — omite la construcción del grafo de conocimiento
--no-metadata — omite la extracción de metadatos
--full-graph — construye el grafo CON aristas de similitud semántica (~2 GB extra de RAM)
--source NAME — etiqueta para aislamiento de procedencia de múltiples fuentes
--force — limpia y reconstruye desde cero
--gliner — usa GLiNER para extracción de entidades (requiere pip install "velocirag[ner]")

📊 Rendimiento

Puntos de referencia reales en ByteByteGo/system-design-101 (418 archivos, 1001 fragmentos):

Métrica	Valor
Índice (418 archivos)	13,6 s
Búsqueda (en caliente, 5 resultados)	35–90 ms
Construcción del grafo (ligero)	2,1 s → 2397 nodos, 8717 aristas
Actualización incremental (1 archivo)	1,3 s
Reordenador	TinyBERT de codificador cruzado mediante ONNX
Tamaño de instalación	~80 MB (sin PyTorch)
Uso de RAM	<1 GB con todos los modelos cargados

Despliegue en producción (más de 6300 fragmentos, 3 fuentes, 950 archivos):

Métrica	Valor
Búsqueda completa (en caliente)	16 ms promedio, 2 ms mínimo
Búsqueda completa (primera ejecución)	22 ms promedio, 4 ms mínimo
Búsqueda P50 / P95	17 ms / 55 ms
Tasa de aciertos (benchmark de 100 consultas)	99/100
Grafo	3125 nodos, 132 320 aristas
Reordenador	TinyBERT de codificador cruzado mediante ONNX
RAM	<1 GB con todos los modelos cargados

⚙️ Configuración

Variable de entorno	Predeterminado	Descripción
`VELOCIRAG_DB`	`./.velocirag`	Directorio de la base de datos
`VELOCIRAG_SOCKET`	`/tmp/velocirag-daemon.sock`	Ruta del socket del daemon
`NO_COLOR`	—	Desactiva la salida de color

Dependencias (todas incluidas en la instalación base):

onnxruntime — inferencia ONNX (incrustador + reordenador)
tokenizers + huggingface-hub — carga de modelos
faiss-cpu — búsqueda de similitud vectorial
networkx + scikit-learn — grafo de conocimiento + agrupación de temas
numpy, click, pyyaml, python-frontmatter

Extras opcionales:

pip install "velocirag[mcp]" — servidor MCP (añade fastmcp)
pip install "velocirag[ner]" — extracción de entidades GLiNER (añade gliner, requiere PyTorch)

📚 Referencias

VelociRAG se basa en estos trabajos fundamentales:

Fusión y recuperación centrales

Fusión de rango recíproco — Cormack, G. V., Clarke, C. L. A., & Büttcher, S. (2009). "Reciprocal Rank Fusion outperforms Condorcet and individual Rank Learning Methods." SIGIR '09.
Algoritmo de fusión central para combinar resultados entre capas de recuperación.

BM25 — Robertson, S. E., Walker, S., Jones, S., Hancock-Beaulieu, M., & Gatford, M. (1994). "Okapi at TREC-3." TREC-3.
Base de búsqueda de palabras clave mediante SQLite FTS5.

Incrustaciones e IR neuronal

Sentence-BERT — Reimers, N., & Gurevych, I. (2019). "Sentence-BERT: Sentence Embeddings using Siamese BERT-Networks." EMNLP 2019. paper
Arquitectura de incrustaciones densas usando all-MiniLM-L6-v2.

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
Destilación eficiente de transformers para modelos de incrustación en producción.

Reordenamiento y modelos neuronales

Reordenamiento de codificador cruzado — Nogueira, R., & Cho, K. (2019). "Passage Re-ranking with BERT." arXiv:1901.04085. paper
Reordenamiento de atención cruzada con TinyBERT en MS MARCO.

TinyBERT — Jiao, X., et al. (2020). "TinyBERT: Distilling BERT for Natural Language Understanding." Findings of EMNLP 2020. paper
BERT comprimido para inferencia de reordenamiento rápida.

Búsqueda vectorial y sistemas

FAISS — Johnson, J., Douze, M., & Jégou, H. (2019). "Billion-scale similarity search with GPUs." IEEE Transactions on Big Data. paper
Motor de búsqueda de similitud vectorial de alto rendimiento.

GLiNER — Zaratiana, U., Nzeyimana, A., & Holat, P. (2023). "GLiNER: Generalist Model for Named Entity Recognition using Bidirectional Transformer." arXiv:2311.08526. paper
NER generalista para extracción de entidades en grafos de conocimiento (dependencia opcional).

📄 Licencia

MIT — Úsalo en cualquier lugar, construye cualquier cosa.

¿Necesitas ayuda con la integración de agentes? Consulta AGENTS.md para obtener contexto del proyecto legible por máquina.

Construido para agentes que piensan rápido y recuerdan más rápido.