QMD: Lokale Hybrid-Suche für Markdown — und warum das deine Token-Kosten um 95% senkt

Das Problem kennt jeder, der mit KI-Assistenten arbeitet: Du willst aus deinen eigenen Notizen, Meeting-Protokollen oder einer Dokumentation etwas abrufen — und stopfst alles in den Kontext. Die Folge: Explodierende Token-Kosten, langsamere Antworten, und irgendwann läuft der Context-Window voll.

QMD löst genau das. Nicht mit einer Cloud-API, sondern vollständig lokal.

Was ist QMD?

QMD (Query Markup Documents) ist ein Mini-Suchmotor für deine Markdown-Dateien — entwickelt von Tobi Lütke ¹, unter anderem bekannt als Shopify-Gründer. Das Projekt entstand aus der Praxis: Best Practices aus Gesprächen mit Search-&-Retrieval-Teams, kondensiert in ein CLI-Tool, das einfach funktioniert.

Der Ansatz: Statt Dokumente blind in den LLM-Prompt zu laden, fragst du gezielt ab — und bekommst nur das Relevante zurück. Das spart laut Community-Berichten 95%+ der Token-Kosten ².

Die Hybrid-Such-Pipeline

QMD kombiniert drei Techniken, die normalerweise getrennt eingesetzt werden ¹:

User Query
    │
    ├─── BM25 Volltextsuche (SQLite FTS5, schnell, exakte Matches)
    └─── Vektorsemantische Suche (gemma-300M lokal via node-llama-cpp)
         │
         └─── Query Expansion (fine-tuned 1.7B Modell generiert Varianten)
              │
              └─── RRF Fusion (Reciprocal Rank Fusion, Top 30)
                   │
                   └─── LLM Reranking (qwen3-reranker-0.6B, lokal)
                        │
                        └─── Position-Aware Blending → Finale Ergebnisse

Drei Suchmodi:

qmd search "keyword" — Reines BM25, blitzschnell
qmd vsearch "frage" — Rein semantisch
qmd query "frage" — Hybrid + Query Expansion + Reranking (beste Qualität)

Komplett lokal, keine Cloud

QMD lädt beim ersten Start drei GGUF-Modelle automatisch herunter ¹:

Modell	Zweck	Grösse
`gemma-300M-Q8_0`	Vektor-Embeddings	~300 MB
`qwen3-reranker-0.6b-q8_0`	Re-Ranking	~640 MB
`qmd-query-expansion-1.7B-q4_k_m`	Query Expansion (fine-tuned)	~1.1 GB

Alle Modelle laufen via node-llama-cpp direkt auf dem Gerät — kein API-Key, kein Datentransfer, GPU-Beschleunigung wo verfügbar. Index landet in ~/.cache/qmd/index.sqlite.

Installation und Setup

# Via npm oder Bun
npm install -g @tobilu/qmd
# oder
bun install -g @tobilu/qmd

# Collections anlegen
qmd collection add ~/notes --name notes
qmd collection add ~/Documents/meetings --name meetings
qmd collection add ~/work/docs --name docs

# Kontext hinzufügen (wichtig für LLM-Qualität!)
qmd context add qmd://notes "Personal notes and ideas"
qmd context add qmd://meetings "Meeting transcripts and notes"

# Embeddings generieren
qmd embed

# Suchen
qmd query "quarterly planning process"

Der Context-Mechanismus ist dabei unterschätzt: Jeder Collection kann eine Beschreibung mitgegeben werden, die bei den Suchergebnissen zurückgeliefert wird — das hilft LLMs enorm bei der kontextuellen Auswahl ¹.

MCP-Integration: Direkt für Claude Code und Cursor

QMD bringt einen MCP-Server mit — sowohl via stdio als auch via HTTP-Transport für shared Deployments ¹:

// ~/.claude/settings.json
{
  "mcpServers": {
    "qmd": {
      "command": "qmd",
      "args": ["mcp"]
    }
  }
}

Oder über Claude Marketplace direkt:

claude marketplace add tobi/qmd

Damit hat der Agent Zugriff auf diese Tools:

qmd_search — BM25 Keyword-Suche
qmd_vector_search — Semantische Suche
qmd_deep_search — Hybrid + Reranking
qmd_get — Dokument by Path oder DocID
qmd_multi_get — Mehrere Docs via Glob-Pattern
qmd_status — Index-Status

Für geteilte Deployments (z.B. mehrere Agents greifen auf denselben Index zu):

qmd mcp --http --daemon  # HTTP-Server starten
# Modelle bleiben im VRAM geladen, 5min Idle-Timeout für Kontexte

Für agentic Workflows optimiert

QMD's Output-Formate wurden explizit für LLMs designt ¹:

# Strukturierte JSON-Ausgabe für Agents
qmd search "authentication" --json -n 10

# Nur Dateipfade (ideal als Tool-Output)
qmd query "error handling" --all --files --min-score 0.4

# Vollständige Dokumente
qmd get "docs/api-reference.md" --full

Das --files-Format liefert: docid,score,filepath,context — genau das, was ein Agent braucht, um gezielt weiterzumachen.

Warum das wichtig ist

Das klassische Problem bei RAG: Entweder lädst du zu viel in den Kontext (teuer, langsam), oder du verfehlst das Relevante (billig, aber nutzlos). QMD trifft den Sweet Spot durch die Kombination aus:

Exakter Treffsicherheit (BM25 für genaue Begriffe)
Semantischem Verständnis (Vektorsuche für Konzepte)
Lokaler Kontrolle (keine Cloud-Abhängigkeit, kein Datenschutzproblem)

Der Hacker News-Thread ³ zeigt die Community-Reaktion: Obsidian-Nutzer mit hunderten Notizen, Teams mit internen Docs, Entwickler die ihre Meeting-Transcripts durchsuchbar machen wollen — QMD trifft einen echten Nerv.

Fazit

QMD ist kein Produkt mit Landing Page und Pricing Tiers — es ist ein gut durchdachtes Open-Source-CLI-Tool, das ein reales Problem löst. Für alle, die viel in Markdown schreiben und mit LLMs arbeiten, ist es einen ernsthaften Blick wert.

Besonders für agentic Setups mit Claude Code oder Cursor: Einmal konfiguriert, hat der Agent sofort Zugriff auf alles, was du je notiert hast — ohne auch nur einen unnötigen Token zu verschwenden.

Quellen:

¹ QMD GitHub Repository (tobi/qmd) — Architektur, Dokumentation, MCP-Integration: github.com/tobi/qmd

² "QMD: Local hybrid search engine for Markdown that cuts token usage by 95%+" — Medium/Coding Nexus: medium.com/coding-nexus/qmd-local-hybrid-search...

³ Hacker News Discussion "QMD - Quick Markdown Search": news.ycombinator.com/item?id=46689289