Skip to content
Get packs

QMD

Local search tool for your markdown notes and docs, combining keyword and AI-based semantic search.

GitHub Download v2.8.3
Stars
30.8k
Forks
1.9k
Licence
MIT
Language
TypeScript
Last update
22 days ago
Type
CLI

What it is

QMD is a command-line search engine that indexes your markdown notes, meeting transcripts, and documentation on your own machine. You can search by exact keywords or by natural language, and it combines full-text search, vector semantic search, and LLM re-ranking, all running locally using GGUF models through node-llama-cpp. It is also designed so AI agents can use it, including through an MCP server.

  • Index a notes folder and search it with qmd search for keyword matches
  • Run qmd query for hybrid search with reranking across meeting notes and docs
  • Export matching files or JSON results for an AI agent with --files or --json
  • Serve the index over MCP so an agent such as Claude can search your documents

Great for

  • People with many markdown notes or meeting transcripts who want local search
  • Developers building agentic workflows that need document retrieval
  • Users who want to keep their documents off cloud services
  • Anyone who wants to connect a local document index to Claude Desktop or Claude Code via MCP

Not ideal for

  • People who need a graphical app; the README describes a command-line tool and MCP server, not a GUI
  • Users on machines that cannot run local LLM models, since embeddings and reranking rely on them
  • Anyone needing a multi-user or internet-facing server, because the HTTP endpoints are unauthenticated per the README
Step-by-step guide: how to use QMDInstall, first run, examples, tips and FAQs

How to get it

  1. 1

    Install with a package manager

    You'll need: Node.js or Bun

    Install globally with npm

    npm install -g @tobilu/qmd

    Or install globally with Bun

    bun install -g @tobilu/qmd
  2. 2

    Run it

    • Add a folder as a collection: qmd collection add ~/notes --name notes
    • Add context to the collection: qmd context add qmd://notes "Personal notes and ideas"
    • Generate embeddings: qmd embed
    • Search with: qmd query "quarterly planning process"
  3. 3

    Get the most out of it

    • Add context descriptions to collections, which the README says are returned with matching documents and help agents choose better results
    • Use --json or --files output for passing results to LLM agents
    • Run the HTTP transport with qmd mcp --http --daemon to avoid repeated model loading
    • Use metadata filtering through the MCP query tool's filter parameter

Downloads

Source code (.zip)main branch · straight from GitHubRelease v2.8.3Release notes and source

Strengths

  • Runs locally, with the README stating models run on-device via node-llama-cpp
  • Combines keyword, semantic, and reranked search in one tool
  • Supports MCP and structured JSON output for agent integration

Trade-offs

  • Requires setting up embeddings and local models, which the README does not fully detail in the truncated portion
  • The README is truncated, so some options and behaviors could not be verified
  • Local LLM use implies hardware demands the README does not quantify

Stats synced from GitHub. The assessment above was drafted with AI from the project's README on 2026-10-29 and may miss recent changes — check the README before relying on a command. MIT licence: free to use, modify and distribute, including commercially, as long as you keep the copyright notice.