QMD: lokaal semantisch zoeken met GGUF-modellen

Definitie

QMD (“Quick Markdown Search”) is een lokale semantische search engine van Tobi Lutke (Shopify-oprichter). Draait volledig op de Mac via Metal GPU, zonder cloud-afhankelijkheden. Geintegreerd in Vault/Atelier als optionele zoeklaag bovenop FTS5.

Context

FTS5 (SQLite full-text search) vindt alleen documenten op basis van keywords. QMD voegt betekenisgebaseerd zoeken toe: een query als “foto’s bij avondlicht” vindt ook documenten die “schemerfotografie” of “golden hour” bevatten. In Atelier vormt QMD de semantische laag van hybrid search (FTS5 + QMD, met QMD-resultaten 10x zwaarder gewogen).

Kernpunten

Drie modellen (totaal ~2.1GB)

Model	Grootte	Functie
qmd-query-expansion-1.7B	1.2 GB	Breidt query uit met synoniemen, HyDE (hypothetical document embeddings)
embeddinggemma-300M	314 MB	Genereert vector embeddings per chunk
Qwen3-Reranker-0.6B	610 MB	Herrankt resultaten op daadwerkelijke relevantie

Modellen staan in ~/.cache/qmd/models/ en worden automatisch gedownload bij eerste gebruik. Draaien op Metal GPU (Apple Silicon).

Drie zoekmodi

• qmd search "query" — BM25 keyword-only (geen LLM)
• qmd vsearch "query" — vector similarity-only
• qmd query "query" — hybrid: BM25 + vector + query expansion + reranking (aanbevolen)

Collections

qmd collection add /pad/naar/project --name naam    # indexeer markdown-bestanden
qmd embed                                            # genereer embeddings
qmd update                                           # herindexeer na wijzigingen
qmd status                                           # gezondheidscheck

Bun sqlite-vec probleem

QMD draait standaard op Bun als $BUN_INSTALL gezet is. Bun’s ingebouwde SQLite ondersteunt loadExtension() niet voor sqlite-vec, waardoor vector-operaties (embed, vsearch, query) falen. Node met better-sqlite3 werkt wel.

Workaround: wrapper in ~/.bun/bin/qmd:

#!/bin/sh
exec env BUN_INSTALL="" /opt/homebrew/bin/qmd "$@"

Dit forceert het Node-pad in QMD’s launcher (db.js kiest better-sqlite3 als isBun false is).

Integratie met Vault

De QMDProvider (/Atelier/vault/src/providers/qmd.ts) biedt:

• init() — check of qmd CLI beschikbaar is
• search(query, limit, mode) — zoek via qmd CLI
• exportTexts(db, vaultRoot) — exporteer asset-teksten voor indexering
• health() — statusrapportage

Vault’s vault.search tool combineert FTS5 + QMD met gewogen scoring.

Vergelijking met cloud-embeddings (OB1-aanpak)

	QMD (lokaal)	pgvector + OpenAI (cloud)
Pipeline	3-staps: expansion → embedding → reranking	1-stap: embedding
Privacy	Niets verlaat de Mac	Content naar cloud API
Kosten	Gratis na 2.1GB download	Pay-per-use (~$5 credits)
Snelheid	~8s per query (expansion + embed + rerank)	Sneller per query, maar netwerk-latency
Offline	Werkt zonder internet	Vereist internet
Kwaliteit	HyDE + reranking geeft nauwkeurigere resultaten	Alleen cosine similarity

Verbanden

• Zie ook: wiki-vault-mcp-architectuur — Vault MCP-server waarvan QMD een provider is
• Zie ook: wiki-atelier-architectuur — bredere Atelier-architectuur
• Gerelateerd project: Atelier (/Users/jvdbreemen/Claude/projects/Atelier/)

Bronnen

• QMD GitHub: tobil/qmd (Hugging Face models)
• Atelier QMDProvider: /Atelier/vault/src/providers/qmd.ts
• Atelier vault-search: /Atelier/vault/src/tools/vault-search.ts

Sessie-herkomst

• raw-sessie-2026-04-24-ai-skill-ecosysteem-qmd-designmd