名称： qmd
描述： 本地混合搜索 Markdown 笔记与文档。适用于搜索笔记、查找相关内容或从已索引的集合中检索文档。
主页： https://github.com/tobi/qmd
元数据： {"clawdbot":{"emoji":"🔍","os":["darwin","linux"],"requires":{"bins":["qmd"]},"install":[{"id":"bun-qmd","kind":"shell","command":"bun install -g https://github.com/tobi/qmd","bins":["qmd"],"label":"通过 Bun 安装 qmd"}]}}

qmd - 快速 Markdown 搜索

用于 Markdown 笔记、文档和知识库的本地搜索引擎。一次索引，快速搜索。

使用场景（触发短语）

• “搜索我的笔记/文档/知识库”
• “查找相关笔记”
• “从我的集合中检索 Markdown 文档”
• “搜索本地 Markdown 文件”

默认行为（重要）

• 优先使用 qmd search (BM25)。它通常是即时的，应作为默认选择。
• 仅当关键词搜索失败且需要语义相似性时，才使用 qmd vsearch（冷启动可能非常慢）。
• 除非用户明确要求最高质量的混合结果并能容忍较长的运行时间/超时，否则避免使用 qmd query。

前提条件

• Bun >= 1.0.0
• macOS: brew install sqlite (SQLite 扩展)
• 确保 PATH 包含: $HOME/.bun/bin

安装 Bun (macOS): 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 "此集合的描述"  # 可选
qmd embed  # 一次性执行以启用向量 + 混合搜索

索引内容

• 专为 Markdown 集合设计（通常为 **/*.md）。
• 经测试，“杂乱”的 Markdown 文件也能处理：分块基于内容（大约每块几百个词元），而非严格的标题/结构。
• 不适用于代码搜索；对于仓库/源码树，请使用专门的代码搜索工具。

搜索模式

• qmd search (默认): 快速关键词匹配 (BM25)
• qmd vsearch (最后手段): 语义相似性（向量）。由于在向量查找前需进行本地 LLM 处理，通常较慢。
• qmd query (通常跳过): 混合搜索 + LLM 重排序。通常比 vsearch 更慢，且可能超时。

性能说明

• qmd search 通常是即时的。
• qmd vsearch 在某些机器上可能需要约 1 分钟，因为查询扩展可能每次运行都会将本地模型（例如 Qwen3-1.7B）加载到内存中；向量查找本身通常很快。
• qmd query 在 vsearch 基础上增加了 LLM 重排序，因此可能更慢，对于交互式使用可靠性较低。
• 如果需要重复进行语义搜索，建议保持进程/模型预热（例如，在您的设置中启用长生命周期的 qmd/MCP 服务器模式），而不是每次调用冷启动的 LLM。

常用命令

qmd search "查询"             # 默认
qmd vsearch "查询"
qmd query "查询"
qmd search "查询" -c notes     # 搜索特定集合
qmd search "查询" -n 10        # 返回更多结果
qmd search "查询" --json       # JSON 输出
qmd search "查询" --all --files --min-score 0.3

实用选项

• -n <数量>: 返回结果数量
• -c, --collection <名称>: 限制在特定集合内搜索
• --all --min-score <数值>: 返回高于阈值的所有匹配项
• --json / --files: 适合代理处理的输出格式
• --full: 返回完整的文档内容

检索

qmd get "path/to/file.md"       # 完整文档
qmd get "#docid"                # 通过搜索结果中的 ID 检索
qmd multi-get "journals/2025-05*.md"
qmd multi-get "doc1.md, doc2.md, #abc123" --json

维护

qmd status                      # 索引状态
qmd update                      # 重新索引已更改的文件
qmd embed                       # 更新嵌入向量

保持索引最新

设置 cron 任务或钩子以自动重新索引。例如，每天凌晨 5 点重新索引：

# 通过 Clawdbot cron（独立作业，静默运行）：
clawdbot cron add \
  --name "qmd-reindex" \
  --cron "0 5 * * *" \
  --tz "America/New_York" \
  --session isolated \
  --message "运行: export PATH=\"\$HOME/.bun/bin:\$PATH\" && qmd update && qmd embed" 

# 或通过系统 crontab：
0 5 * * * export PATH="$HOME/.bun/bin:$PATH" && qmd update && qmd embed

这确保您的笔记库搜索能随着笔记的添加或编辑保持最新。

模型与缓存

• 使用本地 GGUF 模型；首次运行会自动下载。
• 默认缓存目录: ~/.cache/qmd/models/ (可通过 XDG_CACHE_HOME 覆盖)。

与 Clawdbot 记忆搜索的关系

• qmd 搜索您的本地文件（笔记/文档），这些文件您已显式索引到集合中。
• Clawdbot 的 memory_search 搜索代理记忆（从先前交互中保存的事实/上下文）。
• 两者结合使用：memory_search 用于“我们之前决定/学到了什么？”，qmd 用于“我的磁盘笔记/文档中有什么？”。