qmd — Mini CLI Search Engine for Your Docs and Knowledge Bases

Introduction

qmd is a lightweight CLI search engine that indexes your local documents, meeting notes, knowledge bases, and other text files. It tracks current state-of-the-art retrieval approaches while being entirely local — no data leaves your machine.

What qmd Does

• Indexes local directories of Markdown, text, PDF, and other document formats
• Provides fast full-text and semantic search from the command line
• Maintains an incremental index that updates as files change
• Returns ranked results with contextual snippets
• Works entirely offline with no cloud dependencies

Architecture Overview

qmd is a TypeScript application that builds a local search index over your documents. It combines traditional full-text indexing with modern embedding-based semantic search for high-quality retrieval. The index is stored locally and updated incrementally when files change. Search queries run against both indexes and results are merged using a hybrid ranking strategy. The CLI outputs results with highlighted snippets and relevance scores.

Self-Hosting & Configuration

• Install globally via npm or download a standalone binary
• Index any directory with qmd index <path>
• Configure which file types to include/exclude in .qmdrc
• Set the embedding model for semantic search (local or API-based)
• Index auto-updates on subsequent runs — only changed files are reprocessed

Key Features

• Hybrid search combining full-text and semantic retrieval
• Fully local — no data sent to external services
• Incremental indexing for fast updates on large document collections
• Supports Markdown, plain text, PDF, and common document formats
• Minimal setup with sensible defaults

Comparison with Similar Tools

• grep/ripgrep — pattern matching on raw text; qmd provides ranked semantic search
• Elasticsearch — enterprise search server; qmd is a lightweight local CLI tool
• Obsidian Search — built into the Obsidian app; qmd works across any directory
• RAGFlow — full RAG pipeline with LLM; qmd focuses on retrieval, not generation

FAQ

Q: How large a document collection can qmd handle? A: It is designed for personal and team-scale collections (thousands to tens of thousands of documents). It is not built for enterprise-scale corpora.

Q: Does it require a GPU for semantic search? A: No. It can use small local embedding models that run on CPU. Optionally, you can configure an API-based embedder for higher quality.

Q: Can I use it with AI coding agents? A: Yes. The JSON output mode makes it easy for agents to query your docs programmatically.

Q: Is it open source? A: Yes. qmd is fully open source and available on GitHub.

Sources

• https://github.com/tobi/qmd