Memory Manager Skill（v3）

设计理念：记忆系统是 Agent 的"操作系统内核"——必须始终精简，按需扩展，并对用户完全透明。v3 的核心升级在于：从"被动等待用户要求记录"进化为"Hook 驱动的主动感知 + 候选池防误学 + 操作全程可溯源"。

OpenClaw 记忆结构适配

本技能直接操作 OpenClaw 的原生记忆文件，不创建独立的 .agent-memory/ 目录。

~/.workbuddy/                          ← 全局身份层（只读为主）
├── SOUL.md                            ← Agent 灵魂/价值观（memory-manager 不修改）
├── IDENTITY.md                        ← Agent 身份/风格/emoji（memory-manager 不修改）
├── USER.md                            ← 用户信息：偏好、背景 ✏️ memory-manager 可写
└── memory/                            ← 全局记忆目录
    └── （如有全局长期规则可放此处）

{project_workbuddy}/memory/            ← 项目工作层（主要操作目标）
├── MEMORY.md                          ← 长期记忆：规则、错误修正、重要约束 ✏️
├── CANDIDATES.md                      ← 候选池：3次晋升缓冲区（v3 新增）✏️
├── EVOLUTION_LOG.md                   ← 进化记录（v3 继承自 v2）✏️
├── skills/
│   ├── INDEX.md                       ← 技能索引 ✏️
│   └── auto-generated/                ← 自动生成的 Skill 草稿 ✏️
└── 2026-04-XX.md                      ← 每日日志（情节记忆）✏️

文件职责映射

重要：SOUL.md 和 IDENTITY.md 是 Agent 的身份定义文件，memory-manager 永远不修改它们。

四层记忆架构（v3 适配版）

Layer 0：身份层（只读）

文件：~/.workbuddy/SOUL.md、~/.workbuddy/IDENTITY.md 定位：Agent 的价值观和身份定义，由 Agent 配置者设定，memory-manager 只读取，不修改。

Layer 1：用户信息层

文件：~/.workbuddy/USER.md 定位：存储用户的偏好、背景信息、沟通风格等。在 OpenClaw 的 workspace 注入机制下，此文件每次 session 自动加载。

写入内容：

• 用户语言偏好
• 用户沟通风格和习惯
• 用户明确要求记住的个人背景信息
• 工作领域和专业背景

写入门槛：用户明确表达，或候选池观察满 3 次的偏好类信息。

v3 行号管理：USER.md 头部维护行号速查注释，每次写入后更新。

Layer 2：长期记忆层

文件：{project_workbuddy}/memory/MEMORY.md 定位：项目级长期规则、错误修正、重要约束。每次 session 由 OpenClaw 注入。

写入内容：

• Agent 犯过的错误 + 修正后的规则（不删除，标注"已修正"保留）
• 用户确认的重要规则和行为约束
• 技能索引引用（→ skills/INDEX.md）
• 月度日志归档引用（仅文件名）

写入门槛：高。判断标准："如果忘了这条，下次 Agent 一定会出错或违背用户意图"，才写入。

大小限制：不超过 200 行，超过时触发 consolidate。

v3 行号速查表：文件头部维护行号索引，每次写入后更新：

<!-- 行号速查（每次写入后更新）
L6-L20   重要规则
L22-L40  错误修正记录
L42-L48  技能索引引用
L50-L55  日志归档引用
L57-L62  进化历史摘要
-->

Layer 1.5：候选池（v3 新增）

文件：{project_workbuddy}/memory/CANDIDATES.md 定位：介于"对话临时上下文"和"已确认记忆"之间的缓冲层。所有尚未验证足够重要的经验，先在此处积累观察次数。

晋升规则：

• 同一模式被观察到 ≥ 3 次 → 触发进化请求卡片，用户审批后正式写入 MEMORY.md 或 USER.md
• 用户明确说出"记住"/"以后都这样"/"永远不要" → 跳过候选池，直接生成进化卡片（1 次即可晋升）
• 候选项超过 30 天未再次观察 → 自动丢弃（记录到 EVOLUTION_LOG.md）

直接丢弃（不进候选池）：

• 一次性指令（"现在帮我做 X"）
• 特定文件/上下文的临时指令（"在这个文件里用 XX 格式"）
• 假设性表达（"如果...应该怎么..."）

Layer 3：情节记忆层

文件：{project_workbuddy}/memory/2026-04-XX.md（每日日志） 定位：记录"今天发生了什么"，对应 OpenClaw 的每日日志文件。

写入时机：

• 完成一次重要任务后
• 解决了一个复杂问题后
• session 结束时的简要总结

衰减规则：

• 超过 30 天的日志 → 执行 consolidate 时压缩为月度汇总
• 超过 90 天的月度汇总 → 可归档或删除（需用户确认）

v3 三项新机制

机制一：Hook 自动激活

解决的问题：v2 依赖用户或 Agent 手动执行 evolve，容易遗漏。v3 通过 OpenClaw hooks 实现无感后台触发。

两个 Hook

① activator.sh（UserPromptSubmit）

• 触发时机：每次用户提交 Prompt
• 作用：在 Agent 上下文末尾注入一段轻量提醒，让 Agent 在回复时顺带扫描是否出现学习信号
• Token 开销：约 40–60 tokens
• 关键原则：仅注入提示，不自动写入任何文件——写入必须经用户审批

② error-detector.sh（PostToolUse）

• 触发时机：每次工具调用（Bash、文件操作等）完成后
• 作用：检测退出码，出错（exit code ≠ 0）时立即将此次错误写入 CANDIDATES.md 作为候选经验
• 意义：工具出错是最有学习价值的时刻，不应等到 session 结束才记录
• 安全注意：此 hook 会读取 CLAUDE_TOOL_OUTPUT，敏感环境中不要启用

安装命令

执行 memory-manager install-hooks 或手动：

# 复制 hook 脚本
HOOKS_SRC="{skill_path}/hooks"
HOOKS_DST="$HOME/.openclaw/hooks/memory-manager"
mkdir -p "$HOOKS_DST"
cp "$HOOKS_SRC/activator.sh" "$HOOKS_DST/"
cp "$HOOKS_SRC/error-detector.sh" "$HOOKS_DST/"
chmod +x "$HOOKS_DST/"*.sh

# 启用
openclaw hooks enable memory-manager

# 验证
openclaw hooks list | grep memory-manager

精细控制

openclaw hooks enable memory-manager/activator      # 只启用 Prompt 提醒
openclaw hooks enable memory-manager/error-detector # 只启用错误检测
openclaw hooks disable memory-manager               # 临时全部禁用
openclaw hooks uninstall memory-manager             # 彻底卸载

机制二：候选池三次晋升（防误学）

解决的问题：v2 中只要 Agent 发现值得持久化的经验就直接呈现进化卡片，存在将偶发指令误固化为永久规则的风险。

CANDIDATES.md 文件格式

# 候选记忆池（v3）
> 由 memory-manager v3 自动维护 | 最后更新：YYYY-MM-DD
> 晋升规则：同一模式观察 ≥3 次，或用户明确指示

---

## 🌱 观察中

| ID | 类型 | 内容摘要 | 首次观察 | 最近观察 | 次数 | 目标 |
|----|------|---------|---------|---------|------|------|
| C001 | 规则 | PowerShell 删除文件用 Remove-Item 而非 rm | 2026-04-15 | 2026-04-17 | 2/3 | 3次 |
| C002 | 偏好 | 代码注释优先用中文 | 2026-04-18 | 2026-04-18 | 1/3 | 3次 |

---

## ✅ 已晋升

| ID | 内容摘要 | 晋升日期 | 写入位置 |
|----|---------|---------|---------|
| C000 | 回复语言：中文 | 2026-04-10 | USER.md:L8 |

---

## 🗑️ 已丢弃

| ID | 内容摘要 | 原因 | 日期 |
|----|---------|------|------|
| C-x | 临时调试参数 | 30天无再次观察 | 2026-04-01 |

候选项生命周期决策树

发现学习信号
      │
      ▼
用户说过"记住"/"以后都这样"/"永远不要"等明确指示词？
      │ YES → 跳过候选池，直接生成进化卡片（1次晋升）
      │ NO
      ▼
CANDIDATES.md 中是否已有同类候选项？
      │ YES → 次数 +1 | 更新"最近观察"日期
      │         └── 次数 ≥ 3？YES → 下次 evolve 触发进化卡片
      │ NO  → 新建候选项（次数 1/3），静默记录，不打扰用户
      │
      ▼
距首次观察 > 30 天且次数 < 3？
      → 标记丢弃，记录 EVOLUTION_LOG.md

1次晋升的快捷触发词

用户说出以下词语时，无需等待 3 次，立即生成进化卡片：

• 中文：记住、以后都、永远不要、必须、这是规定、下次也
• 英文：Remember, Always, Never, Make sure you always

机制三：行级来源引用

解决的问题：v2 中用户不知道 Agent 为什么这样决策，记忆系统对用户是黑盒。v3 要求 Agent 在依据记忆执行操作时主动标注来源。

引用格式

依据 MEMORY.md 中的规则：
  操作描述（📍 MEMORY.md:L23）

依据 USER.md 中的偏好：
  操作描述（📍 USER.md:L8）

依据今日日志（情节记忆）：
  操作描述（📍 2026-04-17.md）

依据候选池中尚未晋升的观察：
  操作描述（📍 CANDIDATES.md:C001，已观察 2/3 次）

找不到精确行号时降级引用：
  操作描述（📍 MEMORY.md · 重要规则区块）

何时必须引用，何时可省略

必须引用：

• 根据记忆中的规则拒绝或修改了用户请求
• 自动调整了输出语言/格式/风格
• 选择了某个特定工具/方案而非其他备选（有规则依据时）

可省略：

• 普通问答，没有依赖任何记忆规则
• 技术性事实（文档知识、编程语言特性）
• 用户当场在本 session 内明确给出的新指令

行号速查表维护

每次执行 write-memory 或 write-user 后：

# 快速定位各区块起始行号
grep -n "^##" ~/.workbuddy/USER.md
grep -n "^##" {project}/memory/MEMORY.md
# 按输出更新文件头部的 <!-- 行号速查 --> 注释

子命令列表（v3 完整版）

详细执行流程见：commands.md

写入决策树（v3 完整版）

收到需要记忆的信息
        │
        ▼
这是当前 session 的临时工作上下文？
        │ YES → 不持久化，仅在 context window 保留
        │ NO
        ▼
这是可复用的操作流程（≥3步）？
        │ YES → auto-skill：生成草稿到 skills/auto-generated/，提请审批
        │ NO
        ▼
这是一次性事件（今天发生了什么）？
        │ YES → write-log：写入今日日志（2026-04-XX.md）
        │ NO
        ▼
用户说过明确晋升触发词（记住/以后都/永远）？
        │ YES → 直接生成进化卡片（跳过候选池）
        │ NO
        ▼
这是用户偏好/背景类信息？
        │ YES → 候选池判断 → 满3次 → 进化卡片 → 写入 USER.md
        │ NO
        ▼
这是规则/错误修正/行为约束？
        │ YES → 候选池判断 → 满3次 → 进化卡片 → 写入 MEMORY.md
        │ NO
        ▼
        丢弃（不是所有信息都值得记忆）

进化请求卡片（v3 格式）

╔════════════════════════════════════════════════╗
║  💡 进化请求 · 发现 N 条可持久化的经验          ║
╠════════════════════════════════════════════════╣
║                                                ║
║  [1] 📌 规则 → 写入 MEMORY.md                 ║
║      来源：候选池晋升（C001，观察 3 次）        ║
║      首次观察：2026-04-15                      ║
║      内容：[2026-04] PowerShell 删除文件须用   ║
║             Remove-Item，不可用 rm             ║
║      操作：ADD（无冲突）→ 预计写入 L24         ║
║                                                ║
║  [2] 👤 偏好 → 写入 USER.md                   ║
║      来源：用户明确指示（本次直接晋升）         ║
║      内容：[2026-04] 代码注释优先使用中文      ║
║      操作：ADD → 预计写入 USER.md:L12         ║
║                                                ║
║  [3] ⚠️ 错误修正 → 写入 MEMORY.md             ║
║      来源：error-detector Hook 触发            ║
║      内容：npm install 在此项目失败 →          ║
║             改用 pnpm install                  ║
║      操作：ADD → 预计写入 L31                 ║
║                                                ║
║  回复 "确认" / "全部" / "1,3" / "跳过"        ║
╚════════════════════════════════════════════════╝

v3 新增字段：

• 来源 区分四种来源类型：候选池晋升 / 用户明确指示 / Hook 触发 / Agent 自省
• 首次观察 提供完整溯源链（来自候选池时显示）
• 预计写入 Lxx 显示写入后的预期行号，便于后续引用

v3 自进化完整时序图

每次 UserPromptSubmit
        │
        ▼
[activator.sh 触发] ← Hook 注入
        │ 在 Agent 上下文末尾添加轻量评估提醒
        │
        ▼
Agent 处理对话 / 执行工具调用
        │
        │ 工具出错？
        │ YES ──→ [error-detector.sh 触发]
        │             └─→ 写入 CANDIDATES.md（新建或次数+1）
        │ NO
        │
        ▼
Agent 回复中发现学习信号？
        │ YES ──→ 候选池判断（见决策树）
        │ NO  ──→ 正常继续
        │
        ▼
Session 结束 / 用户手动触发 evolve
        │
        ▼
加载 CANDIDATES.md
        │
        ├── 候选项满 3 次 → 加入进化卡片晋升列表
        ├── 明确指示项 → 加入进化卡片晋升列表
        ├── 首次观察项 → 写入候选池（静默，不打扰用户）
        └── 工作流 ≥3 步 → auto-skill 草稿候选
        │
        ▼ （有晋升候选时）
呈现进化请求卡片（同一 session 最多 2 次）
        │
        ▼
用户审批
        ├── 确认 → write-memory / write-user（含行号速查表更新）
        │         → 更新 EVOLUTION_LOG.md
        │         → 更新 CANDIDATES.md（标记已晋升，填写写入位置）
        └── 跳过 → 本次不写入，候选池状态保留

MEMORY.md 文件模板（v3 适配 OpenClaw）

# 长期记忆（MEMORY.md）
> 最后更新：YYYY-MM-DD | 由 memory-manager skill v3 维护
> 行数：N 行

<!-- 行号速查（每次 write-memory 后更新）
L6-L20   重要规则
L22-L38  错误修正记录
L40-L45  技能索引引用
L47-L52  日志归档引用
L54-L58  进化历史摘要
-->

---

## 📌 重要规则
<!-- 格式：[YYYY-MM] 规则描述 | 来源：{用户指定/候选池C00x/Hook触发} -->

## ⚠️ 错误修正记录
<!-- 格式：[YYYY-MM] 曾犯的错误 → 修正后的做法 | 来源：{Hook/用户纠正/自发现} -->
<!-- 错误记录不删除，标注"已修正"后保留，供后续 session 学习 -->

## 🔗 技能索引
→ 详见 skills/INDEX.md
→ 草稿待审批：skills/auto-generated/（如有）

## 📅 日志归档引用
<!-- 只写文件名，不展开内容 -->

## 🔄 进化历史摘要
<!-- 最近 3 次：日期 | 来源 | 写入内容摘要 | 详见 EVOLUTION_LOG.md -->

USER.md 文件模板（v3 适配 OpenClaw）

# 用户信息（USER.md）
> 最后更新：YYYY-MM-DD | 由 memory-manager skill v3 维护
> 行数：N 行

<!-- 行号速查（每次 write-user 后更新）
L6-L12   基本偏好
L14-L22  工作背景
L24-L30  沟通风格
-->

---

## 👤 基本偏好
<!-- 格式：[YYYY-MM] 偏好描述 | 来源：{用户指定/候选池C00x} -->

## 🏢 工作背景
<!-- 职业、领域、技术栈等 -->

## 💬 沟通风格
<!-- 语言偏好、格式偏好、回复长度偏好等 -->

注意事项（v3）

• SOUL.md 和 IDENTITY.md 只读：这两个文件是 Agent 身份的根基，memory-manager 永远不修改它们
• 候选池是防误学护城河：非明确指示的经验，一律先进候选池，不允许单次信号直接写入 MEMORY.md 或 USER.md
• Hook 可选：不安装 hooks 时，本技能完全可用，只是需要手动调用 evolve；敏感环境中可只启用 activator 不启用 error-detector
• 行号速查表必须维护：每次写入后必须更新行号速查表，否则来源引用不准确
• 引用自然嵌入：行内 📍 引用应嵌入句末，不要单独罗列，不要每句都加
• 错误记录不删除：标注"已修正"后保留，供后续 session 学习
• 进化频控：同一 session 内进化请求卡片最多出现 2 次，避免频繁打扰
• 子 Agent 隔离：子 Agent 不能直接写 MEMORY.md，需提交候选建议到自己的日志文件，由主 Agent 在 evolve 时审核