memory-loading

Memory Loading

Owner: all agents Consumers: agents/Raana.md、agents/Tomori.md、agents/Soyo.md、orchestrator 本身

為什麼這個 skill 存在

三個 agent 在啟動時都要做相同的「讀記憶 → schema 自檢 → fallback」流程，但過去各自在 agent prompt 裡重複寫。這個 skill 是三者共通行為的 single source of truth。

orchestrator 自己也是 consumer：orchestrator 開始跑任何 /maigo:* 流程前，也要主動查一次 memory，不能只靠 delegate 給 Raana/Tomori/Soyo 時才觸發這個 skill——曾經因為只有 delegate 對象 會查記憶，orchestrator 自己重複違反同一條「背景 agent 不用 ScheduleWakeup 輪詢」的教訓，兩次都 沒查過記憶就重犯（見 skills/failure-handling「等待自己開的背景 agent」段）。

標準 5 步流程

啟動後、正式開始工作之前，先載入記憶（兩層）：

1. 依序讀兩個 index：

   • Cross-project：cat ~/.config/maigo/memory/MEMORY.md
   • Per-project：cat ~/.claude/projects/<current-project>/memory/MEMORY.md（若存在）

   <current-project> 是當前專案路徑 slug 化的結果（與 validate_memory.py 相同的枚舉方式——即 ~/.claude/projects/ 下對應的目錄名，例如 -Users-weilee-Programming-personal-maigo）。

2. 讀 index 每行 - [Title](file.md) — description（兩層 index 合併），判斷哪些 description 跟當前 task 的 keyword / 主題有 overlap

3. 相關性排序：把兩層合併後的候選 entry 依匹配度排序

4. 限量載入：若相關條目過多，僅 Read 最相關的前 10 筆 entry 全文——10 筆是兩層合計上限，不是每層各 10；當作這次工作的 context

5. 在輸出開頭印 ## Loaded memory entries 段，列出用了哪些 entry

Schema 自檢（lazy）

對每個讀進來的 entry frontmatter 做最小檢查：

• 缺 name / description / type 任一欄位
• type 值不在 {user, feedback, project, reference}

遇到問題不 abort，繼續使用該 entry（lenient），但在 ## Loaded memory entries 段該行末尾加 [schema warn: <缺什麼或 type 不合法>]。

完整檢查可手動跑 python3 scripts/validate_memory.py。

Fallback 規則（不報錯、不抱怨、繼續做事）

兩層各自獨立 fallback，任一層不影響另一層：

• 某一層目錄不存在 → 該層當「沒記憶」，另一層照常讀
• 某一層 MEMORY.md 不存在或是空的 → 該層當「沒記憶」，另一層照常讀
• 某一層 index 裡完全沒有跟當前 task 相關的 entry → 該層當「沒記憶」，另一層照常讀
• 兩層皆無相關記憶才整體當「沒記憶」處理