QMD: documentation you can't query is a graveyard

You have four hundred markdown files. Architecture decisions, operations guides, meeting notes, that one doc explaining why the login flow looks the way it does. You wrote all of it for future-you and your AI agents to use later. Honest question: when did you last find the right file at the exact moment you needed it?

If the sincere answer is "I searched for the word I remembered, didn't find it, and rewrote a doc that already existed", you don't have a knowledge base. You have a graveyard where every headstone is a file nobody reads.

My position: documentation you can't query is just a folder full of files with a little guilt on top. This piece is about what separates the two. I'll carry one concrete case from start to finish, and a real tool as the thread: QMD, a free, open-source project that does exactly this on your own machine.

The case: the decision you can't find

Six months ago your team decided not to use a message queue for a specific payment flow, and wrote down why. Today a new developer asks: "why don't we use a queue here?". You know a doc exists. You just don't remember the filename, or the exact words you used.

You search for "queue", the way programmers do with a grep. Twenty-seven hits, none of them the right one. You try "message queue", "messaging", "buffer". The doc used the word "broker", which you didn't think to search. After ten minutes you give up and answer from memory. The written decision exists, it's saved in the project history, and it's useless, because the retrieval system is your memory, and your memory failed.

The problem isn't that you wrote the wrong doc. It's that writing and retrieving are two different things, and you only solved the first.

Why searching by the word isn't enough

Exact search finds the word you remember. It can't find the idea you forgot you wrote down. That gap is the whole game.

A real knowledge base searches on two axes at once. The first is lexical search, which nails the literal term: the error code, the function name, the client's name. The second is semantic search, which finds by meaning. That's what was missing in the example: "why don't we use a queue" should have surfaced the "broker" doc even with no shared keyword.

Simon Willison has the best description of this I've seen. He calls semantic search "vibes-based search": the doc and your question share the same vibe, according to a weird multi-dimensional representation of what words mean, and it's absurdly useful. It's the right phrase because it's honest about both sides. It works surprisingly well, and it's fundamentally fuzzy. You don't get the answer, you get the most likely candidates.

Both axes together beat either one alone

This isn't opinion, it's a measured result. Anthropic published an engineering writeup on Contextual Retrieval that combines embeddings with classic lexical search (in their version, with context added to each chunk) precisely because neither alone is enough. The numbers are concrete: joining the two axes cut failed retrievals by 49 percent, and adding a reranking step, by 67 percent. The pattern isn't new, it traces back to the paper that coined retrieval-augmented generation in 2020. What's new is that today you can run a competent version of this locally, over your own files, without shipping a byte to anyone's cloud.

That's exactly what qmd, an open-source tool by Tobi Lütke, does. It indexes your markdown and combines BM25, vector search, and language-model reranking, all running on your machine via local models. I cite qmd not to tell you which tool to use, but because it proves it can be done: what looked like AI-lab gear is now a free, open-source program that runs on your own machine, over your own documents.

QMD up close, and the idea worth stealing

It's worth looking at what QMD actually is, because it carries a design decision most search tools ignore. The person who wrote it is Tobi Lütke, the founder and CEO of Shopify. Someone who could delegate anything sat down and shipped a free command-line tool to search his own files. That alone is a sign of the moment: local retrieval went from PhD project to a utility that fits in a weekend.

Under the hood, QMD does what I described above: it indexes your files, searches on both axes at once, fuses the results, and reranks with a model running on your own machine, sending nothing out. But the part I'd single out isn't that. It's the one the author himself flags in the manual as "the key feature of QMD," telling you not to sleep on it: the context tree.

The idea is simple and powerful. You attach a sentence of context to a whole folder, say "product meeting transcripts", and that sentence comes back whenever a document from that folder shows up in a search. It sounds trivial until you think about what it fixes. A loose snippet that says "we decided not to" is noise. The same snippet tagged "architecture decision, payment flow, June" is an answer. The context that lives in your head, and vanishes when you forget the file, now travels glued to the document. It's the difference between an AI agent picking the right document and it guessing the closest-looking one.

It's not the only tool doing local hybrid search, and that doesn't matter. What matters is that the pattern exists in a form you can own, audit, and abandon without pain. That's the criterion, and the tool is just proof the criterion is reachable today.

Where semantic search betrays you

If I stopped here it would be semantic-search propaganda. Willison's own description carries the warning: "vibe" is powerful and it's fuzzy. Three real traps.

First: semantic search retrieves what seems related, not what's correct. It will hand you the old queue-decision doc with the same confidence it would hand you a doc that mentions queues but decided the opposite. Similar to your question is not the same as true for your case.

Second: embeddings carry the bias of the moment they were generated. If you indexed the docs three months ago and your team's vocabulary moved, the vibe ages. Retrieval with no freshness is a stale photo of your own collection.

Third: the temptation to trust the first result. The value of a queryable base isn't that it gives you an answer. It's that it gives you the pointer to the source, which you open and read. The instant you treat a search result as truth instead of a candidate, you've traded a graveyard for a confident source of errors.

Retrieval doesn't give you the answer. It gives you the pointer to the source. Whether the source holds up is your call, after you open it.

The criteria that matter more than the tool

The question is never "which retrieval tool is best". It's "which one can I own, audit, and abandon without pain". My criteria, in order:

• Local first. Your collection is decisions, client context, half-formed strategy. That doesn't belong in a third party's index by default. Local retrieval keeps what's private, private.
• **CLI before SDK before MCP.** If a tool gives me a real command line, I can script it, schedule it, and inspect it. The further down that list you go, the more locked into the tool you get and the less you can see what it does inside. The simplest surface that works is usually the most durable.
• Verify before you trust. Every retrieval returns candidates. The step that separates a useful base from a hallucination factory is opening the source and checking it before acting on it.

Implementing this depends on your collection, your risk, and your tolerance for stale information, which is why no honest post hands it to you as a recipe. What generalizes is the criteria.

The position

Markdown is where the repository remembers. But memory you can't retrieve isn't memory, it's storage. The graveyard isn't a format problem, it's a retrieval problem. You don't lose the decision because it was the wrong file extension. You lose it because nothing answers "where did we decide X, and why?" without you remembering the filename first.

The honest measure of your knowledge base isn't how many files it has. It's how long it takes, right now, to find the queue decision. If the answer is "first I need to remember where I put it", you don't have a base. You have a well-organized graveyard.

The good news is the fix is no longer exotic. A project like QMD proves you can run a real queryable base locally, today, over your own files. The tool will change. The criterion won't: can you find the decision, right now?