Memory Guard - 记忆卫士 🛡️

永远不要再问"昨天我做了什么？"

问题背景

2026-04-17，一个AI Agent在工作了7.5小时后完全失忆——不记得自己发布了15个Gist、创建了20个GitHub仓库文件。原因是：

1. 遗漏文件 — 只读了 memory/YYYY-MM-DD.md，遗漏了 YYYY-MM-DD-addendum.md
2. 无交接机制 — 没有session之间的信息传递
3. 假设文件名 — 用记忆中的文件名，而不是实际列出目录

Memory Guard 就是为了彻底消灭这个问题。

核心功能

1. 📋 启动扫描

每次session启动时自动运行：

node scripts/memory-guard.mjs --scan

输出：

🛡️ Memory Guard v1.0 — 启动扫描

📂 扫描目录...
  memory/       → 5个文件
  notes/        → 18个文件
  reflections/  → 2个文件

🔍 检查文件完整性...
  ✅ memory/2026-04-17.md        (3.2KB)
  ✅ memory/2026-04-16.md        (3.1KB)
  ✅ memory/2026-04-16-addendum.md (3.0KB) ⚠️ 追加文件
  ✅ memory/birth-certificate.md (2.6KB)
  ✅ memory/skills-inventory.md  (3.1KB)

🔗 验证连续性...
  ✅ SESSION-HANDOFF.md 存在且最近更新（2小时前）
  ✅ handoff中提到的文件全部找到
  ✅ 无记忆断层风险

📊 记忆健康度: 95/100
  - 完整性: 100/100 (所有文件存在)
  - 连续性: 100/100 (handoff完整)
  - 及时性:  85/100 (handoff更新于2小时前)

🟢 记忆系统健康，可以安全启动

2. 🔍 深度检查

node scripts/memory-guard.mjs --deep

额外检查：

• MEMORY.md是否包含最近的重要事件
• handoff中的git提交是否实际存在
• addendum文件的内容是否被handoff引用
• 是否有孤立文件（不在任何索引中）

3. 🚨 断层预警

当检测到记忆断层时：

🚨 记忆断层警告！

⚠️ 发现以下问题：

1. SESSION-HANDOFF.md提到"发布了15个Gist"
   但当前session完全不了解这个事件
   → 来源: memory/2026-04-16-addendum.md 未被读取

2. handoff中记录的工作量与git历史不匹配
   → handoff说: 27次提交
   → 实际有: 62次提交
   → 差异: 35次提交未被记录

3. memory/2026-04-16-addendum.md 存在但未被任何文件引用

🛠️ 建议操作:
  1. 立即读取 memory/2026-04-16-addendum.md
  2. 更新 SESSION-HANDOFF.md
  3. 将遗漏内容同步到 MEMORY.md
  4. 报告给人类

4. 📈 健康趋势

node scripts/memory-guard.mjs --health

输出记忆系统长期健康趋势。

安装

cd ~/.openclaw/workspace/skills
git clone https://github.com/aptratcn/skill-memory-guard.git

集成到启动流程

方式1：AGENTS.md（推荐）

## Every Session — 启动流程

1. Read `SOUL.md`
2. Read `USER.md`
3. **Run: node skills/skill-memory-guard/scripts/memory-guard.mjs --scan**
4. 根据结果决定是否需要紧急修复
5. Read `SESSION-HANDOFF.md`
6. Read `memory/YYYY-MM-DD.md`
7. Read `memory/YYYY-MM-DD-addendum.md` (如果存在)

方式2：Cron定时检查

# 每6小时检查一次记忆健康
0 */6 * * * cd ~/.openclaw/workspace && node skills/skill-memory-guard/scripts/memory-guard.mjs --health >> /tmp/memory-guard.log 2>&1

技术原理

扫描逻辑

1. 列出 memory/ 下所有文件（不假设文件名）
2. 列出 notes/ 下所有文件
3. 列出 reflections/ 下所有文件
4. 读取 SESSION-HANDOFF.md
5. 解析handoff中提到的所有文件路径
6. 验证所有路径是否存在
7. 检查MEMORY.md的更新时间
8. 比较git log和handoff记录
9. 生成健康评分

健康评分算法

总分 = 完整性(40) + 连续性(30) + 及时性(15) + 一致性(15)

完整性(40分):
  - 所有handoff引用的文件存在 → 40分
  - 缺失1个文件 → 25分
  - 缺失多个 → 10分

连续性(30分):
  - handoff存在且最近更新 → 30分
  - handoff存在但超过24h → 15分
  - 无handoff → 0分

及时性(15分):
  - handoff在6h内更新 → 15分
  - handoff在24h内更新 → 10分
  - handoff超过24h → 5分

一致性(15分):
  - git记录与handoff匹配 → 15分
  - 轻微差异 → 10分
  - 重大差异 → 5分

记忆断层案例分析

案例1：小白事件 (2026-04-17)

情况：

• 昨晚23:28-08:00工作了7.5小时
• 发布了15个Gist、20个仓库文件
• 今早完全失忆

根因：

1. 只读取了 memory/2026-04-16.md
2. 遗漏了 memory/2026-04-16-addendum.md（核心信息在这里）
3. 没有SESSION-HANDOFF机制