qmd

Search local markdown notes and documents using hybrid BM25, vector, and LLM reranking retrieval.

Updated Jul 7, 2026
One-click install
npx skills add https://github.com/episvr/USTB-2026-SummerInternship --skill qmd-episvr
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: qmd
Source: https://github.com/episvr/USTB-2026-SummerInternship/tree/main/hermes-config/optional-skills/research/qmd
Command: npx skills add https://github.com/episvr/USTB-2026-SummerInternship --skill qmd-episvr

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires @tobilu/qmd.

What problem does it solve? Finding information across large collections of personal notes, meeting transcripts, and documentation is slow with plain grep and inaccurate with keyword-only search. This Skill sets up and operates qmd, a fully local search engine that combines keyword matching, semantic vector search, and LLM reranking so you can query your knowledge base in natural language without sending data to the cloud. ## Core Features & Use Cases - Three Search Modes: Run instant BM25 keyword search, semantic vector search, or full hybrid search with query expansion and LLM reranking depending on speed and quality needs. - Collection Management: Add directories as named collections, attach context descriptions to improve retrieval accuracy, and generate embeddings with a single command. - MCP Integration: Expose search tools directly to Hermes Agent via stdio or a persistent HTTP daemon that keeps models warm for fast repeated queries. - Use Case: You have years of markdown meeting notes and project docs. After indexing them with qmd, you ask "what decisions were made about the database migration" and get reranked, contextually relevant excerpts in seconds. ## Quick Start Use the qmd skill to search my notes collection for anything about the API redesign decisions.

Frequently Asked Questions about qmd

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I search my markdown notes locally with semantic search?▼

Install qmd via npm, add your notes directory with qmd collection add, run qmd embed to generate vector embeddings, then use qmd vsearch for semantic queries or qmd query for hybrid search with LLM reranking. Everything runs locally with no cloud dependencies.

What is the difference between qmd search, vsearch, and query?▼

qmd search is BM25 keyword-only search that runs in about 0.2 seconds with no models loaded. qmd vsearch uses one embedding model for semantic search in about 3 seconds. qmd query runs the full hybrid pipeline with query expansion and reranking for the best quality.

Does qmd work offline without cloud services?▼

Yes, qmd runs entirely on-device. It auto-downloads three local GGUF models totaling about 2GB on first run, stores its index in a local SQLite database, and sends no data to external services.

How do I integrate qmd with Hermes Agent via MCP?▼

Add qmd as an MCP server in ~/.hermes/config.yaml using either stdio mode with command qmd mcp, or HTTP daemon mode pointing to http://localhost:8181/mcp. This registers mcp_qmd_search, mcp_qmd_vsearch, mcp_qmd_deep_search, mcp_qmd_get, and mcp_qmd_status tools.

Why is the first qmd query slow and how do I fix it?▼

Cold start takes about 19 seconds because the GGUF models must load into memory. Run qmd mcp --http --daemon to keep models warm for 2-3 second queries, or use qmd search for instant BM25 results when semantic ranking is not needed.

Why does qmd fail to load extensions on macOS?▼

macOS system SQLite lacks extension loading support, which qmd requires. Install Homebrew SQLite with brew install sqlite and ensure it appears on your PATH before the system SQLite, then verify with qmd status.