介绍
# 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 扩展) - 确保 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` 查询"磁盘上的笔记/文档里有什么？"。