mcpField
Q
qmd

qmd

github.com/levineam生产力706953 次安装35 周前更新
代码仓库

关于 qmd

qmd 是面向 Markdown 笔记、文档和知识库的本地搜索工具，供需要检索本地文件的用户和 Agent 使用。它提供关键词、语义及混合搜索，并可按集合筛选和读取文档。

主要功能

  1. 01BM25 关键词搜索
  2. 02向量语义搜索
  3. 03混合搜索与重排
  4. 04按集合筛选结果
  5. 05读取单篇或多篇文档

适用场景

  1. 01查找本地笔记中的相关内容
  2. 02从 Markdown 集合检索文档
  3. 03按关键词或语义查找资料

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/levineam/qmd-skill --skill qmd

安装后在 Claude Code 中输入/qmd确认已加载。

附带文件README.md

详细介绍

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 也没问题：分块依据内容（每块大约几百个 token），而非严格遵循标题或结构。
  • 它不能替代代码搜索；搜索代码仓库或源代码树时，请使用代码搜索工具。

搜索模式

  • qmd search（默认）：快速关键词匹配（BM25）
  • qmd vsearch（最后手段）：语义相似度（向量）。通常会在向量检索前执行本地大模型操作，因此速度较慢。
  • qmd query（通常跳过）：混合搜索 + 大模型重排。通常比 vsearch 更慢，也可能超时。

性能说明

  • qmd search 通常能即时返回结果。
  • 在某些机器上，qmd vsearch 可能需要约 1 分钟，因为查询扩展可能会在每次运行时将本地模型（例如 Qwen3-1.7B）加载到内存中；向量检索本身通常很快。
  • qmd query 会在 vsearch 的基础上添加大模型重排，因此速度可能更慢，也不太适合交互式使用。
  • 如果需要反复进行语义搜索，可以考虑让进程或模型保持运行（例如，在你的设置支持时使用长时间运行的 qmd/MCP 服务模式），而不是每次都调用冷启动的大模型。

常用命令

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 <num>：结果数量
  • -c, --collection <name>：限定搜索范围为某个文档集
  • --all --min-score <num>：返回所有分数高于阈值的匹配项
  • --json / --files：适合 Agent 使用的输出格式
  • --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/Agent 环境支持内置调度器，也可以在那里运行相同命令，而不是使用系统 cron。

模型和缓存

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

与 Clawdbot 记忆搜索的关系

  • qmd 搜索你的本地文件（笔记 / 文档），也就是你明确添加到文档集中的内容。
  • Clawdbot 的 memory_search 搜索Agent 记忆（之前交互中保存的事实 / 上下文）。
  • 两者都可以使用：用 memory_search 查询“之前我们决定了什么 / 学到了什么？”，用 qmd 查询“我的磁盘笔记 / 文档里有什么？”。

评论

支持 Markdown