VelociRAG

RAG ultrarrápido para agentes de IA. Fusão de 4 camadas (vetorial, BM25, grafo, metadados), ONNX Runtime, busca abaixo de 200ms, sem PyTorch.

GitHub

Experimente este MCPPatrocinado

Documentação

🦖 VelociRAG

RAG ultrarrápido para agentes de IA.

Fusão de recuperação em quatro camadas com ONNX Runtime. Sem PyTorch. Busca aquecida em menos de 200ms. Atualizações incrementais de grafo. Pronto para MCP.

A maioria das soluções de RAG ou arrasta 2GB+ de PyTorch ou limita você à busca vetorial de camada única. O VelociRAG oferece quatro métodos de recuperação — similaridade vetorial, correspondência de palavras-chave BM25, travessia de grafo de conhecimento e filtragem de metadados — fundidos por fusão de classificação recíproca com reordenação por cross-encoder. Tudo rodando em ONNX Runtime, sem GPU, sem chaves de API. Inclui um servidor MCP para integração com agentes, um daemon de socket Unix para consultas aquecidas e uma CLI que simplesmente funciona.

🚀 Início Rápido

Servidor MCP (Claude, Cursor, Windsurf)

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

Claude Code — adicione ao .mcp.json na raiz do seu projeto:

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

Em seguida, abra o /mcp no Claude Code e habilite o servidor velocirag. Se estiver usando um virtualenv, use o caminho completo para o binário (ex.: .venv/bin/velocirag).

Claude Desktop — adicione ao claude_desktop_config.json:

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

Cursor — adicione ao .cursor/mcp.json:

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

API 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 Busca (mecanismo aquecido para usuários da 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

O daemon mantém o modelo ONNX + índice FAISS aquecidos em um socket Unix. A primeira consulta carrega o mecanismo (~1s), consultas subsequentes retornam em ~180ms com fusão completa de 4 camadas.

🎯 Por que VelociRAG?

Busca em 4 camadas — vetor + palavras-chave BM25 + grafo de conhecimento + metadados, fundidos com RRF
Sem necessidade de LLM — a busca roda inteiramente em modelos locais (MiniLM + TinyBERT, ~80MB no total)
Sem necessidade de GPU — inferência ONNX pura, roda em qualquer máquina
Busca aquecida em ~3ms — o daemon mantém modelos + índices aquecidos em socket Unix
Indexação incremental — adicione arquivos sem reconstruir o índice inteiro
Servidor MCP — conecte-se ao Claude, Cursor, Windsurf, qualquer cliente MCP

Projetos Relacionados

Memkoshi — Sistema de memória para agentes. Usa VelociRAG como mecanismo de busca.
Stelline — Inteligência de sessão. Cria memórias a partir de logs de conversa.
Glyph — Scanner de segurança MCP e proteção de runtime.

🏗️ Como Funciona

O pipeline de 4 camadas:

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

O que cada camada captura:

Tipo de consulta	Vetor	Palavra-chave	Grafo	Metadados
Conceitual ("melhorar tratamento de erros")	✅	—	—	—
Correspondência exata ("ERR_CONNECTION_REFUSED")	—	✅	—	—
Conceitos conectados	—	—	✅	—
Filtrada ("#python status:active")	—	—	—	✅
Combinada ("gerenciamento de estado React")	✅	✅	✅	✅

✨ Recursos

ONNX Runtime — 184ms de inicialização a frio, 3ms em cache. Sem PyTorch, sem GPU
Fusão em quatro camadas — similaridade vetorial FAISS + SQLite FTS5 (BM25) + grafo de conhecimento + filtragem de metadados, mesclados por fusão de classificação recíproca
Reordenação por cross-encoder — reordenador TinyBERT via ONNX Runtime — incluído na instalação base, sem necessidade de PyTorch. Baixa modelo de ~17MB no primeiro uso
Atualizações incrementais de grafo — rastreamento de proveniência centrado em arquivos detecta o que mudou e reconstrói apenas nós/arestas afetados. Exclusões em cascata mantêm consistência em todos os armazenamentos (vetor, grafo, metadados). Suporte a múltiplas fontes com proveniência isolada por fonte
Servidor MCP — Cinco ferramentas (search, index, add_document, health, list_sources) para Claude, Cursor, Windsurf
Daemon de busca — servidor de socket Unix mantém modelo ONNX + índice FAISS aquecidos entre consultas
Grafo de conhecimento — analisadores constroem arestas de entidade, temporal, tópico e links explícitos a partir de markdown. GLiNER NER opcional. 418 arquivos em 2,1s
Fragmentação inteligente — divisão ciente de cabeçalhos preserva a estrutura do documento e o contexto pai
Expansão de consulta — registro de acrônimos, variantes de maiúsculas/espaçamento, tokenização ciente de sublinhados
Roda em qualquer lugar — somente CPU, 8GB de RAM, sem chaves de API, sem serviços externos

🤖 Servidor MCP

O VelociRAG expõe um servidor de Model Context Protocol para integração perfeita com agentes:

Ferramentas disponíveis:

search — busca por fusão em 4 camadas com reordenação
index — adiciona documentos à base de conhecimento
add_document — insere documento único
health — diagnóstico do sistema
list_sources — mostra fontes de documentos indexados

O processo do servidor MCP permanece ativo entre consultas, então os modelos carregam uma vez e cada busca subsequente é aquecida. Funciona com qualquer cliente compatível com MCP.

🐍 API Python

Busca unificada completa em 4 camadas:

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'}
)

Busca 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)

Atualizações incrementais de grafo:

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

💻 Referência da 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]

Opções:

--no-graph — pular construção do grafo de conhecimento
--no-metadata — pular extração de metadados
--full-graph — construir grafo COM arestas de similaridade semântica (~2GB de RAM extra)
--source NAME — rótulo para isolamento de proveniência multi-fonte
--force — limpar e reconstruir do zero
--gliner — usar GLiNER para extração de entidades (requer pip install "velocirag[ner]")

📊 Desempenho

Benchmarks reais em ByteByteGo/system-design-101 (418 arquivos, 1.001 fragmentos):

Métrica	Valor
Indexação (418 arquivos)	13,6s
Busca (aquecida, 5 resultados)	35–90ms
Construção do grafo (leve)	2,1s → 2.397 nós, 8.717 arestas
Atualização incremental (1 arquivo)	1,3s
Reordenador	Cross-encoder TinyBERT via ONNX
Tamanho da instalação	~80MB (sem PyTorch)
Uso de RAM	<1GB com todos os modelos carregados

Implantação em produção (6.300+ fragmentos, 3 fontes, 950 arquivos):

Métrica	Valor
Busca completa (aquecida)	16ms média, 2ms mín
Busca completa (primeira execução)	22ms média, 4ms mín
Busca P50 / P95	17ms / 55ms
Taxa de acerto (benchmark de 100 consultas)	99/100
Grafo	3.125 nós, 132.320 arestas
Reordenador	Cross-encoder TinyBERT via ONNX
RAM	<1GB com todos os modelos carregados

⚙️ Configuração

Variável de Ambiente	Padrão	Descrição
`VELOCIRAG_DB`	`./.velocirag`	Diretório do banco de dados
`VELOCIRAG_SOCKET`	`/tmp/velocirag-daemon.sock`	Caminho do socket do daemon
`NO_COLOR`	—	Desabilitar saída colorida

Dependências (todas incluídas na instalação base):

onnxruntime — inferência ONNX (embedder + reordenador)
tokenizers + huggingface-hub — carregamento de modelos
faiss-cpu — busca por similaridade vetorial
networkx + scikit-learn — grafo de conhecimento + agrupamento de tópicos
numpy, click, pyyaml, python-frontmatter

Extras opcionais:

pip install "velocirag[mcp]" — servidor MCP (adiciona fastmcp)
pip install "velocirag[ner]" — extração de entidades GLiNER (adiciona gliner, requer PyTorch)

📚 Referências

O VelociRAG se baseia nestes trabalhos fundamentais:

Fusão Central e Recuperação

Fusão de Classificação Recíproca — Cormack, G. V., Clarke, C. L. A., & Büttcher, S. (2009). "Reciprocal Rank Fusion outperforms Condorcet and individual Rank Learning Methods." SIGIR '09.
Algoritmo central de fusão para mesclar resultados entre camadas de recuperação.

BM25 — Robertson, S. E., Walker, S., Jones, S., Hancock-Beaulieu, M., & Gatford, M. (1994). "Okapi at TREC-3." TREC-3.
Fundação de busca por palavras-chave via SQLite FTS5.

Embeddings e IR Neural

Sentence-BERT — Reimers, N., & Gurevych, I. (2019). "Sentence-BERT: Sentence Embeddings using Siamese BERT-Networks." EMNLP 2019. paper
Arquitetura de embeddings densos 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
Destilação eficiente de transformers para modelos de embeddings em produção.

Reordenação e Modelos Neurais

Reordenação por Cross-Encoder — Nogueira, R., & Cho, K. (2019). "Passage Re-ranking with BERT." arXiv:1901.04085. paper
Reordenação por atenção cruzada com TinyBERT no MS MARCO.

TinyBERT — Jiao, X., et al. (2020). "TinyBERT: Distilling BERT for Natural Language Understanding." Findings of EMNLP 2020. paper
BERT comprimido para inferência rápida de reordenação.

Busca Vetorial e Sistemas

FAISS — Johnson, J., Douze, M., & Jégou, H. (2019). "Billion-scale similarity search with GPUs." IEEE Transactions on Big Data. paper
Mecanismo de busca por similaridade vetorial de alto desempenho.

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 extração de entidades em grafo de conhecimento (dependência opcional).

📄 Licença

MIT — Use em qualquer lugar, construa qualquer coisa.

Precisa de ajuda com integração de agentes? Consulte AGENTS.md para contexto de projeto legível por máquina.

Construído para agentes que pensam rápido e lembram mais rápido.