tobi

qmd

AI#LLM#Search Engine#Vector Database#Node.js #RAG

132

// summary

QMD is an on-device search engine that indexes markdown notes, documentation, and transcripts for efficient local retrieval. It utilizes a hybrid approach combining BM25 full-text search, vector semantic search, and LLM-based re-ranking to deliver high-quality results. The tool is designed for agentic workflows, offering both a command-line interface and an MCP server for seamless integration with AI agents.

// technical analysis

QMD is an on-device search engine designed to index and retrieve information from personal knowledge bases, such as markdown notes and documentation, using a hybrid architecture that combines BM25 full-text search, vector semantic search, and LLM-based re-ranking. By running locally via node-llama-cpp and GGUF models, it solves the challenge of maintaining private, agent-ready search capabilities without relying on external cloud APIs. The project employs a sophisticated retrieval pipeline featuring Reciprocal Rank Fusion (RRF) and position-aware blending, which balances the precision of keyword matching with the contextual understanding of semantic search to ensure high-quality results for agentic workflows.

// key highlights

Implements a hybrid search pipeline that combines BM25, vector embeddings, and LLM re-ranking for superior retrieval accuracy.

Provides a native MCP (Model Context Protocol) server to enable seamless integration with AI agents like Claude Desktop and Claude Code.

Supports AST-aware code chunking using tree-sitter to improve search relevance within programming language source files.

Allows users to define hierarchical context metadata, which helps LLMs make better decisions when selecting relevant documents.

Offers a flexible SDK for Node.js and Bun, enabling developers to embed the search engine directly into custom applications.

Features a local-first design that keeps all data and model processing on-device, ensuring privacy and offline functionality.

// use cases

Performing hybrid searches across personal knowledge bases using keyword, semantic, and LLM-reranked queries.

Integrating local document retrieval into AI agent workflows via the Model Context Protocol (MCP).

Managing and indexing diverse document collections with descriptive context to improve search relevance and LLM decision-making.

// getting started

To begin, install the tool globally using 'npm install -g @tobilu/qmd' or 'bun install -g @tobilu/qmd'. Once installed, create a collection from your local directory using 'qmd collection add [path] --name [name]', then run 'qmd embed' to generate the necessary search indexes. You can then perform searches using 'qmd search' for keywords, 'qmd vsearch' for semantic queries, or 'qmd query' for the full hybrid experience.