name: progressive-memory description: "群聊漸進式記憶披露協議。當 Agent 需要在群聊/團隊/專案協作場景中訪問歷史記憶時啟用。避免 Agent 一次性載入所有記憶或跳過索引直接讀子目錄。不適用：單次無群聊場景的標準問答。"

Progressive Memory — 漸進式披露協議

Agent 在群聊中訪問記憶時必須遵守的分層披露協議：先讀索引，再按需逐層載入。

核心規則

1. 入口管制

• 群聊記憶的唯一入口是 memory/groups/{group_name}.md（索引檔案）
• 禁止直接讀取 memory/groups/{group_name}/ 下的任何子檔案
• 禁止繞過索引直接 memory_search 子目錄
• 群名對映規則：Matrix room ID（如 !xxx:matrix.example.com）需先查 memory/group_names.json 對映為友好名稱 {group_name} 後再用

2. 五步載入流程

Step 0 是新增步驟：每次進入群聊記憶時，必須先執行群名對映，將 Matrix 原始 room ID 轉為友好名稱，再進行後續檔案操作。 群名對映檔案 group_names.json 格式：{room_id}: {name, display_name}

每次只匹配一個最匹配的檔案（優先順序最高）。

3. 載入紀律

• 單會話最多 2 個 P0-P2 檔案 + 1 個 P3 檔案
• conventions/ 一次只加載 1 個
• attention.md 標記「已歸檔」時，只加載 project.md
• 切換群聊時先清理舊上下文，再重新走 Step 1

4. 更新回寫

• 新決策 → 追加 experience.md
• 任務狀態變化 → 更新 attention.md
• 索引檔案只增不刪（刪除時標記 [DEPRECATED]）

檔案結構

memory/groups/
├── {group_name}.md          # L0: 入口+閥門（必讀）
└── {group_name}/            # 群聊私有記憶（禁止直接訪問）
    ├── attention.md       # P0: 當前聚焦
    ├── project.md         # P1: 專案靜態資訊
    ├── experience.md      # P2: 經驗/決策日誌
    ├── people.md         # P3: 人員畫像
    └── conventions/       # L3: 細分規範
        ├── api.md
        ├── db.md
        └── ...

命名規範：所有檔案和目錄一律使用友好名稱 {group_name}，禁止直接使用 Matrix room ID（如 !xxx:matrix.example.com）。通過 memory/group_names.json 做 ID → 名稱對映。

優先順序定義

反模式速查

❌ 一次載入索引所有引用檔案     → ✅ 每次只加載一個
❌ 跳過索引直接讀子檔案         → ✅ 先載入索引
❌ 同時載入兩個群聊            → ✅ 切換時清理再過載
❌ 全文載入 experience.md      → ✅ 搜尋命中後片段載入

索引檔案模板

---
group_name: your-group    # 來自 group_names.json 的對映名稱
last_updated: YYYY-MM-DD
status: active
memory_budget: 6000
---

# {Group Name} — 漸進式披露索引

> ⚠️ 本檔案是訪問此群聊記憶的**唯一合法入口**。

## Hard Rules

- 規則1
- 規則2

## 路由索引

| 觸發場景 | 載入檔案 | 優先順序 |
|---------|---------|--------|
| 當前任務、Sprint、阻斷項 | `attention.md` | P0 |
| 技術棧、架構約束 | `project.md` | P1 |
| 歷史決策、踩坑記錄 | `experience.md` | P2 |
| 人員分工、聯絡方式 | `people.md` | P3 |
| API 開發細節 | `conventions/api.md` | P2-L3 |

5. Memory Flush — 週期性記憶沖刷 ⭐

本協議的第四條規定了"手動更新"，本擴充套件規定了自動週期性沖刷。

漸進式披露解決了"讀什麼"，這個擴充套件解決"什麼時候寫、寫什麼"。

5.1 沖刷觸發時序

關鍵設計：/remem 在會話活躍時觸發，hook 拿到的是當前 session 的完整上下文，而不是空狀態。

5.1a 預設配置

⚠️ 為什麼不用 /new hook？

內建 memory-flush hook 監聽 command:new（即 /new），但存在根本性衝突：

1. /new 的語義是建立新 session
2. Hook 在 /new 觸發時，新 session 已建立，舊 session 的上下文已丟失
3. Hook 拿到的 previousSessionEntry 在新 session 建立後可能已經不可訪問
4. 結果：hook 執行了，但沒有任何歷史內容可沖刷，命令被靜默吞掉

解決方案：自定義 remem-flush hook 監聽 message:received，在訊息層攔截 /remem。此時 session 仍然活躍，完整上下文可用。

5.1b remem-flush Hook 安裝

Hook 檔案已打包在 skill 目錄中，安裝時需複製到 OpenClaw hooks 目錄：

# Skill 包內路徑（安裝後位於 skill 目錄）
# hooks/remem-flush/
#   ├── HOOK.md       # 後設資料 + 文件
#   └── handler.js    # 處理邏輯

# 安裝命令（從 skill 目錄複製）
cp -r hooks/remem-flush/ ~/.openclaw/hooks/remem-flush/

安裝後目錄結構：

~/.openclaw/hooks/remem-flush/
├── HOOK.md       # 後設資料 + 文件
└── handler.js    # 處理邏輯

注意：內建 memory-flush hook 必須停用（enabled: false），否則 /new 會被它攔截且失敗。

5.1c precompact-remem Hook（可選，推薦安裝）

自動在 session context 壓縮前執行 memory flush，無需人工觸發：

# 安裝
cp -r hooks/precompact-remem/ ~/.openclaw/hooks/precompact-remem/
7w4.net小蔥技能。

安裝後需在 OpenClaw 中啟用：

openclaw hooks enable precompact-remem

兩個 hook 互補： - remem-flush — 使用者手動 /remem 觸發 - precompact-remem — 自動在 context 壓縮前觸發（推薦開啟）

5.2 沖刷內容判定

✅ 值得寫

❌ 不寫

5.3 寫回規範

• experience.md：追加-only，按時間倒序，每條含 YYYY-MM-DD 標記、背景、決策、執行
• attention.md：直接覆蓋舊狀態（任務進度是事實性更新，不是日誌）
• project.md、people.md：增補為主，刪除需顯式確認
• group_names.json：發現新成員或角色變化時可追加，不做破壞性更新

5.4 沖刷狀態檔案

引入 memory/flush-state.json 追蹤沖刷狀態：

{
  "last_flush_time": "2026-05-15T07:30:00+08:00",
  "attention_last_updated": "2026-05-15T07:00:00+08:00",
  "experience_last_appended": "2026-05-15T06:00:00+08:00",
  "context_usage_at_flush": 45,
  "pending_items": ["確認張三是新 PM"],
  "session_id": "last-session-id"
}

使用規則： - 每次沖刷後更新 last_flush_time - pending_items 儲存暫未確認但值得留意的線索 - 下次沖刷時先處理 pending_items 再掃增量

5.5 與漸進式披露的配合

        讀：Progressive Disclosure        寫：Memory Flush
              ↓                                ↓
        索引 → 按需載入                會話增量 → 寫回檔案
              ↓                                ↓
         省 token + 精準讀取            不丟資訊 + 自動維護
              ↓                                ↓
              └── 組成完整記憶閉環 ←───────────┘

在載入檔案後，應向 HUMAN 說明該檔案的上次沖刷時間（如 attention.md 上次更新: 2026-05-14，當前會話有 2 項任務狀態變更待刷）

完整協議清單

1. 入口管制 — 索引唯一入口，禁止直接讀子目錄
2. 五步載入流程 — 群名對映 → 路由定位 → 意圖匹配 → 顯式載入 → 子層控制 → 預算熔斷
3. 載入紀律 — 2+1 檔案限制，切換清除
4. 手動更新回寫 — 新決策/狀態變更立即寫回
5. Memory Flush — /remem 觸發（推薦）+ Cron 兜底（06:17 & 18:17）
6. Auto-Flush — precompact-remem hook 在 session compaction 前自動執行 flush

這個 Skill 質量很好，設計思路清晰，使用體驗流暢。它能幫 Agent 聰明地讀取記憶（按需載入、不丟資訊），還能自動儲存會話內容，不用手動操心。文件通俗易讀，上手成本低。美中不足的是初次配置需要了解一些背景知識，對新手不太友好。整體值得推薦。