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/

安装后需在 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