qmd

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

1|Updated Mar 12, 2026
One-click install
npx skills add https://github.com/kaminocorp/hermes-alpha-hunter --skill qmd-kaminocorp
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: qmd
Source: https://github.com/kaminocorp/hermes-alpha-hunter/tree/main/optional-skills/research/qmd
Command: npx skills add https://github.com/kaminocorp/hermes-alpha-hunter --skill qmd-kaminocorp

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: Use qmd search for instant BM25 keyword lookup, qmd vsearch for semantic vector search, and qmd query for hybrid search with query expansion and LLM reranking. - Collection Management: Add directories as named collections, attach context descriptions to improve retrieval quality, and generate embeddings with qmd embed. - MCP Integration: Expose search tools directly to the agent via stdio or a persistent HTTP daemon that keeps models warm for fast repeated queries. - Use Case: You have years of meeting transcripts and project docs in markdown. Add them as qmd collections, then ask "what decisions were made about the database migration" and get reranked, contextually relevant excerpts in seconds. ## Quick Start Install qmd with npm, add my notes folder as a collection, run the embedding step, and then search my notes for everything 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 reranking. Everything runs locally with no cloud dependency.

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 the embedding model for semantic matching, and `qmd query` combines both with query expansion and LLM reranking for the highest quality results.

Does qmd work offline without sending data to the cloud?▼

Yes, qmd runs entirely on-device. It downloads three local GGUF models (~2GB total) on first run for embeddings, reranking, and query expansion, and stores its index in a local SQLite database at ~/.cache/qmd/index.sqlite.

Why is my first qmd query slow to respond?▼

The first query triggers a cold start of about 19 seconds while the GGUF models load into memory. To avoid this, run `qmd mcp --http --daemon` to keep models warm, or use `qmd search` for BM25-only queries that need no models.

How do I integrate qmd with an AI agent via MCP?▼

Run `qmd mcp` for stdio mode or `qmd mcp --http --daemon` for a persistent HTTP server on port 8181, then add the server to your agent's MCP configuration. This exposes tools like mcp_qmd_search, mcp_qmd_deep_search, and mcp_qmd_get.

What are the system requirements for installing qmd?▼

qmd requires Node.js version 22 or higher and is installed via `npm install -g @tobilu/qmd`. On macOS you also need Homebrew's SQLite because the system SQLite lacks extension loading support. It supports macOS and Linux platforms.