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对于“我的磁盘上的笔记/文档里有什么？”。