# Agent Memory

> 跨Agent全局记忆库管理工具。支持 remember（写入）、recall（查询）、archive（归档洞察）、hygiene（健康检查）、upgrade（自我更新）五个指令。所有记忆以 Markdown 文件存储，人类可直接编辑。

- Skill: `lucianwhy/agent-memory` (Agent Skill, multi-file: 8 files)
- Install (CLI): `npx skillmds@latest add lucianwhy/agent-memory`
- Raw SKILL.md: https://api.skillmd.com/api/skills/lucianwhy/agent-memory/raw
- Safety review: pending (external: skill-scanner PASS, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: lucianwhy (https://skillmd.com/u/lucianwhy)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/lucianwhy/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 一致性