介绍
# qmd - Quick Markdown Search
用于 Markdown 笔记、文档和知识库的本地搜索引擎。一次索引，快速搜索。
## 何时使用（触发短语）
- "search my notes / docs / knowledge base" - "find related notes" - "retrieve a markdown document from my collection" - "search local markdown files"
## 默认行为（重要）
- 优先使用 `qmd search` (BM25)。它通常是即时的，应该作为默认选择。 - 仅当关键词搜索失败且你需要语义相似性时才使用 `qmd vsearch`（在冷启动时可能会非常慢）。 - 除非用户明确想要最高质量的混合结果并且能忍受较长的运行时间/超时，否则避免使用 `qmd query`。
## 前置条件
- Bun >= 1.0.0 - macOS: `brew install sqlite` (SQLite extensions) - 确保 PATH 包含: `$HOME/.bun/bin`
安装 Bun (macOS): `brew install oven-sh/bun/bun`
## 安装
`bun install -g https://github.com/tobi/qmd`
## 设置
```bash 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` (最后手段): 语义相似性 (向量)。由于向量查找前的本地 LLM 计算，通常较慢。 - `qmd query` (通常跳过): 混合搜索 + LLM 重排序。通常比 `vsearch` 更慢，并且可能会超时。
## 性能说明
- `qmd search` 通常是即时的。 - `qmd vsearch` 在某些机器上可能需要约 1 分钟，因为查询扩展可能会在每次运行时将本地模型（例如 Qwen3-1.7B）加载到内存中；向量查找本身通常很快。 - `qmd query` 在 `vsearch` 之上增加了 LLM 重排序，因此对于交互式使用来说可能更慢且更不可靠。 - 如果你需要反复进行语义搜索，考虑保持进程/模型热身（例如，如果你的设置支持，使用长生命周期的 qmd/MCP 服务器模式），而不是每次都调用冷启动的 LLM。
## 常用命令
```bash 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`: 代理友好的输出格式 - `--full`: 返回完整文档内容
## 检索
```bash 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 ```
## 维护
```bash qmd status # Index health qmd update # Re-index changed files qmd embed # Update embeddings ```
## 保持索引最新
自动化索引，以便在添加/编辑笔记时结果保持最新。
- 对于关键词搜索 (`qmd search`)，`qmd update` 通常就足够了（速度快）。 - 如果你依赖语义/混合搜索 (`vsearch`/`query`)，你可能还需要 `qmd embed`，但这可能会很慢。
示例计划 (cron):
```bash # 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` 回答"我的磁盘笔记/文档里有什么？"。