Agent 记忆系统：从理论到实战
为什么记忆必须是框架而非插件？三条实战路线：本地记忆库、记忆文件体系、Skills＋Chronicle。
开篇：为什么记忆必须是框架
这一课解决一个根本问题：Agent 的记忆到底应该做成什么样？是像装插件一样外挂一个"记忆系统"，还是从一开始就内建进框架？
以下理论来自 @sarahwooders（MemGPT / Letta 作者，2026-03-31 X thread）：她被反复问"如何把你的记忆系统接入我的代理"，她的回答是——这个问题本身没有意义。
要求把内存接入代理框架，就像要求把"驾驶功能"接入汽车。驾驶不是汽车的选配插件，它就是汽车之所以是汽车的原因。管理上下文（因此包括记忆）是代理框架的核心职责，不是外挂。
RAG ≠ 记忆
对过去会话数据做 RAG，当然可以当插件用，但检索数据只占记忆很小一部分。而且实测发现，"很难找到比 grep 更好的方法"（引自 letta.com/blog/benchmarking-ai-agent-memory）。
MemGPT 也常被误解：因为 RAG 常被贴"记忆"标签，MemGPT 常被误认成 RAG 或可插拔记忆工具。实际它是 stateful agent framework（有状态代理框架）——在"框架"一词流行之前就已存在；它的记忆能力来自框架提供的重写 prompt、管理外部状态的工具，以及框架自身的上下文管理。
框架在做的隐性决策（外部插件控制不了）
- AGENTS.md / CLAUDE.md 如何加载进上下文；
- skill 元数据如何向 agent 呈现（系统提示还是系统消息）；
- agent 能否修改自身系统指令；
- 什么能经受 compaction（上下文压缩）、什么会丢失；
- 交互是否被存储并可查询；
- 当前工作目录如何表示、暴露多少文件系统信息。
实例佐证：对 Claude Code 泄露源码的分析显示，其多级记忆层次结构是直接构建进框架的。
Letta Code 是内存优先（memory-first）的代理框架：把 agent 记忆投射到 git 支持的文件系统，后台内存子代理可同时修改该文件系统，专门做快速重写和主动内存管理。Letta 还发布了《上下文宪法》（Context Constitution），概述 agent 上下文管理的共同原则。
安装命令：
npm install -g @letta-ai/letta-code（支持 Codex 计划和 BYOK）
路线一：本地可审查的记忆库实战
理论听完了，怎么落地？第一条路线来自 @gengdaJ（Codex 元老用户，2026-06-06 X 长文）：一套存放在本地 Obsidian、可审查、可搜索的 Codex 记忆系统，8 个基础概念 ＋ 12 步运转流程 ＋ closeout / audit 自动化机制。
背景：作者此前基于 EverOS 开源记忆框架重构过半成品记忆系统（跨项目记忆、隔离 agent 记忆与用户决策、省 token、自动沉淀 skill；后加本地语义检索 EmbeddingGemma ＋ Zvec）。这次用 Fable 5（经 Zenmux API 调用，充 10 美元）给记忆系统做规划评审——Fable 5 以 4:1 发现更多 bug / 优化点。
8 个基础概念
原始记忆档案 / 事实原件：人可读可改，Git 记录每一次变化。
入口导航地图：先读索引再深入，省 token。
全文搜索索引卡片：关键词检索。
语义 / 向量检索：按"意思"找记忆，配合 EmbeddingGemma 本地语义检索。
修改记录与回滚保险。
任务结束后的自动整理员：查变更 → 敏感信息检查 → 查长度 → 查重 → 刷新 SQLite / Zvec 索引 → 写日志 → scoped commit（只提交本轮记忆文件）。
定期体检医生：只列问题，不自动改。三层触发：closeout 时若超 7 天未体检顺手跑一次；macOS 每周一 10:30 自动兜底；Stop hook 发现太久未体检时提醒。
系统宪法：规定何时读 / 写记忆、什么不能写、高风险事项 ASK_USER。
12 步运转流程
识别是否需要调用记忆。
8 大优点与自我进化
① 事实源可控（Markdown 不被平台锁定）；② 检索完整（导航＋关键词＋语义）；③ 写入前 reconcile 对账；④ closeout 闭环；⑤ Git 可回滚；⑥ audit 体检；⑦ 自动化克制不越权（不自动删文件 / 改敏感事实 / 操作高风险内容）；⑧ Agent 自我进化。
case candidate → 验证 → 正式 case → 候选 skill，有门槛、有审计，不是什么都往 skill 里塞。
已封装成 Skill 开源：github.com/mcncarl/codex-memory。
路线二：五个记忆文件，各司其职
第二条路线来自 @sairahul1（2026-06-19 X 长文），更轻量：用 5 个记忆文件解决"每会话失忆"。核心论点：代理失败主因不是模型，是会话结束记忆消失、每轮重复纠正；"模型＋记忆＋检索＋反馈＝有用的智能体"，"记忆是复合变量，模型智能不是"。
五文件分工
| 文件 | 给谁看 | 装什么 |
|---|---|---|
| CLAUDE.md | Claude | 会话简报：项目背景 / 代码风格 / 精确命令 / 架构，<300 行 |
| AGENTS.md | 所有工具 | 跨工具通用标准（Claude Code、Cursor、Copilot、Gemini CLI、Windsurf、Aider、Zed、Warp 都读） |
| CLAUDE.local.md | 自己 | 个人偏好，永不提交 git |
| MEMORY.md | AI 自己 | AI 写的笔记，配 memory/ 目录 |
| README.md | 人 | 给人看的项目说明 |
分四部分，附示例模板。/init 生成后删除大部分——默认文件含 package.json 已知信息，只留"没它 Claude 会弄错"的内容。
可递归最多 5 层；团队分工维护 docs/ 下各文件（前端团队管 frontend-rules.md、安全团队管 security.md）。
Claude Code 会话中自己写 memory/（MEMORY.md 索引 ＋ debugging.md ＋ api-conventions.md ……）。会话结束时说一句："用今天你对我们代码库的了解来更新你的记忆文件"；/memory 可查看编辑。
根目录 AGENTS.md ＋ CLAUDE.md（<100 行，多用 @imports）＋ CLAUDE.local.md ＋ 自动记忆；其余工具配置用符号链接指回 AGENTS.md（.github/copilot-instructions.md、.cursor/rules/main.mdc），消除多工具指令漂移。
工作流：/init → 删冗余；犯错时把规则写进 CLAUDE.md（如"总是从 @company/utils-v2 导入"）；每几周清理冲突指令。
路线三：Skills 按需加载 ＋ Chronicle 屏幕记忆
第三条路线分两篇：一篇是 @claudeskills101（2026-09-25）的三个 Claude Skills，解决"每次聊天重复输背景"；一篇是 @shao__meng（2026-04-21）介绍的 OpenAI Codex 记忆扩展层 Chronicle。
三个 Skills（@claudeskills101）
把简单提示转成完整分步计划，过程中还会提问；加 ELI5 可得通俗解释。用法：下载 skill 文件 → Claude 设置 → 自定义 → Skills 上传 → 任意聊天输入 /how-to ＋任务。
一次性保存背景（你是谁 / 如何工作 / 理想结果），仅调用时加载而非全局常驻——全局常驻会让 Claude 不断重复相同回答、扼杀创造力。这是全文最关键的一句：按需加载 vs 全局常驻。
向你提问 → 生成 skill 文件 → 命名保存 → 斜杠调用；可经"自定义 → 技能 → 分享"分发给团队。三者互相嵌套：skill-creator 能造出前两个。
Chronicle：用屏幕理解你在做什么（@shao__meng，引 OpenAI 官方 2026-04-20 公告）
Chronicle 是 Codex 记忆功能的扩展层：本地运行沙盒化的后台智能体，持续捕获屏幕图像并生成记忆，利用"最近的屏幕内容"改善记忆——让 Codex 理解"你现在在做什么"，无需用户重新解释上下文，不依赖用户主动输入。
- 截图临时存储：原始截图在本地 $TMPDIR/chronicle/screen_recording/，超 6 小时自动删除；
- 记忆生成需联网：截图＋OCR 文本发到 OpenAI 服务器做摘要，生成 Markdown 记忆文件，随后服务器端删除原截图（除非法律要求保留）；
- 记忆本地明文存储：~/.codex/memories_extensions/chronicle/，未加密，用户可直接查看 / 编辑 / 删除；
- 权限要求：macOS 屏幕录制 ＋ 辅助功能权限——能看到屏幕上一切内容（含邮件、密码管理器、财务数据等敏感信息）；
- 模型：与 Codex Memories 同模型（默认 Codex 默认模型，可经 consolidation_model 配置，如 gpt-5.4-mini）；
- 能力边界：识别当前屏幕的报错 / 图表 / 设计稿；补全"你提到'这个'时的指代"；长期学习用户工具习惯与工作流；
- 数据流：本地捕获 → 临时存（6h）→ 上传 OpenAI 生成记忆 → 记忆回本地长期存 → 服务器删截图；记忆用作未来会话上下文时可能被用于模型改进（取决于 ChatGPT 设置）；
- 可用性：当时 ChatGPT Pro 可用，Plus 要再等等。
Chronicle 的隐私代价：屏幕录制权限意味着它能看到你屏幕上的一切。记忆文件是未加密明文 Markdown——方便你审查，但别人拿到你电脑也能看。
收尾：三条路线怎么选
三条路线不是互斥的，但起点不同。按你的情况对号入座：
| 路线 | 适合谁 | 代价 | 一句话定位 |
|---|---|---|---|
| 本地记忆库（@gengdaJ） | 重度 Codex 用户、想完全掌控记忆 | 最高：要搭 Obsidian＋索引＋脚本 | 记忆的"自建房"：事实原件在手，可审计可回滚 |
| 记忆文件体系（@sairahul1） | 大多数人、从今天就能开始 | 最低：5 个文件写好就行 | 记忆的"精装修"：人类写规则，代理写记忆 |
| Skills＋Chronicle | 怕麻烦、愿用官方能力的人 | 中等：接受屏幕权限与云端摘要 | 记忆的"全托管"：按需加载背景，屏幕即上下文 |
三条路线都指向 @sarahwooders 开篇的结论：记忆是框架的事。本地记忆库用 AGENTS.md 当宪法、记忆文件体系用 CLAUDE.md / AGENTS.md 当入口、Chronicle 直接做进 Codex——没有一条路线是把记忆当"外挂插件"用的。
选记忆方案就像选记笔记的方式：本地记忆库是手账本（全自己管，最放心也最累）；记忆文件是便利贴（贴在固定位置，谁都看得懂）；Skills＋Chronicle 是请了个助理（你不用记，它替你记，但你要给它看你桌面的权限）。
术语翻卡：点卡片看解释
自测一下：点问题展开参考答案
因为管理上下文本身就是代理框架的核心职责；框架在做大量隐性决策（什么进上下文、什么经受 compaction、skill 元数据如何呈现），外部插件控制不了这些。就像要求把驾驶功能接入汽车——驾驶不是选配。
ADD / UPDATE / NOOP / MARK_OUTDATED / MERGE_REQUIRED / ASK_USER。写入正式记忆之前必须先对账。
CLAUDE.md 给 Claude（会话简报）；AGENTS.md 给所有工具（通用标准）；CLAUDE.local.md 给自己（个人偏好，永不提交）；MEMORY.md 给 AI 自己（它写的笔记）；README.md 给人看。
截图在本地 $TMPDIR/chronicle/screen_recording/，超 6 小时自动删除；记忆在 ~/.codex/memories_extensions/chronicle/，是未加密的明文 Markdown，可查看编辑删除。
全局常驻会让 Claude 不断重复相同回答、扼杀创造力。背景只在调用 skill 时加载，需要时才进上下文。