qmd

What This Skill Does

The qmd skill is a powerful, high-performance local search engine specifically optimized for Markdown-based knowledge bases, notes, and documentation. It bridges the gap between simple grep-style searches and complex LLM-driven retrieval systems. By leveraging BM25 for near-instant keyword matching and providing optional semantic vector search (vsearch), the qmd skill allows OpenClaw to quickly navigate your local files to surface relevant context. It is designed to handle collections of disparate Markdown files, indexing them effectively to support fast information retrieval without requiring external cloud databases, ensuring your data stays private and local.

Installation

To integrate this skill, ensure you have Bun version 1.0.0 or higher installed. On macOS, make sure you have SQLite extensions via brew install sqlite. First, ensure your shell PATH contains your Bun installation directory. Install the tool globally by running bun install -g https://github.com/tobi/qmd. Once installed, you must initialize your collections by navigating to your notes directory and running qmd collection add /path/to/notes --name notes --mask "**/*.md". For enhanced semantic capabilities, run qmd embed to generate the necessary vectors. If you need to specify context for your collection, use qmd context add to help the engine understand the purpose of specific folders.

Use Cases

This skill is perfect for users who maintain a "second brain" or personal wiki in Markdown. It excels at finding specific snippets within years of notes, identifying related concepts across multiple files, and retrieving technical documentation quickly. It is ideal for developers, researchers, or writers who need to cross-reference their own content. The tool handles "messy" notes effectively by using content-based chunking, making it highly reliable for non-structured data.

Example Prompts

1. "Search my notes for any mentions of 'project architecture' to help me catch up on my recent designs."
2. "I need to find a related document in my knowledge base that explains the setup process for our local API; search for the configuration steps."
3. "Can you retrieve the markdown document titled 'Q3 Goals' from my collection and summarize the key action items for me?"

Tips & Limitations

For optimal performance, always default to qmd search as it provides the most responsive experience. Only resort to qmd vsearch if keywords fail to find the desired document, as it carries a performance penalty due to model loading. Avoid qmd query for standard interactions, as the overhead of LLM reranking can lead to timeouts. Remember that qmd is not intended for general code search; if you are looking for specific function definitions or variable usages in code, use dedicated code-scanning tools. Because local vector searching may require loading a model into memory, consider keeping the session warm if you anticipate performing multiple semantic searches in a single interaction loop.