quillrag

Un solo archivo. Cero dependencias. Listo antes de que tu editor termine de cargar.

Un motor RAG local en un único binario estático: embeddings MiniLM compilados dentro, recuperación híbrida densa + BM25, nativo para MCP. Sin Node, sin Python, sin descarga de modelos en la primera consulta.

Por qué quillrag

Related MCP server: mcp-fts5-starter

Inicio rápido

# 1. grab a prebuilt binary (or cargo install --path .)
gh release download --repo Ayush-yadav11/quillrag -p '*linux*'
tar xzf quillrag-x86_64-linux.tar.gz && chmod +x quillrag

# 2. point it at any folder of notes/docs/code
./quillrag index ~/notes          # incremental walk

# 3. ask it something
./quillrag search "how does backpropagation work"

O conéctalo directamente a Claude Desktop / Cursor y deja que la IA busque en tus notas a mitad de conversación — configuración abajo.

$ ./quillrag serve --data-dir ~/.local/share/quillrag
2026-08-26 INFO quillrag 0.1.2 ready in 41ms      <- handshake-ready before the model loads

Por qué es rápido

El modelo de embeddings es perezoso: el handshake de MCP y rag_status nunca lo tocan, así que los editores ven un servidor instantáneo.

Instalación

Descarga un archivo precompilado desde la última versión — Windows x86_64, macOS Apple Silicon y Linux x86_64 son compilados por CI en cada etiqueta de versión:

# linux/macOS example: fetch + extract the latest release
gh release download --repo Ayush-yadav11/quillrag -p '*linux*' | tar xz
chmod +x quillrag && ./quillrag --version

O compila desde el código fuente:

cargo install --path .

Objetivos de compilación cruzada usados por CI: x86_64-unknown-linux-gnu, aarch64-apple-darwin, x86_64-pc-windows-msvc.

Conéctalo a tu editor

Claude Desktop / Cursor / cualquier cliente MCP:

{
  "mcpServers": {
    "quillrag": {
      "command": "/usr/local/bin/quillrag",
      "args": ["serve"],
      "env": { "QUILLRAG_DATA": "~/.local/share/quillrag" }
    }
  }
}

O simplemente ejecuta ./quillrag serve y apunta cualquier cliente stdio hacia él.

Herramientas

Equivalentes CLI (mismo motor):

quillrag index ~/notes              # incremental walk
quillrag search "auth flow" -k 5    # one-shot search
quillrag status                     # stats
quillrag clear                      # wipe

Diseño

• Embeddings: candle (Rust puro) ejecutando sentence-transformers/all-MiniLM-L6-v2 — pooling de media enmascarada + norma L2, coincidiendo numéricamente con sentence-transformers en CPU. Los pesos se incluyen con include_bytes! en el binario y se mapean con mmap desde una caché materializada en la primera carga.

• Almacenamiento: un único archivo redb — texto de fragmentos, vectores f32 crudos, metadatos de documentos. Commits atómicos; seguro ante fallos.

• Palabras clave: índice secundario BM25 de tantivy reconstruido en cada pasada de indexación (barato a escala de bolsillo).

• Fusión: Reciprocal Rank Fusion (Σ 1/(60+rank)) — sin ajuste de escala de puntuaciones, robusto ante rankings heterogéneos.

• Fragmentación: primero por párrafos con límite de 1000 caracteres y solapamiento de 120; los párrafos demasiado grandes se dividen en límites de oración.

Tipos de archivo indexados por defecto

md markdown txt rst json yaml yml toml csv tsv html htm xml log rs py js jsx ts tsx go c h cpp hpp java rb sh bash zsh sql proto graphql dockerfile makefile ini cfg conf env — amplía con -e ext1,ext2 / "extensions": [...].

Directorios ignorados: todos los directorios con punto (.git .obsidian .vscode …) más node_modules target dist build venv __pycache__ vendor.

Privacidad y huella

Todo se ejecuta localmente: embeddings, almacenamiento, búsqueda. Nada sale de la máquina — no hay ninguna ruta de código de red después de la instalación.

Binario ≈ 105 MB (el modelo vive dentro). RAM ≈ 120 MB residentes en reposo, subiendo a ~250 MB durante el embedding por lotes.

Escalado y límites

quillrag almacena todo en un único archivo redb y ejecuta la recuperación densa como un escaneo lineal exacto de un solo hilo sobre todos los vectores — aún sin índice ANN. Eso hace que el límite relevante sea la latencia de consulta, no el almacenamiento. El almacenamiento escala a millones de fragmentos; la velocidad de recuperación es O(N) por consulta.

Verificado en un corpus de 1K fragmentos (5/5 pruebas incluyendo e2e real de JSON-RPC sobre stdio); las cifras por encima de 1K son extrapoladas del costo del escaneo denso O(N), no medidas. Existe una sonda de escala sintética (src/bin/quillbench.rs) para medir la curva en tu propio hardware — ejecuta cargo build --release && ./target/release/quillbench.

Qué significa esto en la práctica:

• Gran ajuste: bases de conocimiento personales/locales, documentación de proyectos, notas, código — hasta decenas de miles de fragmentos donde la latencia de sub-segundo a interactiva se mantiene.

• Fuera del punto óptimo: corpus de cientos de miles o más donde necesitas recuperación interactiva (<200 ms) — querrás un índice ANN (ver Roadmap).

Cómo se compara con alternativas comunes en el eje de relevancia:

• Solo embeddings (p. ej., FAISS flat crudo / almacén de vectores simple): el mismo techo de all-MiniLM-L6-v2 que la ruta densa de quillrag, pero quillrag añade fusión BM25 + RRF, que gana en consultas con muchas palabras clave (códigos de error, IDs, tokens exactos). quillrag no tiene reranker ni filtrado de metadatos, que llama-index ofrece además.

• Backends locales de llama-index: recuperación híbrida funcionalmente similar (BM25 + vector + RRF). quillrag cambia el rico reranking/fragmentación padre-hijo/expansión de consultas de llama-index por un binario único sin dependencias y arranque instantáneo. La relevancia en un conjunto de datos estándar (BEIR/MS MARCO) aún no está comparada — ver el issue abierto que rastrea ANN + una línea base de relevancia.

Roadmap

quillrag es deliberadamente mínimo hoy. El gran desbloqueo es un índice de vecinos más cercanos aproximados:

• ANN (HNSW / IVF) sobre los vectores densos — convierte el escaneo O(N) en búsqueda ANN de sub-milisegundo, empujando el techo interactivo de ~10K a millones de fragmentos en una sola máquina.

• Cuantización (PQ / SQ) — reduce la RAM de vectores de 4 bytes/dim a ~1 byte/dim, así que 1M de fragmentos ≈ 380 MB en lugar de 1.5 GB.

• Escaneo multi-hilo — paraleliza la ruta exacta actual como solución provisional.

• Gancho de reranker — rerank opcional con cross-encoder del top-k fusionado.

• Benchmark de relevancia — BEIR / MS MARCO nDCG@10 frente a líneas base de llama-index.

Sigue el trabajo de ANN aquí: issue #1 — "Índice ANN para <1M de fragmentos."

FAQ

¿Es realmente un solo archivo? Sí. Los pesos de MiniLM + el tokenizador están compilados dentro vía include_bytes!. Sin npm install, sin Python, sin descarga de modelos en la primera consulta. El binario es ~105 MB porque el modelo vive dentro.

¿Por qué el arranque es tan rápido? El modelo de embeddings es perezoso. El handshake de MCP y rag_status nunca lo tocan — los editores ven un servidor listo en ~20 ms. El modelo solo se carga en la primera rag_search / rag_index (~300 ms una sola vez).

¿Cuál es el corpus más grande que maneja? Verificado en 1K fragmentos (~25 ms/consulta). La arquitectura escala a millones de fragmentos almacenados; la recuperación interactiva se mantiene hasta decenas de miles hoy, y un índice ANN (Roadmap) lo extiende a 1M+.

¿En qué se diferencia de llama-index? Calidad de recuperación híbrida similar, pero quillrag es un binario estático único sin huella de dependencias en tiempo de ejecución y arranque instantáneo. llama-index añade rerankers, fragmentación sofisticada y expansión de consultas que quillrag aún no tiene.

¿Qué tipos de archivo se indexan? md markdown txt rst json yaml yml toml csv tsv html htm xml log rs py js jsx ts tsx go c h cpp hpp java rb sh bash zsh sql proto graphql dockerfile makefile ini cfg conf env — amplía con -e.

¿Hace llamadas a casa? No. No hay ninguna ruta de código de red después de la instalación.

Historial de cambios

• v0.1.3 — Descripciones de herramientas MCP reescritas para claridad, semántica de parámetros y transparencia de comportamiento (banderas de solo lectura/destructivas, guía de uso); server.json incluido en el repositorio para publicación en el Registro MCP.

• v0.1.2 — omitir todos los directorios con punto al indexar (las configuraciones de plugins de .obsidian ya no contaminan los resultados); primera versión CI totalmente automatizada para 3 plataformas. Nota de actualización: ejecuta quillrag clear una vez y re-indexa.

• v0.1.1 — Artefactos de versión compilados por CI para linux/macos/windows con sumas de verificación.

• v0.1.0 — versión pública inicial; renombrado desde pocketrag.

Desarrollo

cargo test                    # unit + end-to-end (spawns real stdio servers)
cargo run -- serve            # dev server
RUST_LOG=debug cargo run ...  # verbose logs (stderr only)

Licencia: MIT