agent-memory

# 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. **写入文件**：追加到目标文件，格式： ```markdown ### [YYYY-MM-DD] 条目标题 内容描述。 --- ``` 4. **新文件处理**：如果目标文件不存在 - 创建文件，写入标题和说明 - 更新 `INDEX.md`，在对应分类中添加条目 5. **更新日志**：追加到 `LOG.md` ```markdown ## [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. **生成更新提案**：列出具体修改项，格式： ```markdown ## 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 一致性