QMD — 本地知识库搜索
QMD 是用户工作区内的本地矢量+关键词搜索引擎。在回答可能已有文档记录的问题时务必使用它——尤其是涉及人物、项目、决策和过往工作的上下文。
工作流程
工作流程始终为：
- 搜索候选文档。
- 使用
qmd get或qmd multi-get检索完整源文档。 - 根据检索到的文本回答，并引用路径或文档 ID。
当用户需要事实、决策、引用或细微差别时，不要仅凭片段回答。片段只是线索。
在报告检索结果时，给出简洁的说明即可；除非必要，不要粘贴整份文件：
检索结果：#abc123 wiki/projects/GenAICategorizer.md, #def432 memory/2026-05-26.md
选择正确的搜索模式
| 模式 | 命令 | 使用时机 |
|---|---|---|
| BM25 关键词 | qmd search | 精确词汇、标题、名称、代码符号、罕见短语 |
| 混合+重排序 | qmd query | 间接措辞、概念性回忆、最佳质量 |
| 结构化查询 | 包含 lex:/vec:/hyde: 字段的 qmd query | 需要精确锚点加语义回忆的困难搜索 |
简单查找：
qmd search "challenger crew project status" -n 10
qmd search '"GenAI Categorizer"' -c wiki-main -n 5
语义概念查找：
qmd query "决策质量取决于揭示假设和上下文" -n 10
结构化查询（困难搜索）：
qmd query $'intent: 查找关于作为工具的指标的概念说明，不要让 OKR 取代判断。\nlex: 仪表盘 OKR 古德哈特 指标 判断\nvec: 数据驱动而非指标驱动 产品判断\nhyde: 一份概念说明表明指标如同仪表盘一样有用，但领导者应保持数据知情而非指标驱动，因为 OKR 和仪表盘会损害产品判断。'
结构化查询字段：
intent:说明你要查找什么以及要避免什么。lex:确切的术语、别名、标题和罕见词汇。vec:用自然语言转述该想法。hyde:描述能够满足请求的文档或答案。
检索源文档
qmd get "#abc123" # 通过搜索结果中的文档 ID
qmd get "wiki/projects/GenAICategorizer.md" --full # 通过路径
qmd multi-get "#abc123,#def432" --md # 通过文档 ID 批量获取
qmd multi-get 'memory/2026-05-*.md' -l 80 # 通配符批量获取
在比较多个命中结果或跨页面收集上下文时，使用 multi-get。当确切的源文档至关重要时，使用 --full。
按代理划分的集合
每个代理都有自己基于 XDG 隔离配置的 QMD 索引。代理列表位于 ${OPENCLAW_HOME}/config/agents.map。当从 CLI 搜索时，请使用代理的 XDG 包装器：
# 主代理
XDG_CONFIG_HOME=${OPENCLAW_HOME}/agents/main/qmd/xdg-config XDG_CACHE_HOME=${OPENCLAW_HOME}/agents/main/qmd/xdg-cache qmd query "..."
# 开发代理和任何其他代理——相同模式，替换代理名称
主代理集合
| 集合 | 包含内容 |
|---|---|
identity-main | 核心文档 — SOUL、IDENTITY、TOOLS、AGENTS、NETWORK、MEMORY 索引 |
wiki-main | 持久知识库。 Wiki — 代理行为（跨代理规则）、项目、工具、概念、人员。自 2026-05-28 起为主要持久记忆存放地。 |
memory-main | 每日记忆文件 (YYYY-MM-DD.md) — 7 天捕获层，将内容提升到 wiki-main |
workspace-docs-main | 完整工作区 Markdown（参考、任务、交接、学习记录） |
skills-main | 技能定义文件 (SKILL.md 文件) |
agents-*-identity | 其他代理的根身份/配置文档（按代理划分的工作区） |
agents-*-memory | 其他代理的每日记忆文件（按代理划分的工作区） |
agents-*-wiki | 其他代理的持久 Wiki（按代理划分的工作区）——主代理可以直接查询专业代理的持久知识。 |
handoffs-* | 按代理划分的交接文件（包含主代理、开发代理和任何其他代理） |
专业代理集合提示
以下集合名称来自各专业代理自身的 QMD 配置。从主代理来看，请使用跨代理等效项（agents-<agent>-wiki、agents-<agent>-memory）。
| 你要查找的内容 | 代理 | 关键集合（在该代理内） | 从主代理的角度 |
|---|---|---|---|
| 代码项目、构建配置、工程决策 | dev | projects-dev、identity-dev、wiki-dev | agents-dev-wiki、agents-dev-memory |
上下文和集合范围限定
QMD 的 context: 元数据（在 index.yml 中设置或通过 qmd context add 设置）通过描述每个集合包含的内容来提高搜索相关性。该元数据会与搜索结果一起返回。
当宽泛的查询偏离到错误的语料库时，请使用 -c 限定搜索范围：
qmd search "本周站会记录" -c agents-dev-memory -n 10
qmd query "GenAI 项目状态" -c wiki-main -c projects-dev -n 10
省略 -c 以搜索所有内容。
诊断
qmd status # 集合计数和待处理的嵌入
qmd update # 重新索引（在向索引路径添加/编辑文件后使用）
qmd embed # 在更新后生成/重建矢量
如果 qmd query 或 qmd vsearch 失败（模型/GPU 不可用），请回退到使用更强词汇项的 qmd search。
注意：旧文档引用了 qmd doctor——当前 CLI 版本中不存在此子命令。使用 qmd status 进行健康检查，使用 qmd update/qmd embed 进行修复。
MCP 工具
当使用 MCP（OpenClaw 代理的默认方式）时，优先使用结构化查询：
{
"searches": [
{ "type": "lex", "query": "challenger crew status" },
{ "type": "vec", "query": "challenger 团队项目当前状态如何" }
],
"intent": "查找项目状态，而非关于团队的一般概念。",
"limit": 10
}
注意事项
- 不要止步于片段。 在做出断言之前，务必获取完整文档。
- 不要过度使用语义搜索。 如果你知道确切的标题或术语，BM25 速度更快，且效果通常更好。
- 不要随意变更索引。
qmd collection add、qmd update和qmd embed会更改本地状态，并可能消耗大量资源。 - 模型支持的命令可能对环境敏感。 如果
qmd query或重排序失败，请回退到使用更强词汇项的qmd search。 - 用户措辞模糊时需要意图。 添加
intent:字段，而不是指望查询扩展能猜对正确的领域。 - 集合名称很重要。 当查询可能匹配多个领域时，使用
-c限定范围。 - 时效性： QMD 不会衰减旧结果。对于时间敏感的记忆，请检查文件名——YYYY-MM-DD 越靠近今天的日期越新。
设置与维护
仅在要求时运行这些命令。搜索和检索是安全的；索引变更并非随意操作。
qmd collection add ~/notes --name notes # 编辑 index.yml 的 CLI 替代方案
qmd context add qmd://notes "描述信息" # 设置 index.yml 中 context 的 CLI 替代方案
qmd update # 重新索引集合
qmd embed # 生成/重建矢量
qmd status # 更改后的健康检查