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 "Description of this collection"  # optional
qmd embed  # one-time to enable vector + hybrid search

索引内容

• 适用于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 "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 <数量>：结果数量
• -c, --collection <名称>：限制在某个集合内
• --all --min-score <数值>返回所有高于阈值的匹配项
• --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 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。

模型与缓存

• 使用本地GGUF模型；首次运行时会自动下载。
• 默认缓存路径：~/.cache/qmd/models/（可通过XDG_CACHE_HOME环境变量覆盖）。

与Clawdbot记忆搜索的关系

• qmd搜索的是您本地文件（笔记/文档）中显式索引到集合的内容。
• 而Clawdbot的memory_search搜索的是代理记忆（来自先前交互的保存事实/上下文）。
• 两者可结合使用：memory_search用于查询“我们之前决定/学习了什么？”，qmd对于“我磁盘上的笔记/文档里有什么内容？”。