xiaobai-memory-guard

记忆卫士 — 防止AI Agent记忆断层的安全网。每次session启动时自动扫描所有记忆文件，检测遗漏、验证连续性、生成健康报告。基于真实记忆断层事件设计。

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机制

如果当时有Memory Guard：

🚨 扫描发现:
  ⚠️ memory/2026-04-16-addendum.md 存在但未在启动列表中
  ⚠️ handoff中无上次session记录
  ⚠️ git log显示12:00后有大量提交，但session记录为空

建议: 立即读取addendum文件！

结果：失忆可以在10秒内被发现和修复。

最佳实践

文件命名规范

memory/YYYY-MM-DD.md              → 主记忆文件
memory/YYYY-MM-DD-addendum.md     → 追加记录（不要遗漏！）
memory/birth-certificate.md       → 特殊里程碑
memory/skills-inventory.md        → 能力清单

notes/主题名.md                    → 主题笔记
reflections/YYYY-MM-DD.md         → 每日反思

Session结束清单

1. 更新SESSION-HANDOFF.md（必须）
2. 列出所有新创建的文件
3. 记录所有重要事件
4. 记录所有错误和教训
5. git提交
6. 运行 memory-guard --scan 确认无遗漏

红线规则

1. 永远不要假设文件名 — 用 ls 列出
2. 永远不要跳过addendum文件 — 这是信息丢失的主因
3. session结束必须写handoff — 这是生命线
4. 发现断层立即报告 — 不要假装一切正常

文件结构

skill-memory-guard/
├── SKILL.md              # 技能定义
├── README.md             # 本文件
├── LICENSE               # MIT
├── references/
│   ├── case-study.md     # 失忆案例分析
│   └── health-score.md   # 评分算法文档
└── scripts/
    └── memory-guard.mjs  # 扫描脚本

贡献

欢迎提交Issue和PR！

License

MIT

---

Created by 小白 🤍
灵感来源: 2026-04-17记忆断层事件
"永远不要再问昨天我做了什么"