qmd

What This Skill Does

qmd is a high-performance, local-first search engine specifically optimized for Markdown-based knowledge bases, notes, and documentation. By leveraging hybrid search techniques, it enables users to index their local file systems and retrieve context instantly. The tool utilizes BM25 for rapid keyword-based discovery as its primary mechanism, ensuring that 'search' operations feel instantaneous, while providing optional semantic vector search and LLM-powered reranking for complex queries where conceptual matching is preferred over literal string matching.

Installation

To integrate the qmd skill into your environment, ensure you have Bun installed (>= 1.0.0). On macOS, you must install SQLite with extensions using brew install sqlite. Once prerequisites are met, install the global package via bun install -g https://github.com/tobi/qmd. After installation, run qmd collection add /path/to/your/notes to register your markdown directory, and execute qmd embed to generate the necessary vector indexes to enable advanced semantic search capabilities.

Use Cases

This skill is indispensable for individuals who maintain personal wikis, developers managing documentation in markdown, or researchers storing extensive notes. It is best suited for scenarios where you need to quickly surface information from fragmented notes or locate specific technical documentation within a large collection. It serves as an internal knowledge retrieval system that keeps your data local, private, and searchable without requiring external cloud synchronization.

Example Prompts

1. "Search my notes for the project plan regarding the Q4 marketing initiative."
2. "I need to find related notes about my previous Python refactoring work; can you retrieve that for me?"
3. "Search my local markdown files for any mentions of 'API authentication' and give me the full content of the most relevant document."

Tips & Limitations

For the best experience, default to the standard search command (qmd search), as it is the most responsive. The vector (vsearch) and hybrid (query) modes are significantly slower due to the potential cold-start overhead of loading local models and performing intensive reranking. Use these advanced modes only when exact keyword matching fails to produce the desired result. Note that qmd is designed for text-heavy markdown files and should not be used as a replacement for dedicated code-indexing tools which are optimized for source code structures and language-specific symbols.