用途
qmd（Quick Markdown Search）是一个本地搜索引擎，用于搜索 Markdown 笔记、文档和知识库。它的定位是“一次索引，快速搜索”，适合在本地 Markdown 集合中查找笔记、发现相关内容，或从已索引的集合中取回文档。
典型触发场景包括：搜索我的笔记 / 文档 / 知识库、查找相关笔记、从我的集合中取回某个 Markdown 文档、搜索本地 Markdown 文件。
主要能力
qmd 提供三种搜索模式：
- qmd search（默认）：快速关键词匹配（BM25），通常即时返回，应作为默认选择。
- qmd vsearch（最后手段）：语义相似度（向量）搜索。仅在关键词搜索失败、需要语义相似时使用；冷启动时可能非常慢。
- qmd query（一般跳过）：混合搜索加 LLM 重排序。通常比 vsearch 更慢，可能超时，除非用户明确需要最高质量的混合结果并能容忍长时间运行。
检索方面，qmd 支持按路径取回完整文档、按搜索结果中的文档 ID 取回，以及用通配符批量取回多个文档。
维护方面，qmd 提供索引健康状态查看、重新索引已变更文件、更新嵌入向量等命令。
索引对象
qmd 面向 Markdown 集合（常见掩码为 **/*.md）。根据资料中的测试，结构“凌乱”的 Markdown 也可以处理：分块基于内容（大约每块几百个 token），而不是严格依赖标题或结构。它不是代码搜索的替代品；仓库和源码树应使用代码搜索工具。
安装与前置条件
前置条件：
- Bun >= 1.0.0
- macOS：brew install sqlite（SQLite 扩展）
- 确保 PATH 包含：$HOME/.bun/bin
- 在 macOS 上安装 Bun：brew install oven-sh/bun/bun
安装命令：
bun install -g https://github.com/tobi/qmd
使用方式
初始化设置：
qmd collection add /path/to/notes --name notes --mask "**/*.md" qmd context add qmd://notes "Description of this collection" # optional qmd embed # one-time to enable vector + hybrid search
常用命令：
qmd search "query" # default qmd vsearch "query" qmd query "query" qmd search "query" -c notes # Search specific collection qmd search "query" -n 10 # More results qmd search "query" --json # JSON output qmd search "query" --all --files --min-score 0.3
常用选项：
- -n <num>：结果数量
- -c, --collection <name>：限定到某个集合
- --all --min-score <num>：返回阈值以上的全部匹配
- --json / --files：便于智能体使用的输出格式
- --full：返回完整文档内容
取回文档：
qmd get "path/to/file.md" # Full document qmd get "#docid" # By ID from search results qmd multi-get "journals/2025-05*.md" qmd multi-get "doc1.md, doc2.md, #abc123" --json
维护：
qmd status # Index health qmd update # Re-index changed files qmd embed # Update embeddings
性能说明
- qmd search 通常即时返回。
- qmd vsearch 在某些机器上可能耗时约 1 分钟，因为查询扩展可能每次运行都要把本地模型（例如 Qwen3-1.7B）加载进内存；向量查找本身通常很快。
- qmd query 在 vsearch 之上增加 LLM 重排序，因此可能更慢，在交互式使用中可靠性更低。
- 如果需要反复进行语义搜索，可考虑保持进程/模型常驻（例如使用可用的长驻 qmd/MCP 服务模式），而不是每次冷启动 LLM。
保持索引新鲜
可以自动化索引，使新增或编辑笔记后结果保持最新。
对于关键词搜索（qmd search），通常运行 qmd update 即可（速度快）。如果依赖语义/混合搜索（vsearch/query），可能还需要 qmd embed，但它可能较慢。
示例计划任务（cron）：
Hourly incremental updates (keeps BM25 fresh):
0 * * * * export PATH="$HOME/.bun/bin:$PATH" && qmd update
Optional: nightly embedding refresh (can be slow):
0 5 * * * export PATH="$HOME/.bun/bin:$PATH" && qmd embed
如果 Clawdbot/智能体环境支持内置调度器，也可以在其中运行同样的命令，而不使用系统 cron。
模型与缓存
qmd 使用本地 GGUF 模型；首次运行会自动下载。默认缓存位置为 ~/.cache/qmd/models/，可通过 XDG_CACHE_HOME 覆盖。
与 Clawdbot 记忆搜索的关系
qmd 搜索的是你显式索引进集合的本地文件（笔记/文档）。Clawdbot 的 memory_search 搜索的是智能体记忆（此前交互中保存的事实/上下文）。两者可以配合使用：memory_search 用于“我们之前决定/了解到什么”，qmd 用于“磁盘上的笔记/文档里有什么”。
限制
- 不用于代码搜索；仓库和源码树应使用代码搜索工具。
- 语义与混合搜索依赖本地模型，冷启动可能很慢，qmd query 可能超时。
- 需要 Bun >= 1.0.0；macOS 上需要 sqlite 扩展支持。
- 资料未提供其他平台的具体安装说明、收费或价格信息。