Qmd

Qmd is a community skill for local search and indexing using BM25, vector embeddings, and reranking, covering document indexing, semantic search, hybrid retrieval, result ranking, and MCP mode for AI agent integration.

What Is This?

Overview

Qmd provides local document search and indexing capabilities using advanced retrieval algorithms for finding relevant content. It covers document indexing that processes files and text content into searchable structures with metadata extraction, semantic search that finds relevant documents based on meaning rather than exact keyword matches using vector embeddings, hybrid retrieval that combines traditional BM25 keyword scoring with vector similarity for comprehensive results, result ranking that applies reranking models to improve relevance and order search results accurately, and MCP mode that enables integration with AI agents through the Model Context Protocol for seamless knowledge retrieval. The skill helps users build powerful local search systems without relying on external search services or cloud infrastructure, keeping data private and processing fast.

Who Should Use This

This skill serves developers building local search features, researchers organizing large document collections, and AI agents requiring semantic retrieval capabilities. It is also well suited for teams managing internal wikis, technical documentation repositories, or any structured knowledge base that requires fast and accurate local querying.

Why Use It?

Problems It Solves

Simple keyword search misses relevant documents that use different terminology or synonyms for the same concepts. Building search systems from scratch requires implementing complex indexing algorithms, vector databases, and ranking models. Cloud-based search services raise privacy concerns when indexing sensitive documents and incur ongoing costs for storage and queries. Exact match search fails to handle natural language queries that express information needs conversationally rather than with precise keywords.

Core Highlights

Document indexer processes files and text into searchable structures locally. Semantic search engine finds relevant content based on meaning using embeddings. Hybrid retrieval combines BM25 keyword scoring with vector similarity. Reranker improves result ordering with advanced relevance models, making it easier to surface the most useful documents even when query phrasing varies significantly from the source text.

How to Use It?

Basic Usage

qmd index ./docs

qmd search \
  "machine learning basics"

qmd search \
  --mode hybrid \
  "neural networks"

qmd mcp --port 3000

Real-World Examples

qmd index \
  ./knowledge_base \
  --recursive \
  --extensions ".md,.txt"

qmd search \
  "How do transformers work?" \
  --mode semantic \
  --top-k 10 \
  --rerank

qmd search \
  "Python async patterns" \
  --format json \
  > results.json

Advanced Tips

Combine BM25 and vector search in hybrid mode for best results across different query types and document characteristics, leveraging the strengths of both traditional keyword matching and modern semantic understanding. Enable reranking to significantly improve result quality at the cost of slightly slower query times. Use MCP mode to integrate with AI agents for retrieval augmented generation workflows that enhance LLM responses with relevant document context. When indexing mixed content types such as markdown documentation alongside plain text logs, specifying file extensions explicitly helps ensure consistent embedding quality and avoids processing irrelevant files.

When to Use It?

Use Cases

Build a local documentation search system that finds relevant code examples and API references using natural language queries. Index research paper collections to enable semantic search across academic literature stored locally. Integrate with AI agents for retrieval augmented generation that grounds responses in local knowledge bases.

Related Topics

Information retrieval, vector search, semantic search, BM25 algorithm, document indexing, and RAG systems.

Important Notes

Requirements

Local storage for index files and vector embeddings with sufficient disk space. Computing resources for generating embeddings and processing queries efficiently. The qmd CLI tool installed with required dependencies for indexing and search operations.

Usage Recommendations

Do: reindex documents periodically when your content changes to keep search results current and accurate. Use hybrid search mode for general-purpose applications since it handles both keyword and semantic queries well. Enable reranking when result quality matters more than query latency for critical search applications.

Don't: index extremely large document collections without checking disk space requirements first. Expect instant indexing for huge datasets since embedding generation takes time. Use semantic search exclusively without fallback to keyword search for queries with specific technical terms, identifiers, or version numbers where exact matching is more reliable.

Limitations

Indexing large document collections requires significant disk space for storing vectors and index structures. Query performance depends on index size and may slow down with millions of documents. Embedding model quality affects semantic search relevance and may miss domain-specific terminology.