agent-memory

name	agent-memory
version	1.1.0
description	跨Agent全局记忆库管理工具。支持 remember（写入）、recall（查询）、archive（归档洞察）、hygiene（健康检查）、upgrade（自我更新）五个指令。所有记忆以 Markdown 文件存储，人类可直接编辑。
triggers	["记住","记忆","remember","recall","archive","hygiene","upgrade","记忆库","全局记忆","升级记忆Skill"]

Agent Memory Skill

概述

本 Skill 管理全局记忆库。所有 Agent（WorkBuddy、Claude Code、Cursor、Codex）共享同一套 Markdown 记忆文件。

核心架构基于 Karpathy LLM Wiki 方法论：

• PROTOCOL.md：控制所有 Agent 行为的 Schema
• INDEX.md：内容索引，会话开始必读
• LOG.md：时间日志，仅追加
• wiki/：LLM 维护的记忆层
• archive/：归档（超 30 天的旧记忆）

使用前：将下方所有 MEMORY_PATH 替换为你的记忆库实际路径（如 ~/agent-memory/）

---

指令

1. remember — 写入记忆

触发：用户说"记住XXX" / "记到记忆库" / 检测到重要信息

执行流程：

1. 分类：根据信息内容判断类型，确定目标文件

   • 用户偏好/身份 → wiki/preferences.md
   • API/密钥配置 → wiki/config-XXX.md
   • 项目记忆 → wiki/project-XXX.md
   • 工具记忆 → wiki/tools-XXX.md
   • 踩坑经验 → wiki/troubleshooting.md
   • 决策记录 → wiki/decision-XXX.md
   • 学习笔记 → wiki/learn-XXX.md
   • 人物关系 → wiki/people-XXX.md

2. 冲突检测：读取目标文件，检查是否有矛盾信息

   • 如果新信息与旧信息矛盾 → 在条目中标注 ⚠️ 矛盾，保留两条并注明日期
   • 如果新信息是旧信息的更新 → 标注旧条目为 [已更新见下方]，写入新条目
   • 如果无冲突 → 直接追加

3. 写入文件：追加到目标文件，格式：

   ### [YYYY-MM-DD] 条目标题
   内容描述。
   
   ---
   

4. 新文件处理：如果目标文件不存在

   • 创建文件，写入标题和说明
   • 更新 INDEX.md，在对应分类中添加条目

5. 更新日志：追加到 LOG.md

   ## [YYYY-MM-DD] ingest | 主题摘要
   - 写入 wiki/xxx.md：简要内容
   ---
   

6. 卫生检查：如果目标文件 > 2KB，提示用户"文件较大，建议执行 hygiene 压缩"

---

2. recall — 查询记忆

触发：用户说"回忆一下XXX" / "记忆库里有XXX吗" / 需要历史信息支撑当前任务

执行流程：

1. 读取 INDEX.md，定位可能相关的文件
2. 读取相关文件内容
3. 如果 INDEX.md 中未找到匹配：
   • 用 grep/ripgrep 搜索 MEMORY_PATH/wiki/ 目录中的关键词
   • 仍无结果 → 告知用户"记忆库中无此信息"
4. 综合找到的信息，带引用地回复用户
5. 更新 LOG.md：## [YYYY-MM-DD] query | 查询主题

---

3. archive — 归档对话洞察

触发：对话中产生了有价值的分析/决策/踩坑结论 / 用户说"归档这个"

执行流程：

1. 从当前对话提取有价值结论
2. 判断类型：新事实 / 新经验 / 新决策 / 新洞察
3. 按 remember 的流程写入对应 wiki 文件
4. 更新 LOG.md：## [YYYY-MM-DD] archive | 洞察摘要

与 remember 的区别：

• remember：用户主动要求记住的信息
• archive：从对话中自动发现的有价值洞察（用户未明确要求）

判断标准（什么值得归档）：

• ✅ 踩坑经验（"XXX 不支持 YYY"）
• ✅ 技术决策（"决定用方案A而非方案B，因为..."）
• ✅ 配置变更（"API key 更新"）
• ✅ 工作流优化（"发现更快的做法"）
• ❌ 临时性讨论
• ❌ 未验证的猜测
• ❌ 纯事实查询结果

---

4. hygiene — 健康检查

触发：每周一次 / 用户要求 / 文件超 2KB

执行流程：

1. 矛盾检测：扫描同一主题的多个文件，查找矛盾声明

   • 输出：⚠️ 矛盾：wiki/xxx.md 第N行 vs wiki/yyy.md 第M行

2. 孤立页面：检查 INDEX.md 中列出的文件是否被其他文件引用

   • 输出：🏝️ 孤立：wiki/xxx.md 没有入站链接

3. 缺失交叉引用：检查被提及但无独立页面的概念

   • 输出：🔗 缺失：wiki/xxx.md 提到了"YYY"但没有独立页面

4. 过时声明：检查超过 90 天未更新的条目

   • 输出：⏰ 过时：wiki/xxx.md 第N行（最后更新 YYYY-MM-DD）

5. 文件膨胀：检查 > 2KB 的文件

   • 输出：📦 膨胀：wiki/xxx.md (X KB)，建议压缩

6. 生成报告，列出所有发现，等待用户确认后执行修复

7. 更新 LOG.md：## [YYYY-MM-DD] hygiene | 检查结果摘要

---

5. upgrade — 自我更新 Skill

触发：用户说"升级记忆Skill" / "更新记忆规则" / "upgrade memory" / 发现 Skill 规则不适应实际使用

执行流程：

1. 收集变更理由：

   • 用户提出的修改需求
   • 或：分析 LOG.md 中的 remember/recall/archive/hygiene 执行记录，找出频繁失败/不适用的规则
   • 或：对比 PROTOCOL.md 与实际操作习惯的差异

2. 生成更新提案：列出具体修改项，格式：

   ## Skill 更新提案 v1.x → v1.y
   
   ### 修改项
   1. [新增/修改/删除] 具体描述
   2. ...
   
   ### 理由
   - 为什么要改
   

3. 等待用户确认：⚠️ 绝不自动修改，必须用户明确批准后才能执行

4. 执行更新：

   • 修改 SKILL.md 对应部分
   • 如涉及 PROTOCOL.md 变更，同步更新 PROTOCOL.md
   • 更新 SKILL.md 头部的 version 字段
   • 追加 LOG.md：## [YYYY-MM-DD] upgrade | v1.x → v1.y，修改N项

安全边界：

• ❌ 不能修改记忆文件内容（只改规则，不改数据）
• ❌ 不能删除指令（只能新增或修改）
• ❌ 不能降低冲突检测标准
• ✅ 可以新增分类规则
• ✅ 可以调整文件大小阈值
• ✅ 可以优化执行流程
• ✅ 可以修改触发词

---

初始化（会话开始时）

当 Skill 被加载时，自动执行：

1. 读取 MEMORY_PATH/INDEX.md
2. 读取 MEMORY_PATH/LOG.md 最近 5 条（用 grep "^## \[" LOG.md | tail -5 等效方式）
3. 读取 wiki/preferences.md（必读文件）
4. 向用户简报："记忆库已加载，共 X 个文件，最近活动：XXX"

---

注意事项

1. 不要一次加载全部文件——按需加载，控制 token 消耗
2. 冲突不静默覆盖——标注矛盾，让用户判断
3. LOG.md 仅追加——永远不修改或删除已有条目
4. 文件 > 2KB 需提示——建议用户执行 hygiene
5. 写入前先读——避免覆盖已有内容
6. 日期使用当天实际日期——不要硬编码
7. 路径使用绝对路径——确保跨 Agent 一致性