qmd

QMD - Query Markup Documents

An on-device search engine for everything you need to remember. Index your markdown notes, meeting transcripts, documentation, and knowledge bases. Search with keywords or natural language. Ideal for your agentic flows.

QMD combines BM25 full-text search, vector semantic search, and LLM re-ranking—all running locally via node-llama-cpp with GGUF models.

This project is a fork of tobi/qmd (Go port, optional GGUF embedding backend).

Quick Start

# Install (requires Go 1.23+)
go install -tags fts5 github.com/ba0f3/qmd-go
# Or from repo:
# git clone https://github.com/ba0f3/qmd-go && cd qmd && go build -tags fts5 -o qmd-go ./cmd/qmd

# Create collections for your notes, docs, and meeting transcripts
qmd collection add ~/notes --name notes
qmd collection add ~/Documents/meetings --name meetings
qmd collection add ~/work/docs --name docs

# Add context to help with search results
qmd context add qmd://notes "Personal notes and ideas"
qmd context add qmd://meetings "Meeting transcripts and notes"
qmd context add qmd://docs "Work documentation"

# Generate embeddings for semantic search
qmd embed

# Search across everything
qmd search "project timeline"           # Fast keyword search
qmd vsearch "how to deploy"             # Semantic search
qmd query "quarterly planning process"  # Hybrid + reranking (best quality)

# Get a specific document
qmd get "meetings/2024-01-15.md"

# Get a document by docid (shown in search results)
qmd get "#abc123"

# Get multiple documents by glob pattern
qmd multi-get "journals/2025-05*.md"

# Search within a specific collection
qmd search "API" -c notes

# Export all matches for an agent
qmd search "API" --all --files --min-score 0.3

Using with AI Agents

QMD's --json and --files output formats are designed for agentic workflows:

# Get structured results for an LLM
qmd search "authentication" --json -n 10

# List all relevant files above a threshold
qmd query "error handling" --all --files --min-score 0.4

# Retrieve full document content
qmd get "docs/api-reference.md" --full

MCP Server

QMD exposes an MCP (Model Context Protocol) server for integration with Claude, Cursor, and other AI tools.

Tools exposed:

• search – Fast BM25 keyword search (supports collection filter)
• vsearch – Semantic vector search (supports collection filter)
• query – Hybrid search (BM25 + vector, RRF)
• get – Retrieve document by path or docid
• multi_get – Retrieve multiple documents by glob or list
• status – Index health and collection info

Resources: Documents are readable via qmd:// URIs (e.g. qmd://collection/path/to/file.md).

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "qmd": {
      "command": "qmd",
      "args": ["mcp"]
    }
  }
}

Claude Code — Install the plugin (recommended):

claude marketplace add tobi/qmd
claude plugin add qmd@qmd

Or configure MCP manually in ~/.claude/settings.json:

{
  "mcpServers": {
    "qmd": {
      "command": "qmd",
      "args": ["mcp"]
    }
  }
}

Architecture

• SQLite FTS5 – Full-text search (BM25)
• Embeddings – Stored in SQLite; generated via Ollama, any OpenAI-compatible API, or local GGUF (purego, no CGO)
• Hybrid search – query combines BM25 and vector results using Reciprocal Rank Fusion (RRF)
• Chunking – 800 tokens per chunk, 15% overlap (character-based in Go)
• Index – ~/.cache/qmd/index.sqlite (or INDEX_PATH)

Query ──┬──► BM25 (FTS5) ──► Ranked list
        │
        └──► Embed query ──► Vector similarity ──► Ranked list
                                    │
                                    ▼
                            RRF fusion ──► Final results

Requirements

• Go 1.23 or later (for building)
• SQLite with FTS5 (e.g. github.com/mattn/go-sqlite3 – enable via build tag fts5)
• Embeddings: Ollama (default), any OpenAI-compatible API, or local GGUF via purego (no CGO; build libllama_go with make deps-purego and make build-purego)

Build tags

Tag	Purpose
fts5	Use for normal builds. Enables SQLite FTS5 full-text search. Without it, qmd search and related features will not work.
gguf	Optional. Enables local GGUF embedding models (no Ollama required). Preferred: purego (no CGO) — build the shared library with make deps-purego and make build-purego, then make build-gguf. Fallback: CGO with go-llama.cpp via make deps-gguf then make build-gguf.

Examples: make build (outputs qmd-go) or go build -tags fts5 -o qmd-go ./cmd/qmd. For GGUF embeddings: make build-gguf.

Installation

From source (recommended)