⚡

qmd-QuickMarkdownSearch qmd

本地Markdown笔记和文档的快速搜索引擎，适用于需要快速检索和查找相关内容的场景。

数据分析 0 次安装 0 次浏览 更新于 3/5/2026

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

在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 "这个收藏的描述"  # 可选
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 <num>: 结果数量
  • -c, --collection <name>: 限制在收藏中
  • --all --min-score <num>: 返回所有高于阈值的匹配项
  • --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                       # 更新嵌入

保持索引新鲜

自动化索引，以便在添加/编辑笔记时结果保持最新。

  • 对于关键词搜索（qmd search），qmd update通常足够（快速）。
  • 如果你依赖于语义/混合搜索（vsearch/query），你可能还需要qmd embed，但它可能很慢。

示例计划（cron）：

# 每小时增量更新（保持BM25新鲜）：
0 * * * * export PATH="$HOME/.bun/bin:$PATH" && qmd update

# 可选：每晚嵌入刷新（可能很慢）：
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用于"我的笔记/文档磁盘上有什么？”。