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

保持索引更新

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

# Via Clawdbot cron (isolated job, runs silently):
clawdbot cron add \
  --name "qmd-reindex" \
  --cron "0 5 * * *" \
  --tz "America/New_York" \
  --session isolated \
  --message "Run: export PATH=\"\$HOME/.bun/bin:\$PATH\" && qmd update && qmd embed" 

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