QMD — 本地知識庫搜尋
QMD 是使用者工作區的本機向量+關鍵字搜尋引擎。在回答那些可能已被記錄的疑問之前，請先使用它——尤其是關於人員、專案、決策與過往工作的脈絡資訊。
工作流程
工作流程永遠是：
- 搜尋候選文件。
- 使用
qmd get或qmd multi-get擷取完整來源。 - 根據擷取的文字回答，並引用路徑或文件 ID。
當使用者需要事實、決策、引述或細微差別時，請不要僅根據片段回答。片段只是線索。
在回報你擷取的內容時，一個簡潔的備註就夠了；除非必要，否則不要貼上整個檔案：
Retrieved: #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 "decision quality depends on surfacing assumptions and context" -n 10
結構化查詢（困難搜尋）：
qmd query $'intent: Find the concept note about metrics as instruments without letting OKRs replace judgment.\nlex: cockpit instruments OKR Goodhart metrics judgment\nvec: data informed not metric driven product judgment\nhyde: A concept note says metrics are useful like cockpit instruments, but leaders should remain data-informed rather than metric-driven because OKRs and dashboards can Goodhart product judgment.'
結構化查詢欄位：
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。
按代理分類的集合
每個代理都有自己的 QMD 索引，並採用 XDG 隔離設定。代理清單位於 ${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 | 其他代理的持久知識庫（按代理劃分的工作區）— 主代理可以直接查詢專家的持久知識。 |
handoffs-* | 按代理劃分的交接檔案（main、dev 與任何其他代理） |
專家集合提示
以下集合名稱來自各個專家代理自己的 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 "standup notes this week" -c agents-dev-memory -n 10
qmd query "GenAI project status" -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": "what is the current state of the challenger crew project" }
],
"intent": "Find project status, not general concepts about crew.",
"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 # CLI 替代方案，用於編輯 index.yml
qmd context add qmd://notes "Description" # CLI 替代方案，用於在 index.yml 中的 context:
qmd update # 重新索引集合
qmd embed # 產生/重建向量
qmd status # 變更後的健康檢查