📌 项目地址：tobi/qmd | ⭐ 25,775 颗星 | 🔧 TypeScript | 📜 MIT
为什么需要另一个搜索工具？
我之前搜本地Markdown笔记，全靠 grep -r 加上文件名联想。问题是：想找“怎么部署服务”，但你只记得模糊的概念，不记得具体关键词。或者笔记里写的是“上线步骤”，你搜“deploy”就漏了。QMD 解决的就是这类问题。
它由 Shopify 联合创始人 Tobias Lütke 开发，GitHub 上 25775 个星。纯 TypeScript，MIT 许可证。所有搜索和索引都在本地运行，不调外部 API。
三层搜索，按需选
QMD 提供三条命令，对应三种不同的搜索策略：
qmd search "project timeline" # BM25全文检索，最快，只做字面匹配
qmd vsearch "how to deploy" # 语义搜索，把query和文档都转成向量再算相似度
qmd query "quarterly planning process" # 混合+LLM重排序，质量最高但最慢search用 BM25，适合搜已知术语（比如函数名、日期）。vsearch靠本地 embedding 模型（首次运行自动下载几百MB的GGUF文件），“上线”、“发布流程”、“deploy steps”能命中同一批文档。query同时跑关键词和语义，用RRF（倒数排序融合）合并候选，再调本地LLM对结果重新打分。我一般写周报需要引经据典时用它。
注意：query 依赖本地LLM，首次使用会自动下载模型文件。如果不想要这个依赖，只用前两条命令也能工作。
上下文树：QMD真正独特的设计
这是 QMD 和普通向量数据库、全文检索引擎最大的区别。你给每个集合附加一段描述，当搜索结果返回文档时，这段描述也会附带。用 --json 输出时，每个结果都带 context 字段。
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"假设你搜“authentication”，返回两个文档：一个在 qmd://docs（上下文“Work documentation”），一个在 qmd://notes（上下文“Personal notes and ideas”）。如果你写技术文档，显然优先看前者。如果你的AI代理在整理文档，这个 context 字段让它立刻知道该选哪个，不需要猜目录结构。
README 里写：“Don’t sleep on it”。我觉得这确实是最有实用价值的功能——很多人把笔记乱放，有了上下文树，搜索结果自带来源说明，省了后面的人工（或AI）判断。
输出格式：专门为AI代理设计的
QMD 默认输出人类可读的文本，但为LLM提供了结构化版本：
# 返回JSON，方便解析
qmd search "authentication" --json -n 10
# 只输出文件路径，不低于0.4分
qmd query "error handling" --all --files --min-score 0.4
# 获取文档全文（不加--full默认只返回片段）
qmd get "docs/api-reference.md" --full获得文档内容也有几种方式：
qmd get "meetings/2024-01-15.md" # 按路径
qmd get "#abc123" # 按docid（搜索结果里会显示）
qmd multi-get "journals/2025-05*.md" # 按glob模式批量获取如果你在写Agent（比如让AI自动整理会议记录），--json 输出结构固定，--files 只给路径减少token消耗，--min-score 过滤低分结果。配合 --all 可以拿到所有匹配项，不被默认的top N限制。
MCP服务器：让Claude直接操作你的笔记库
QMD 内置了一个 MCP（Model Context Protocol）服务器，暴露四个工具：
query：搜索，支持lex（关键词）、vec（语义）、hyde三种子查询get：按路径或docid查文档，带模糊匹配建议multi_get：批量检索status：索引健康和集合信息
如果你用 Claude Desktop，在 claude_desktop_config.json 里加一段：
{
"mcpServers": {
"qmd": {
"command": "qmd",
"args": []
}
}
}之后Claude可以直接调用 query 工具搜你的笔记。相比让AI自己解析命令行输出，MCP集成的好处是参数固定、返回值结构化，不会因为输出格式变化导致解析失败。
快速上手
# 全局安装
npm install -g @tobilu/qmd
# 或
bun install -g @tobilu/qmd把笔记目录注册为集合：
qmd collection add ~/notes --name notes
qmd collection add ~/Documents/meetings --name meetings
qmd collection add ~/work/docs --name docs然后生成向量索引：
qmd embed首次运行会下载 embedding 模型文件（几百MB），之后只处理新增和修改的文件。索引建好后就能搜索了。
对我个人来说，最大的变化是：以前要找某次架构评审的记录，得翻文件夹猜文件名；现在直接 qmd vsearch "上周的架构评审"，结果精确。项目是MIT许可证，所有模型和代码都跑在本地，不担心隐私。
一些细节
- 所有搜索命令都支持
-c <collection>限定范围，比如qmd search "API" -c notes。 --all返回全部匹配项，不截断；--min-score过滤低分结果。- 上下文树可以嵌套（README 说“works as a tree”），你可以在父集合上加描述，子集合会自动继承？但官方文档没展开，我建议你试一下。
- MCP服务器默认暴露所有命令，你也可以只用命令行告诉AI代理去执行
qmd search --json。
最后，README 里反复强调“Don’t sleep on it”的上下文树，值得你认真配置。给你的每个笔记目录写一段简洁的描述，后面搜索收益翻倍。
===
标签：笔记搜索，语义检索，本地AI，MCP服务器