qmd - Quick Markdown Search

Local search engine for Markdown notes, docs, and knowledge bases. Index once, search fast.

When to use (trigger phrases)

• - "search my notes / docs / knowledge base"
• "find related notes"
• "retrieve a markdown document from my collection"
• "search local markdown files"

Default behavior (important)

• - Prefer qmd search (BM25). It's typically instant and should be the default.
• Use qmd vsearch only when keyword search fails and you need semantic similarity (can be very slow on a cold start).
• Avoid qmd query unless the user explicitly wants the highest quality hybrid results and can tolerate long runtimes/timeouts.

Prerequisites

• - Bun >= 1.0.0
• macOS: brew install sqlite (SQLite extensions)
• Ensure PATH includes: INLINECODE4

Install Bun (macOS): INLINECODE5

Install

INLINECODE6

Setup

CODEBLOCK0

What it indexes

• - Intended for Markdown collections (commonly **/*.md).
• In our testing, "messy" Markdown is fine: chunking is content-based (roughly a few hundred tokens per chunk), not strict heading/structure based.
• Not a replacement for code search; use code search tools for repositories/source trees.

Search modes

• - qmd search (default): fast keyword match (BM25)
• INLINECODE9 (last resort): semantic similarity (vector). Often slow due to local LLM work before the vector lookup.
• INLINECODE10 (generally skip): hybrid search + LLM reranking. Often slower than vsearch and may timeout.

Performance notes

• - qmd search is typically instant.
• INLINECODE13 can be ~1 minute on some machines because query expansion may load a local model (e.g., Qwen3-1.7B) into memory per run; the vector lookup itself is usually fast.
• INLINECODE14 adds LLM reranking on top of vsearch, so it can be even slower and less reliable for interactive use.
• If you need repeated semantic searches, consider keeping the process/model warm (e.g., a long-lived qmd/MCP server mode if available in your setup) rather than invoking a cold-start LLM each time.

Common commands

CODEBLOCK1

Useful options

• - -n <num>: number of results
• INLINECODE17: restrict to a collection
• INLINECODE18: return all matches above a threshold
• INLINECODE19 / --files: agent-friendly output formats
• INLINECODE21: return full document content

Retrieve

CODEBLOCK2

Maintenance

CODEBLOCK3

Keeping the index fresh

Automate indexing so results stay current as you add/edit notes.

• - For keyword search (qmd search), qmd update is usually enough (fast).
• If you rely on semantic/hybrid search (vsearch/query), you may also want qmd embed, but it can be slow.

Example schedules (cron):

CODEBLOCK4

If your Clawdbot/agent environment supports a built-in scheduler, you can run the same commands there instead of system cron.

Models and cache

• - Uses local GGUF models; first run auto-downloads them.
• Default cache: ~/.cache/qmd/models/ (override with XDG_CACHE_HOME).

Relationship to Clawdbot memory search

• - qmd searches your local files (notes/docs) that you explicitly index into collections.
• Clawdbot's memory_search searches agent memory (saved facts/context from prior interactions).
• Use both: memory_search for "what did we decide/learn before?", qmd for "what's in my notes/docs on disk?".