介绍
# 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 ```
### 保持索引最新
设置 cron 任务或钩子以自动重新索引。例如，每天早上 5 点重新索引：
```bash # 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` 回答 "我磁盘上的笔记/文档里有什么？"。