Qmd

1---2name: qmd3description: Local hybrid search for markdown notes and docs. Use when searching notes, finding related content, or retrieving documents from indexed collections.4homepage: https://github.com/tobi/qmd5metadata: {"clawdbot":{"emoji":"🔍","os":["darwin","linux"],"requires":{"bins":["bun","qmd"]},"install":[{"id":"bun-qmd","kind":"shell","command":"bun install -g https://github.com/tobi/qmd","bins":["qmd"],"label":"Install qmd via Bun"}]}}6---7 8# qmd - Quick Markdown Search9 10Local search engine for Markdown notes, docs, and knowledge bases. Index once, search fast.11 12## When to use (trigger phrases)13 14- "search my notes / docs / knowledge base"15- "find related notes"16- "retrieve a markdown document from my collection"17- "search local markdown files"18 19## Default behavior (important)20 21- Prefer `qmd search` (BM25). It's typically instant and should be the default.22- Use `qmd vsearch` only when keyword search fails and you need semantic similarity (can be very slow on a cold start).23- Avoid `qmd query` unless the user explicitly wants the highest quality hybrid results and can tolerate long runtimes/timeouts.24 25## Prerequisites26 27- Bun >= 1.0.028- macOS: `brew install sqlite` (SQLite extensions)29- Ensure PATH includes: `$HOME/.bun/bin`30 31Install Bun (macOS): `brew install oven-sh/bun/bun`32 33## Install34 35`bun install -g https://github.com/tobi/qmd`36 37## Setup38 39```bash40qmd collection add /path/to/notes --name notes --mask "**/*.md"41qmd context add qmd://notes "Description of this collection"  # optional42qmd embed  # one-time to enable vector + hybrid search43```44 45## What it indexes46 47- Intended for Markdown collections (commonly `**/*.md`).48- In our testing, "messy" Markdown is fine: chunking is content-based (roughly a few hundred tokens per chunk), not strict heading/structure based.49- Not a replacement for code search; use code search tools for repositories/source trees.50 51## Search modes52 53- `qmd search` (default): fast keyword match (BM25)54- `qmd vsearch` (last resort): semantic similarity (vector). Often slow due to local LLM work before the vector lookup.55- `qmd query` (generally skip): hybrid search + LLM reranking. Often slower than `vsearch` and may timeout.56 57## Performance notes58 59- `qmd search` is typically instant.60- `qmd vsearch` 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.61- `qmd query` adds LLM reranking on top of `vsearch`, so it can be even slower and less reliable for interactive use.62- 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.63 64## Common commands65 66```bash67qmd search "query"             # default68qmd vsearch "query"69qmd query "query"70qmd search "query" -c notes     # Search specific collection71qmd search "query" -n 10        # More results72qmd search "query" --json       # JSON output73qmd search "query" --all --files --min-score 0.374```75 76## Useful options77 78- `-n <num>`: number of results79- `-c, --collection <name>`: restrict to a collection80- `--all --min-score <num>`: return all matches above a threshold81- `--json` / `--files`: agent-friendly output formats82- `--full`: return full document content83 84## Retrieve85 86```bash87qmd get "path/to/file.md"       # Full document88qmd get "#docid"                # By ID from search results89qmd multi-get "journals/2025-05*.md"90qmd multi-get "doc1.md, doc2.md, #abc123" --json91```92 93## Maintenance94 95```bash96qmd status                      # Index health97qmd update                      # Re-index changed files98qmd embed                       # Update embeddings99```100 101## Keeping the index fresh102 103Automate indexing so results stay current as you add/edit notes.104 105- For keyword search (`qmd search`), `qmd update` is usually enough (fast).106- If you rely on semantic/hybrid search (`vsearch`/`query`), you may also want `qmd embed`, but it can be slow.107 108Example schedules (cron):109 110```bash111# Hourly incremental updates (keeps BM25 fresh):1120 * * * * export PATH="$HOME/.bun/bin:$PATH" && qmd update113 114# Optional: nightly embedding refresh (can be slow):1150 5 * * * export PATH="$HOME/.bun/bin:$PATH" && qmd embed116```117 118If your Clawdbot/agent environment supports a built-in scheduler, you can run the same commands there instead of system cron.119 120## Models and cache121 122- Uses local GGUF models; first run auto-downloads them.123- Default cache: `~/.cache/qmd/models/` (override with `XDG_CACHE_HOME`).124 125## Relationship to Clawdbot memory search126 127- `qmd` searches *your local files* (notes/docs) that you explicitly index into collections.128- Clawdbot's `memory_search` searches *agent memory* (saved facts/context from prior interactions).129- Use both: `memory_search` for "what did we decide/learn before?", `qmd` for "what's in my notes/docs on disk?".