qmd External Knowledge Base Search

**Judgement:** A strong, local-first Markdown knowledge base search tool that works well as an external retrieval layer for agents, provided the environment is correctly set up and the agent is disciplined about which search mode it uses. **What it does well** - Provides fast, high-quality keyword search (`qmd search`, BM25) over Markdown collections; ideal as the *default* retrieval method. - Supports semantic (`vsearch`) and hybrid (`query`) modes for harder queries where keyword search fails, leveraging local GGUF models. - Offers agent-friendly output (`--json`, `--files`, `--full`) and direct file retrieval (`qmd get`, `multi-get`), making it easy to pull context into an AI workflow. - Keeps everything local (files and models), which is excellent for privacy-sensitive note vaults and knowledge bases. **Key risks / limitations** - **Environment & setup:** Requires Bun, SQLite, and qmd installation plus PATH configuration; misconfiguration will break the skill entirely. Not plug-and-play on all platforms. - **Performance pitfalls:** `qmd vsearch` and especially `qmd query` can be very slow on cold start (tens of seconds to ~1 minute) due to local model loading and reranking. Overuse will degrade UX or cause timeouts. - **Freshness:** Search quality depends on regular `qmd update` and `qmd embed`; stale indexes will miss recent notes unless a cron or similar automation is reliably configured. - **Scope limitations:** Designed for Markdown docs; not a replacement for code search or arbitrary binary/document formats. **Recommended scenarios** - As the primary external KB search for personal or team Markdown note vaults where privacy and local control are priorities. - For workflows where the agent mostly uses **fast BM25 keyword search**, occasionally falling back to semantic search when explicitly needed. - For users willing to maintain a scheduled re-index (e.g., cron) and tolerate occasional slower semantic queries for deep-dive research. **Usage recommendations for agents** - Default to `qmd search` with sensible options (`-c` for collection, `-n` for result count, `--json` for parsing). - Only use `qmd vsearch` when: - Keyword search has clearly failed *and* - The user can tolerate higher latency. - Avoid `qmd query` unless the user explicitly asks for “highest quality hybrid results” and is aware of the performance cost. - Encourage users to set up periodic `qmd update && qmd embed` to keep the index and embeddings in sync with their evolving notes.