quillrag

Eine Datei. Null Abhängigkeiten. Bereit, bevor dein Editor fertig geladen hat.

Eine lokale RAG-Engine in einer einzigen statischen Binärdatei – MiniLM-Embeddings einkompiliert, hybrides Dense- + BM25-Retrieval, MCP-nativ. Kein Node, kein Python, kein Modell-Download bei der ersten Abfrage.

Warum quillrag

Related MCP server: mcp-fts5-starter

Schnellstart

# 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"

Oder binde es direkt in Claude Desktop / Cursor ein und lass die KI deine Notizen mitten im Gespräch durchsuchen – Konfiguration unten.

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

Warum es schnell ist

Das Embedding-Modell ist lazy: Der MCP-Handshake und rag_status berühren es nie, daher sehen Editoren einen sofort bereiten Server.

Installation

Lade ein vorgefertigtes Archiv aus dem neuesten Release herunter – Windows x86_64, macOS Apple Silicon und Linux x86_64 werden von CI bei jedem Versions-Tag gebaut:

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

Oder aus dem Quellcode bauen:

cargo install --path .

Von CI verwendete Cross-Compile-Ziele: x86_64-unknown-linux-gnu, aarch64-apple-darwin, x86_64-pc-windows-msvc.

In deinen Editor einbinden

Claude Desktop / Cursor / jeder MCP-Client:

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

Oder führe einfach ./quillrag serve aus und richte einen beliebigen stdio-Client darauf aus.

Tools

CLI-Äquivalente (gleiche Engine):

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

Design

• Embeddings: candle (reines Rust) mit sentence-transformers/all-MiniLM-L6-v2 – maskiertes Mean-Pooling + L2-Norm, numerisch übereinstimmend mit sentence-transformers auf der CPU. Die Gewichte werden per include_bytes! in die Binärdatei eingebettet und beim ersten Laden aus einem materialisierten Cache gemappt (mmap).

• Speicher: eine einzige redb-Datei – Chunk-Text, rohe f32-Vektoren, Dokument-Metadaten. Atomare Commits; absturzsicher.

• Keywords: tantivy BM25-Sidecar-Index, der bei jedem Indizierungslauf neu aufgebaut wird (günstig bei kleinen Datenmengen).

• Fusion: Reciprocal Rank Fusion (Σ 1/(60+rank)) – keine Score-Skalierungs-Anpassung, robust gegenüber heterogenen Rankings.

• Chunking: absatzbasiert mit 1000-Zeichen-Limit und 120-Zeichen-Überlappung; überlange Absätze werden an Satzgrenzen hart geteilt.

Standardmäßig indizierte Dateitypen

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 – erweitern mit -e ext1,ext2 / "extensions": [...].

Ignorierte Verzeichnisse: jedes Dot-Verzeichnis (.git .obsidian .vscode …) sowie node_modules target dist build venv __pycache__ vendor.

Datenschutz & Ressourcenbedarf

Alles läuft lokal: Embeddings, Speicher, Suche. Nichts verlässt die Maschine – es gibt nach der Installation überhaupt keinen Netzwerk-Codepfad.

Binärdatei ≈ 105 MB (das Modell lebt darin). RAM ≈ 120 MB resident im Leerlauf, mit Spitzen von ~250 MB während des Batch-Embeddings.

Skalierung & Grenzen

quillrag speichert alles in einer einzigen redb-Datei und führt das Dense-Retrieval als exakten, single-threaded linearen Scan über alle Vektoren aus – noch kein ANN-Index. Dadurch ist die relevante Grenze Abfragelatenz, nicht Speicher. Der Speicher skaliert auf Millionen von Chunks; die Abrufgeschwindigkeit ist O(N) pro Abfrage.

Verifiziert an einem Korpus von 1K Chunks (5/5 Tests inklusive echtem JSON-RPC-over-stdio-E2E); Werte über 1K sind aus den O(N)-Kosten des Dense-Scans hochgerechnet, nicht gemessen. Eine synthetische Skalierungssonde (src/bin/quillbench.rs) existiert, um die Kurve auf deiner eigenen Hardware zu messen – führe cargo build --release && ./target/release/quillbench aus.

Was das in der Praxis bedeutet:

• Sehr gut geeignet: persönliche/lokale Wissensdatenbanken, Projektdokumentationen, Notizen, Code – bis zu einigen Zehntausend Chunks, wo Latenzen von unter einer Sekunde bis interaktiv gelten.

• Außerhalb des Optimalbereichs: Korpora mit mehreren hunderttausend Chunks und mehr, wo du interaktive (<200 ms) Suche benötigst – dann brauchst du einen ANN-Index (siehe Roadmap).

So schneidet es im Vergleich zu gängigen Alternativen auf der Relevanz-Achse ab:

• Nur-Embedding (z. B. rohes FAISS-Flat / einfacher Vektor-Store): gleiche all-MiniLM-L6-v2-Obergrenze wie quillrags Dense-Pfad, aber quillrag fügt BM25 + RRF-Fusion hinzu, die bei keyword-lastigen Abfragen (Fehlercodes, IDs, exakte Tokens) gewinnt. quillrag hat keinen Reranker und keine Metadatenfilterung, die llama-index zusätzlich bietet.

• llama-index lokale Backends: funktional ähnliches Hybrid-Retrieval (BM25 + Vektor + RRF). quillrag tauscht llama-index' umfangreiches Reranking/Parent-Child-Chunking/Query-Expansion gegen eine einzige Binärdatei ohne Abhängigkeiten und sofortigen Start. Die Relevanz auf einem Standarddatensatz (BEIR/MS MARCO) ist noch nicht benchmarkt – siehe das offene Issue, das ANN + eine Relevanz-Baseline verfolgt.

Roadmap

quillrag ist heute bewusst minimal. Der große Durchbruch ist ein Approximate-Nearest-Neighbor-Index:

• ANN (HNSW / IVF) über die Dense-Vektoren – verwandelt den O(N)-Scan in eine ANN-Suche im Sub-Millisekundenbereich und hebt die interaktive Grenze von ~10K auf Millionen von Chunks auf einer einzigen Maschine.

• Quantisierung (PQ / SQ) – reduziert den Vektor-RAM von 4 Bytes/Dim auf ~1 Byte/Dim, sodass 1M Chunks ≈ 380 MB statt 1,5 GB benötigen.

• Multithreaded-Scan – parallelisiert den aktuellen exakten Pfad als Übergangslösung.

• Reranker-Hook – optionales Cross-Encoder-Reranking der fusionierten Top-k.

• Relevanz-Benchmark – BEIR / MS MARCO nDCG@10 vs. llama-index-Baselines.

Verfolge die ANN-Arbeit hier: issue #1 — "ANN index for <1M chunks."

FAQ

Ist es wirklich eine Datei? Ja. Die MiniLM-Gewichte + Tokenizer sind per include_bytes! einkompiliert. Kein npm install, kein Python, kein Modell-Download bei der ersten Abfrage. Die Binärdatei ist ~105 MB groß, weil das Modell darin lebt.

Warum ist der Start so schnell? Das Embedding-Modell ist lazy. Der MCP-Handshake und rag_status berühren es nie – Editoren sehen einen bereiten Server in ~20 ms. Das Modell lädt nur beim ersten rag_search / rag_index (~300 ms einmalig).

Was ist der größte Korpus, den es verarbeitet? Verifiziert bei 1K Chunks (~25 ms/Abfrage). Die Architektur skaliert auf Millionen gespeicherter Chunks; interaktive Suche gilt heute bis zu einigen Zehntausend, und ein ANN-Index (Roadmap) erweitert das auf 1M+.

Wie unterscheidet sich das von llama-index? Ähnliche Qualität der hybriden Suche, aber quillrag ist eine einzige statische Binärdatei ohne Laufzeit-/Abhängigkeits-Fußabdruck und mit sofortigem Start. llama-index bietet Reranker, ausgefeiltes Chunking und Query-Expansion, die quillrag noch nicht hat.

Welche Dateitypen werden indiziert? 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 – erweitern mit -e.

Sendet es Daten nach Hause? Nein. Es gibt nach der Installation keinen Netzwerk-Codepfad.

Changelog

• v0.1.3 – MCP-Toolbeschreibungen für Klarheit, Parametersemantik und Verhaltenstransparenz neu geschrieben (Read-only/destruktive Flags, Nutzungshinweise); server.json im Repo für die MCP-Registry-Veröffentlichung enthalten.

• v0.1.2 – überspringt beim Indizieren alle Dot-Verzeichnisse (.obsidian-Plugin-Konfigurationen verschmutzen die Ergebnisse nicht mehr); erstes vollautomatisiertes CI-Release für 3 Plattformen. Hinweis zum Upgrade: quillrag clear einmal ausführen und neu indizieren.

• v0.1.1 – CI-gebauten Release-Artefakte für linux/macos/windows mit Prüfsummen.

• v0.1.0 – erste öffentliche Veröffentlichung; umbenannt von pocketrag.

Entwicklung

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

Lizenz: MIT