QMD: hoe een Shopify-tool mijn hele workflow veranderde

Je kent het probleem. Je bouwt software, je hebt documentatie, notities, changelogs, bug reports, contactgegevens, project plannen. Alles in markdown, netjes georganiseerd. En toch: als je Claude Code iets vraagt over een bug van twee weken geleden, weet het van niks.

Context windows zijn eindig. Zelfs met 200K tokens kun je niet alles erin proppen. En grep? Grep geeft je regels tekst zonder context. Zoek op "deploy error" en je krijgt 400 resultaten waar je zelf doorheen moet spitten. Dat is geen workflow, dat is archeologie.

QMD lost dit op. Niet met een cloud service, niet met een dure API, maar lokaal op je eigen machine.

Wat is QMD

QMD (Quick Markdown Search) is een lokale hybrid search engine voor markdown bestanden, gebouwd door Tobi Lutke, CEO van Shopify. Open source, gratis, en verrassend krachtig voor iets dat volledig op je laptop draait.

Tobi is niet zomaar iemand die een side project heeft. De man runt een bedrijf van $200+ miljard en zegt zelf: "QMD is one of my finest tools, I use it every day." Als de CEO van Shopify dagelijks een tool gebruikt die hij zelf bouwde, is dat een signaal dat het werkt.

QMD combineert drie zoektechnieken in een hybride aanpak: BM25 keyword search, vector embeddings voor semantisch begrip, en LLM reranking voor relevantie. Alles draait lokaal via node-llama-cpp met GGUF modellen. Geen data die je machine verlaat, geen API keys, geen maandelijkse kosten.

Hoe het werkt: drie lagen zoeken

De kracht van QMD zit in de combinatie van drie zoekstrategieen die elk hun eigen sterke punten hebben.

BM25 (lexicale search) is de snelste laag. Klassieke keyword matching met slimme scoring. Zoek je op "deploy error staging", dan vindt BM25 documenten die precies die woorden bevatten. Snel, deterministisch, en ideaal voor exacte termen. Dit is wat je 80% van de tijd nodig hebt.

Vector embeddings (semantische search) begrijpen betekenis. Zoek je op "problemen met uitrollen naar acceptatie", dan vindt de vector search ook documenten die "deploy issues on staging" bevatten, omdat de betekenis overeenkomt. De embeddings worden lokaal gegenereerd en opgeslagen, dus na de eerste indexering is het razendsnel.

LLM reranking is de derde laag. Een lokaal LLM beoordeelt de resultaten van BM25 en vector search en rankt ze op relevantie. Dit filtert ruis eruit en zorgt dat het meest relevante document bovenaan staat.

Daarnaast heeft QMD AST-aware chunking voor code bestanden. Het snapt dat een functie een logische eenheid is en splitst niet halverwege een method body. Dat klinkt als een detail, maar het maakt het verschil tussen bruikbare en onbruikbare code snippets in je zoekresultaten.

Mijn setup: 270+ documenten

Ik gebruik QMD dagelijks met meer dan 270 geindexeerde documenten, verdeeld over vier collecties:

• vault (133 docs): mijn persoonlijke kennisbank in Obsidian. Project plannen, meeting notes, ideeën, bugs, contactgegevens, deals, todos
• code-reviews (84 docs): CodeRabbit code review reports per pull request
• changelogs (15 docs): CHANGELOG.md bestanden van al mijn actieve Laravel projecten
• jordan (38 docs): documentatie voor een specifiek project

QMD draait als MCP server en is direct beschikbaar in mijn James framework. Claude Code kan zoeken, ophalen, en combineren zonder dat ik handmatig bestanden open of kopieer.

Concrete workflow voorbeelden

De theorie klinkt mooi, maar de echte waarde zit in dagelijks gebruik. Hier zijn scenario's die ik wekelijks tegenkom.

Bug onderzoek. Een klant meldt een probleem. Ik vraag Claude: "Zoek in de vault naar eerdere bugs met factuurgeneratie." QMD doorzoekt mijn Obsidian vault, vindt drie eerdere rapportages, en Claude kan direct de context meenemen. Geen handmatig graven in Obsidian, geen screenshots delen.

Code review context. Ik review een PR en wil weten of vergelijkbare patronen eerder zijn besproken. Een zoekopdracht in de code-reviews collectie geeft me CodeRabbit feedback van eerdere PRs die hetzelfde component raakten. Patronen herkennen in plaats van opnieuw uitvinden.

Changelogs doorzoeken. "Wanneer hebben we de notificatie service aangepast?" Een lexicale search op "notification" in de changelogs collectie geeft me exact de datum, het versienummer, en de beschrijving van de wijziging. Sneller dan git log doorploegen.

Contact en deal info. Midden in een gesprek over een project wil ik weten wat de afspraken waren. "Zoek naar contactgegevens van bedrijf X" haalt direct de relevante Obsidian notitie op, inclusief dealstatus en laatste contactmoment.

Het belangrijkste: dit alles gebeurt binnen mijn context management workflow. QMD levert precies de relevante snippets, niet hele bestanden. Gebruikers rapporteren 96% minder tokens vergeleken met grep-gebaseerde aanpakken. Dat is het verschil tussen een context window dat vol zit na drie queries en een dat de hele sessie meegaat.

Waarom lokaal beter is dan cloud

Er zijn genoeg cloud-gebaseerde search oplossingen. Pinecone, Weaviate, Algolia. Waarom dan lokaal?

Privacy. Mijn vault bevat klantgegevens, deals, contacten, interne notities. Dat gaat niet naar een externe server. Punt. Met QMD verlaat niks je machine. De embeddings worden lokaal gegenereerd, de index staat op je disk, de search draait in je eigen process.

Snelheid. Geen netwerk latency. BM25 search duurt milliseconden. Zelfs de vector search met lokale embeddings is sneller dan een API call naar een cloud service. In mijn setup reageert een lexicale zoekopdracht in minder dan 200ms.

Kosten. Nul. Geen maandelijks abonnement, geen token-gebaseerde pricing, geen usage limits. Je hebt een laptop nodig, meer niet. De GGUF modellen die QMD gebruikt zijn compact genoeg om naast je normale werk te draaien.

Beschikbaarheid. Werkt offline. In het vliegtuig, op een trein zonder wifi, met een instabiele hotelverbinding. Je kennis is altijd doorzoekbaar, ongeacht je connectie.

Integratie met Claude Code

QMD is gebouwd als MCP server. Dat betekent dat het naadloos integreert met Claude Code. In mijn CLAUDE.md staan instructies over wanneer en hoe QMD te gebruiken:

• Bevat Maurice's prompt een persoons- of bedrijfsnaam? Zoek in de vault.
• Verwijst hij naar iets uit het verleden? Zoek in de vault.
• Werkt hij aan een bestaand project? Check changelogs en code reviews.

Claude Code weet automatisch wanneer het QMD moet raadplegen. Dat is de kern van context engineering: niet alles vooraf laden, maar precies de juiste informatie ophalen op het juiste moment.

De zoeksyntax is flexibel. Je kunt lexicaal zoeken voor exacte termen, semantisch zoeken voor betekenis, of beide combineren voor de beste resultaten. Met het intent parameter geef je QMD extra context over wat je zoekt, wat de relevantie van snippets verbetert.

Aan de slag

QMD installeren is simpel. Clone de GitHub repo, configureer je collecties, en draai de indexer. De eerste keer duurt even vanwege het genereren van embeddings, maar daarna is het incrementeel.

Mijn advies: begin klein. Een collectie met je belangrijkste project notities. Kijk hoe het voelt om te zoeken in plaats van te bladeren. Voeg dan geleidelijk meer toe: changelogs, meeting notes, documentatie.

Gebruik je Claude Code met skills en agents? Dan is QMD de ontbrekende schakel. Het geeft je AI assistent toegang tot jouw kennis, zonder dat je het handmatig moet aanleveren. Dat is het verschil tussen een assistent die elke sessie opnieuw begint en een die doorlopend leert.

Wil je weten hoe QMD past in jouw development workflow, of hoe je een vergelijkbare kennisinfrastructuur opzet voor je team? Neem contact op, dan denk ik mee.