Machine-translated from the Korean original. Read the original

Query Markup Documents (QMD)

Contents
Vittore Carpaccio, "St. Augustine in His Study", c. 1502. Scuola di San Giorgio degli Schiavoni, Venice.
Vittore Carpaccio, "St. Augustine in His Study", c. 1502. Scuola di San Giorgio degli Schiavoni, Venice.

Intro

Note management is said to come down to reading, writing, and finding things well, but each of these steps is far more complicated than it sounds. Reading and writing are taught at the core of our education, so we know how much they matter and can say we're reasonably familiar with them. Finding is a different story. In this post, I introduce QMD, a tool that lets you find notes by meaning. I personally use it a lot alongside Obsidian.

Note that QMD runs locally, so your computer needs reasonably good specs.

File search methods fall into two broad categories.

파일 검색 방식Lexical Search(Keyword search)Semantic Search
  • Lexical search finds items that contain the search term. This is the search method that comes to mind intuitively for most of us. BM25 is the best-known example.
  • Semantic search finds items whose meaning is similar to the search term. There are various ways to search by meaning, but in Personal Knowledge Management the method mainly used is one based on an embedding model.

Using an embedding model works like this.

cosine similarity📄📄📄노트들🧠Embedding Model🔍검색어[0.2, -0.5, ...] × N벡터 집합[0.3, -0.4, ...]쿼리 벡터📄유사한 노트

When you embed a note, it turns into a vector. A good embedding model turns things with similar meanings into similar vectors and different things into different vectors. Then, when a search term comes in, it is also turned into a vector, and cosine similarity is used to find the most similar notes.

QMD

What is QMD?

I had wanted to find Obsidian notes by meaning for a long time, and the Smart Connections community plugin actually made that possible. But at some point, choosing the embedding model became a paid feature, and unless you pay, Smart Connections has become a mess. The embedding model designated for free use performs very poorly in Korean. While I was looking for an alternative, QMD happened to appear.

QMD is a local markdown search tool made by Tobi Lütke, the founder of Shopify. It runs as a CLI and indexes your markdown notes locally (tokenizing or embedding them) so they become searchable. It also supports several search methods: BM25, vector search, and hybrid search that combines BM25 plus vector search with an LLM. All of this runs on local models.

Honestly, for the embedding part I would have liked to use an embedding model from OpenAI or Voyage AI. It costs money, but embedding isn't that expensive and doesn't depend on the performance of your local PC. Still, the fact that everything works only locally can be an advantage when you use it at a company where security matters.

QMD is also specialized for markdown, so it chunks documents in a markdown-friendly way. That is, when a document gets long, it splits it up and embeds the pieces. But if you cut the document ruthlessly (?) at a fixed number of tokens, the content can end up split in the middle of a sentence. So QMD uses markdown elements such as headings to chunk within the structure of the markdown.

Note that if you use QMD's lexical search method, BM25, as is, it doesn't work well for Korean. For example, if you have a note named 안보위기, searching 안보 finds it, but searching 위기 doesn't. This is because, unlike English, Korean is sometimes written without spaces. The problem arises during tokenization, and there are projects like kQMD↗ that try to fix it. (This problem also occurs in the Obsidian plugin Omnisearch.) Perhaps QMD itself will support a fix for this in the future.

Given this situation, for lexical search I leave the file searching to the AI Agent rather than QMD. In this case, Claude Code uses Grep or Glob. I use QMD's semantic search only when I need search by meaning. This kind of hybrid search may look inefficient, but it works for now, so I keep using it as is. After all, in PKM you will have 10,000 notes at the very most.

Using QMD

Installation

For installing QMD, see https://github.com/tobi/qmd↗. It may be a bit of a headache for Windows users.

Adding a Collection

QMD manages a set of markdown notes in a unit called a collection. So to use an Obsidian vault with QMD, you need to add the vault folder as a collection. In the terminal, go to the Obsidian vault folder and enter qmd collection add . --name pkm to add the vault folder as a collection named pkm.

Change the Embedding Model

The default embedding model is embeddinggemma-300M-Q8_0, which performs poorly in Korean. So you need to change the embedding model. You can use a Qwen3 embedding model, like this:

export QMD_EMBED_MODEL="hf:Qwen/Qwen3-Embedding-0.6B-GGUF/Qwen3-Embedding-0.6B-Q8_0.gguf"
qmd embed -f

Because export changes an environment variable, you need to register it so the embedding model is set automatically whenever your shell starts, for example in ~/.zshrc. Also, since the embedding model has changed, if you had previously embedded with embeddinggemma, you need to force re-embedding with qmd embed -f. (If you don't understand what this means, ask an AI Agent to do it for you.)

Also, embeddings are not updated automatically when files in an added collection change. So you need to set up a cronjob that updates the collection and then embeds. In my case, I set the following command to run at around 2 a.m. It doesn't seem necessary to run embedding every time a file changes.

qmd update && qmd embed

You can check that everything worked with qmd status.

Since this is a local embedding model, you may doubt its performance. I cover that in Qwen3-Embedding 0.6B Embedding Performance.

Using QMD as OpenClaw's Memory Engine

If you use OpenClaw, you can also use QMD as its memory engine. OpenClaw saves some conversation context to memory during chats, and this is recorded as markdown files.

But you need to retrieve that memory through semantic search. Honestly, it isn't necessary while the conversation history is still small. In the extreme case, you could just hand all of these files to the AI. But once the amount grows, you need to pull in only what's needed, and then you need to pull it in based on meaning. That's where QMD comes in, and how to set it up is documented at https://docs.openclaw.ai/concepts/memory-qmd↗. If the integration succeeds, running qmd status will show memory-root-main, memory-alt-main, and memory-dir-main added as collections.

Letting an AI Agent Use QMD on Your Obsidian Vault

QMD supports MCP. So if you want Claude Code or similar tools to use your notes embedded with QMD, you can connect it via MCP. For example, with Claude Desktop, you can set up the MCP connection with the following configuration.

{
  "mcpServers": {
    "qmd": {
      "command": "qmd",
      "args": ["mcp"]
    }
  }
}

Closing

A full era of local LLMs may still be some way off, but I suspect that embedding models, at least, will soon reach a satisfying level even when run on a local PC. QMD is a great tool that lets an AI Agent search your Obsidian vault by meaning, with no billing and no tedious API setup. I recommend giving it a try.

Graph
Graph