QMD

QMD 是一款完全在设备端运行的搜索引擎，专为开发者和知识工作者设计。它能索引你的 Markdown 笔记、会议记录、项目文档和知识库，支持关键词搜索与自然语言查询，并可无缝集成到 AI 智能体工作流中。

所有处理——包括全文检索、语义向量搜索和 LLM 重排序——均通过 node-llama-cpp 调用 GGUF 模型在本地完成，无需联网，不上传数据。

核心能力

• 混合检索引擎：结合 BM25 全文搜索、向量语义搜索与 LLM 重排序；
• 纯本地运行：模型自动下载并缓存于本地，数据永不离开设备；
• 智能体友好：输出格式（JSON、文件列表等）专为 LLM 工作流设计；
• MCP 协议支持：可通过 Model Context Protocol 与 Claude、OpenClaw 等代理深度集成；
• 上下文感知：支持为不同目录添加语义描述，提升搜索相关性。

快速上手

1. 安装

# 需要 Bun >= 1.0.0
bun install -g https://github.com/tobi/qmd

macOS 用户需额外安装支持扩展的 SQLite：

brew install sqlite

2. 添加知识源

# 创建集合
qmd collection add ~/notes --name notes
qmd collection add ~/Documents/meetings --name meetings
qmd collection add ~/work/docs --name docs

# 为集合添加上下文（帮助理解内容）
qmd context add qmd://notes "个人笔记与想法"
qmd context add qmd://meetings "会议记录与纪要"
qmd context add qmd://docs "工作文档"

3. 生成嵌入

qmd embed  # 首次使用时自动下载模型（约 2GB）

4. 开始搜索

qmd search "项目时间轴"        # 快速关键词匹配（BM25）
qmd vsearch "如何部署服务"     # 语义相似度搜索
qmd query "季度规划流程"      # 混合搜索 + LLM 重排序（推荐）

三种搜索模式

query 模式采用 倒数排名融合（RRF） + 位置感知重排序，确保：

• 精确匹配结果不被稀释；
• 高排名结果保留原始检索权重；
• 低置信度结果由 LLM 二次校准。

与 AI 智能体集成

QMD 的输出专为自动化设计：

# 获取结构化结果供 LLM 使用
qmd search "身份验证" --json -n 10

# 列出所有相关文件（带分数阈值）
qmd query "错误处理" --all --files --min-score 0.4

# 获取完整文档内容
qmd get "docs/api-reference.md" --full

支持 MCP 协议（推荐）

在 ~/.claude/settings.json 中添加：

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

或通过插件安装（Claude Code）：

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

之后，AI 代理可直接调用 qmd_search、qmd_get 等工具，实现“自主查阅本地知识库”。

高级功能：HTTP 长驻服务

默认 MCP 以子进程方式启动，每次调用需加载模型。若频繁使用，可启用 HTTP 守护进程：

# 启动后台服务（端口 8181）
qmd mcp --http --daemon

# 停止
qmd mcp stop

# 查看状态
qmd status

服务启动后，LLM 模型常驻内存，后续请求响应更快（空闲 5 分钟后释放嵌入上下文，模型仍保留）。

任意 MCP 客户端可连接 http://localhost:8181/mcp。

技术细节

模型依赖（首次使用自动下载）

缓存路径：~/.cache/qmd/models/

数据存储

索引保存在 SQLite 数据库：~/.cache/qmd/index.sqlite
包含：

• 文档元数据与 6 位哈希 ID；
• FTS5 全文索引；
• sqlite-vec 向量索引；
• LLM 缓存（避免重复计算）。

文档按 800 个 token 分块，15% 重叠，确保上下文连贯。

实用命令速查

# 列出集合
qmd collection list

# 重新索引
qmd update

# 批量获取文件
qmd multi-get "journals/2025-05*.md" --json

# 清理缓存
qmd cleanup

# 查看索引状态
qmd status

为什么选择 QMD？

• 隐私优先：所有数据和模型均在本地，无云依赖；
• 精准可控：通过上下文和集合管理，明确区分“个人笔记”与“工作文档”；
• 智能体原生：从 CLI 到 MCP，为 AI 自主操作而设计；
• 开源免费：MIT 许可，可审计、可修改、可自托管。

对于重度依赖本地知识库的开发者、研究者或 AI 工作流构建者，QMD 提供了一种高效、安全、可编程的检索基础设施。