📦 Xiaobai Memory Guard记忆卫士 — Xiaobai Memory Guard 记忆卫士

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

问题背景

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

• 遗漏文件 —— 只读了 memory/YYYY-MM-DD.md，漏掉 YYYY-MM-DD-addendum.md
• 无交接机制 —— session 间无信息传递
• 假设文件名 —— 凭记忆拼文件名，而非实际列目录

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. 🚨 断层预警

检测到记忆断层时：

🚨 记忆断层警告！
⚠️ 发现以下问题：
SESSION-HANDOFF.md 提到“发布了 15 个 Gist”但当前 session 完全不了解该事件
   
→ 来源: memory/2026-04-16-addendum.md 未被读取
handoff 记录的工作量与 git 历史不匹配
   
→ handoff 说: 27 次提交
   → 实际有: 62 次提交
   → 差异: 35 次提交未被记录
memory/2026-04-16-addendum.md 存在但未被任何文件引用
🛠️ 建议操作:
立即读取 memory/2026-04-16-addendum.md
更新 SESSION-HANDOFF.md
将遗漏内容同步到 MEMORY.md
报告给人类

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 — 启动流程
Read SOUL.md
Read USER.md
Run: node skills/skill-memory-guard/scripts/memory-guard.mjs --scan
根据结果决定是否需要紧急修复
Read SESSION-HANDOFF.md
Read memory/YYYY-MM-DD.md
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/ 下所有文件（不假设文件名）
列出 notes/ 下所有文件
列出 reflections/ 下所有文件
读取 SESSION-HANDOFF.md
解析 handoff 中提到的所有文件路径
验证所有路径是否存在
检查 MEMORY.md 的更新时间
比较 git log 和 handoff 记录
生成健康评分

健康评分算法

总分 = 完整性(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 个仓库文件
• 今早完全失忆

根因：

• 只读取 memory/2026-04-16.md
• 遗漏 memory/2026-04-16-addendum.md（核心信息在此）
• 无 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（必须）
列出所有新创建的文件
记录所有重要事件
记录所有错误和教训
git 提交
运行 memory-guard --scan 确认无遗漏

红线规则

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

文件结构

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 记忆断层事件 "永远不要再问昨天我做了什么"