- name
- memory-guard
- description
- 记忆卫士 — 防止AI Agent记忆断层的安全网。每次session启动时自动扫描所有记忆文件，检测遗漏、验证连续性、生成健康报告。基于真实记忆断层事件设计。
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. 🚨 断层预警
当检测到记忆断层时：
🚨 记忆断层警告！
⚠️ 发现以下问题：
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个仓库文件
- 今早完全失忆
根因：
- 只读取了
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（必须）
2. 列出所有新创建的文件
3. 记录所有重要事件
4. 记录所有错误和教训
5. git提交
6. 运行 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记忆断层事件* *"永远不要再问昨天我做了什么"*