Agent 记忆系统设计四层记忆架构与长期上下文持久化引言让 Agent 跨会话记住用户是几乎所有 AI 助理产品的核心诉求也是最容易做糊的一环。很多产品的做法是把记忆塞进云端黑盒用户既看不到 Agent 记了什么也无法精确增删更谈不上备份迁移。而在以 OpenClaw 为代表的本地优先 Agent 框架里记忆被设计成一整套透明的、由文件构成的分层系统——可查看、可编辑、可导出、可回滚。本文从大模型上下文窗口的固有局限出发拆解四层记忆架构的设计逻辑并讨论记忆的写入、检索、压缩淘汰与版本管理等工程问题。一、问题起点上下文窗口装不下一段关系大模型的上下文窗口是有限的常见在 128K–200K tokens 量级而一段持续数小时的深度对话就可能逼近上限。框架的应对手段是上下文压缩Compaction会话接近上限时把较旧的对话历史压成摘要腾出空间仅保留最近的一部分原文默认约 20,000 tokens 与最近几轮对话。这里埋着一个致命细节。规范的压缩流程分两步先触发一次记忆冲刷Memory Flush——用一个静默的内部回合提醒 Agent 把重要内容写入磁盘文件——然后才执行压缩。但冲刷是尽力而为的如果某次巨大的工具输出让 Token 突然飙升冲刷可能来不及运行就触发了紧急压缩上下文大量丢失。一个广为流传的教训来自一位 AI 对齐方向的研究者她让 Agent 整理邮箱并明确嘱咐在我确认之前不要做任何操作。测试邮箱运行良好切到真实收件箱后会话撑满了窗口触发压缩那句关键指令从摘要中消失了——Agent 随即批量删除了两百多封邮件连停止命令都被忽略。事后她自嘲对齐研究者也会栽在未对齐上。这个案例的技术启示只有一条没有写入文件的信息等于不存在。对话是易失的文件才是持久的。这是记忆系统设计的第一原则。一切分层、检索、备份设计都由它推导出来。二、四层记忆架构按稳定性分层OpenClaw 把 Agent 的记忆组织为四层稳定性自上而下递减┌─────────────────────────────────────────────┐ │ 第一层 · 不可变内核 │ │ AGENTS.md / SOUL.md / IDENTITY.md │ 人类手动维护永久生效 ├─────────────────────────────────────────────┤ │ 第二层 · 动态工具与引导 │ │ TOOLS.md / BOOTSTRAP.md / Skills / 心跳清单 │ 随配置变化 ├─────────────────────────────────────────────┤ │ 第三层 · 语义长期记忆 │ │ MEMORY.md / USER.md / memory/每日笔记 │ Agent 写入 人工编辑 ├─────────────────────────────────────────────┤ │ 第四层 · 实时会话Session │ │ 消息列表压缩后大量丢失 │ 最易失 └─────────────────────────────────────────────┘第一层不可变内核这一层回答Agent 是谁、怎么做事AGENTS.md承载操作规则与决策框架怎么做SOUL.md定义性格与行为边界是什么样的人IDENTITY.md存放身份信息。它们由人类手动编写维护、生命周期永久每次会话开始时注入。关键的约束性指令比如未经确认不得执行删除类操作必须沉淀在这一层而不是留在对话里——这正是前述删邮件事故的反面教材。第二层动态工具与引导工具说明、启动引导、Skills 配置、心跳巡检清单都属于这一层随配置增删而变化同样在会话开始时注入。值得注意它的成本属性以一个中等规模的配置为例二十余个 Skills 的描述加上六十多个工具的 schema合计可占用约 18,000 tokens——是上下文预算里的大头。装得越多留给记忆和对话的空间就越少这是技能丰富度与记忆容量之间的隐性交换。第三层语义长期记忆这是 Agent 经验的沉淀层也是唯一由 Agent 自主写入、同时允许人工编辑的层文件角色加载策略MEMORY.md长期记忆库提炼后的事实、偏好、决策每次 DM 会话加载USER.md用户画像关于你的长期信息每次 DM 会话加载memory/YYYY-MM-DD.md每日笔记当天的观察与上下文只加载今天与昨天个人档案与工作日志的分工是这个设计的精髓临时观察进每日笔记被时间自然淘汰只有沉淀下来的持久事实才升格进MEMORY.md长期常驻上下文。数据形态全部是纯 Markdown 文本任何编辑器都能直接打开——这与云端黑盒式记忆形成了根本区别用户可以逐行查看 Agent 对自己的认知发现错误可以直接改正而不是含糊地说一句忘掉这件事然后祈祷。第四层实时会话当前对话的完整消息列表用户发言、Agent 回复、工具调用结果存于内存与会话文件中是 Agent 的工作记忆。它的宿命就是被压缩——那位研究员的指令正是只活在这一层才会在压缩中蒸发。一句话总结四层关系对话会消失文件不会。所有重要的信息必须跨越第四层与第三层之间的鸿沟落地到文件。三、记忆的写入与检索3.1 一条信息的完整旅程用户发出消息 → 消息进入会话 → Agent 判断其是否值得持久化显式的记住…或自主判定为重要信息→ 短期观察写入当日笔记、持久偏好写入MEMORY.md→ 下次会话自动加载这些文件 → Agent 记得了。自动加载有一套明确的预算与优先级各引导文件按固定次序注入操作规则 → 人格 → 身份 → 用户画像 → 工具说明 → 引导脚本 → 长期记忆 → 心跳清单 → 近两日笔记单个文件默认上限 12,000 字符、总量上限 60,000 字符超出即截断。这意味着MEMORY.md并非越长越好——写满了过时信息不仅挤占预算还会因为截断而写了等于没写。3.2 双引擎检索自动加载解决不了上周自动加载只覆盖近两天的笔记。Agent 要回忆更早的内容靠的是检索工具memory_search在全部记忆文件中搜索相关片段把结果纳入当前上下文。一个关键认知是——Agent 不是想起来的而是搜到的。检索质量直接决定了它的记性。自然语言的模糊性与技术术语的精确性构成一对无法调和的矛盾问那次翻车怎么修的需要理解翻车约等于踩坑查CVE-2026-25253 的影响范围或某个域名的 Docker Compose 配置则必须逐字匹配专有名词。任何单一检索引擎都顾不了两头因此 OpenClaw 采用向量 BM25 的混合检索用户查询 / \ Embedding 向量化 FTS5 全文索引 │ │ 向量相似度 TopK BM25 排名 TopK \ / 合并排序Union finalScore 0.7×向量分 0.3×文本分 │ 过滤低分minScore≈0.35→ 返回 TopK 片段向量路径擅长语义相近、同义改写、跨语言的查询BM25 路径擅长精确术语、代码符号、项目名、IP 地址。两路并行、结果取并集加权合并实测在模糊查询与精确查询下都能命中而单引擎各有盲区。默认配置为向量权重 70%、关键词权重 30%、每路先取约 4 倍候选再合并开箱即用只需配好 Embedding 提供商。进阶参数在日常不必动mmr最大边际相关用于对高度相似的片段去重适合日志积累多了、检索结果大量重复时开启temporalDecay让旧笔记的权重随时间衰减避免陈年旧事淹没新近信息常驻文件不受影响。这类调优留到记忆库积累了数月之后再考虑也不迟。四、淘汰与压缩记忆的陈代谢记忆系统必须回答什么该被忘掉否则检索噪音和上下文预算都会失控。这个系统的淘汰机制分三条路径其一结构化淘汰。每日笔记天然带过期属性——只加载近两天更早的自动退出上下文但文件仍在磁盘上可被检索召回。这是退出注意力、不销毁数据的优雅设计既控制了常驻成本又保留了完整历史。其二压缩兜底。会话层面的 Compaction 按 safeguard 模式运行接近上限 → 触发记忆冲刷提醒 Agent 落盘重要内容→ 压缩旧历史为摘要 → 保留最近约 20K tokens 与最近几轮。可调参数包括保留窗口大小、保留轮数以及给压缩过程本身预留的空间社区经验建议至少 30,000 tokens避免压缩动作本身把窗口挤爆。但要清楚其边界紧急溢出路径没有冲刷机会上下文丢失最大——所以关键指令永远不要只依赖这条兜底链。其三人工策展。MEMORY.md需要定期体检每周问一次 Agent你对我有哪些了解核对有无偏差与过时条目删除失效信息把文件保持在精简水平实践中建议控制在 10,000 字符以内为 12,000 的截断线留出余量。记忆策展之于 Agent如同整理通讯录之于人——不整理再好的检索也架不住噪音堆积。五、修正、备份与版本管理记忆是文件于是一切文件工程手段都自然可用。记忆修正有两种途径小修走对话——“你记错了我的偏好是 X 不是 Y请更新记忆”Agent 执行更新大改走编辑器——直接修改MEMORY.md批量删除、结构调整都比对话高效。但直接编辑文件后必须重建记忆索引openclaw memory index --force否则旧索引残留检索结果与文件内容不一致。一个真实的坑Agent 在修正记忆时把 USER.md 里我David主要负责服务器稳定性的我误判为用户本人方向直接改反——修正记忆时主语归属必须写得不留歧义。备份与克隆则体现了文件化架构的最大红利。因为整个大脑就是一个目录三条命令覆盖三个场景# 版本管理立即做之后可随时回滚到任意历史状态cd~/.openclaw/workspacegitinitgitadd-Agitcommit-m初始备份# 定期备份把整个工作区打包到安全位置tar-czf~/openclaw-backup-$(date%Y%m%d).tar.gz ~/.openclaw/workspace/# 迁移与克隆复制目录即克隆一个配置与记忆完全相同的 Agentscp-r~/.openclaw/workspace/ userserver:~/.openclaw/workspace/用 git 管理记忆文件还有一层价值记忆变更是可审计、可回滚的。Agent 今天学会了什么、你昨天删掉了哪条错误认知都在提交历史里一清二楚一次失败的策展可以直接 checkout 回去。这是黑盒记忆产品完全无法提供的能力。六、常见坑速查关键指令只说在对话里压缩一来就蒸发务必写入不可变内核层。MEMORY.md 无限膨胀超过 12,000 字符被截断“写了等于没写”定期策展宁缺毋滥。直接编辑文件后不重建索引检索结果与文件脱节。修改记忆时主语含糊“我”你在记忆文件里极易被误读写明具体人名。Agent失忆就怪模型先用/context list排查加载状态文件是否 MISSING、是否被截断再查 Embedding 配置是否失效——多数失忆是工程问题不是模型问题。检索结果全是陈年旧账或重复片段分别考虑开启时间衰减与 MMR 去重。小结四层记忆架构的深层逻辑是把人的认知分层映射为一组磁盘文件不可变内核是价值观工具层是技能长期记忆是经验实时会话是工作记忆。窗口有限就让稳定性递减的层级各自承担不同生命周期的信息自动加载管近双引擎检索管远压缩与策展管忘最后用 git 给整颗大脑做版本管理。对 Agent 开发者而言这套设计给出的最重要提醒或许还是那句第一原则没有写入文件它就不存在。记忆系统的一切工程——分层、检索、淘汰、备份——本质上都是在为这句话修路。
【AI 业务流架构师】06-Agent记忆系统设计：四层记忆架构与长期上下文持久化
Agent 记忆系统设计四层记忆架构与长期上下文持久化引言让 Agent 跨会话记住用户是几乎所有 AI 助理产品的核心诉求也是最容易做糊的一环。很多产品的做法是把记忆塞进云端黑盒用户既看不到 Agent 记了什么也无法精确增删更谈不上备份迁移。而在以 OpenClaw 为代表的本地优先 Agent 框架里记忆被设计成一整套透明的、由文件构成的分层系统——可查看、可编辑、可导出、可回滚。本文从大模型上下文窗口的固有局限出发拆解四层记忆架构的设计逻辑并讨论记忆的写入、检索、压缩淘汰与版本管理等工程问题。一、问题起点上下文窗口装不下一段关系大模型的上下文窗口是有限的常见在 128K–200K tokens 量级而一段持续数小时的深度对话就可能逼近上限。框架的应对手段是上下文压缩Compaction会话接近上限时把较旧的对话历史压成摘要腾出空间仅保留最近的一部分原文默认约 20,000 tokens 与最近几轮对话。这里埋着一个致命细节。规范的压缩流程分两步先触发一次记忆冲刷Memory Flush——用一个静默的内部回合提醒 Agent 把重要内容写入磁盘文件——然后才执行压缩。但冲刷是尽力而为的如果某次巨大的工具输出让 Token 突然飙升冲刷可能来不及运行就触发了紧急压缩上下文大量丢失。一个广为流传的教训来自一位 AI 对齐方向的研究者她让 Agent 整理邮箱并明确嘱咐在我确认之前不要做任何操作。测试邮箱运行良好切到真实收件箱后会话撑满了窗口触发压缩那句关键指令从摘要中消失了——Agent 随即批量删除了两百多封邮件连停止命令都被忽略。事后她自嘲对齐研究者也会栽在未对齐上。这个案例的技术启示只有一条没有写入文件的信息等于不存在。对话是易失的文件才是持久的。这是记忆系统设计的第一原则。一切分层、检索、备份设计都由它推导出来。二、四层记忆架构按稳定性分层OpenClaw 把 Agent 的记忆组织为四层稳定性自上而下递减┌─────────────────────────────────────────────┐ │ 第一层 · 不可变内核 │ │ AGENTS.md / SOUL.md / IDENTITY.md │ 人类手动维护永久生效 ├─────────────────────────────────────────────┤ │ 第二层 · 动态工具与引导 │ │ TOOLS.md / BOOTSTRAP.md / Skills / 心跳清单 │ 随配置变化 ├─────────────────────────────────────────────┤ │ 第三层 · 语义长期记忆 │ │ MEMORY.md / USER.md / memory/每日笔记 │ Agent 写入 人工编辑 ├─────────────────────────────────────────────┤ │ 第四层 · 实时会话Session │ │ 消息列表压缩后大量丢失 │ 最易失 └─────────────────────────────────────────────┘第一层不可变内核这一层回答Agent 是谁、怎么做事AGENTS.md承载操作规则与决策框架怎么做SOUL.md定义性格与行为边界是什么样的人IDENTITY.md存放身份信息。它们由人类手动编写维护、生命周期永久每次会话开始时注入。关键的约束性指令比如未经确认不得执行删除类操作必须沉淀在这一层而不是留在对话里——这正是前述删邮件事故的反面教材。第二层动态工具与引导工具说明、启动引导、Skills 配置、心跳巡检清单都属于这一层随配置增删而变化同样在会话开始时注入。值得注意它的成本属性以一个中等规模的配置为例二十余个 Skills 的描述加上六十多个工具的 schema合计可占用约 18,000 tokens——是上下文预算里的大头。装得越多留给记忆和对话的空间就越少这是技能丰富度与记忆容量之间的隐性交换。第三层语义长期记忆这是 Agent 经验的沉淀层也是唯一由 Agent 自主写入、同时允许人工编辑的层文件角色加载策略MEMORY.md长期记忆库提炼后的事实、偏好、决策每次 DM 会话加载USER.md用户画像关于你的长期信息每次 DM 会话加载memory/YYYY-MM-DD.md每日笔记当天的观察与上下文只加载今天与昨天个人档案与工作日志的分工是这个设计的精髓临时观察进每日笔记被时间自然淘汰只有沉淀下来的持久事实才升格进MEMORY.md长期常驻上下文。数据形态全部是纯 Markdown 文本任何编辑器都能直接打开——这与云端黑盒式记忆形成了根本区别用户可以逐行查看 Agent 对自己的认知发现错误可以直接改正而不是含糊地说一句忘掉这件事然后祈祷。第四层实时会话当前对话的完整消息列表用户发言、Agent 回复、工具调用结果存于内存与会话文件中是 Agent 的工作记忆。它的宿命就是被压缩——那位研究员的指令正是只活在这一层才会在压缩中蒸发。一句话总结四层关系对话会消失文件不会。所有重要的信息必须跨越第四层与第三层之间的鸿沟落地到文件。三、记忆的写入与检索3.1 一条信息的完整旅程用户发出消息 → 消息进入会话 → Agent 判断其是否值得持久化显式的记住…或自主判定为重要信息→ 短期观察写入当日笔记、持久偏好写入MEMORY.md→ 下次会话自动加载这些文件 → Agent 记得了。自动加载有一套明确的预算与优先级各引导文件按固定次序注入操作规则 → 人格 → 身份 → 用户画像 → 工具说明 → 引导脚本 → 长期记忆 → 心跳清单 → 近两日笔记单个文件默认上限 12,000 字符、总量上限 60,000 字符超出即截断。这意味着MEMORY.md并非越长越好——写满了过时信息不仅挤占预算还会因为截断而写了等于没写。3.2 双引擎检索自动加载解决不了上周自动加载只覆盖近两天的笔记。Agent 要回忆更早的内容靠的是检索工具memory_search在全部记忆文件中搜索相关片段把结果纳入当前上下文。一个关键认知是——Agent 不是想起来的而是搜到的。检索质量直接决定了它的记性。自然语言的模糊性与技术术语的精确性构成一对无法调和的矛盾问那次翻车怎么修的需要理解翻车约等于踩坑查CVE-2026-25253 的影响范围或某个域名的 Docker Compose 配置则必须逐字匹配专有名词。任何单一检索引擎都顾不了两头因此 OpenClaw 采用向量 BM25 的混合检索用户查询 / \ Embedding 向量化 FTS5 全文索引 │ │ 向量相似度 TopK BM25 排名 TopK \ / 合并排序Union finalScore 0.7×向量分 0.3×文本分 │ 过滤低分minScore≈0.35→ 返回 TopK 片段向量路径擅长语义相近、同义改写、跨语言的查询BM25 路径擅长精确术语、代码符号、项目名、IP 地址。两路并行、结果取并集加权合并实测在模糊查询与精确查询下都能命中而单引擎各有盲区。默认配置为向量权重 70%、关键词权重 30%、每路先取约 4 倍候选再合并开箱即用只需配好 Embedding 提供商。进阶参数在日常不必动mmr最大边际相关用于对高度相似的片段去重适合日志积累多了、检索结果大量重复时开启temporalDecay让旧笔记的权重随时间衰减避免陈年旧事淹没新近信息常驻文件不受影响。这类调优留到记忆库积累了数月之后再考虑也不迟。四、淘汰与压缩记忆的陈代谢记忆系统必须回答什么该被忘掉否则检索噪音和上下文预算都会失控。这个系统的淘汰机制分三条路径其一结构化淘汰。每日笔记天然带过期属性——只加载近两天更早的自动退出上下文但文件仍在磁盘上可被检索召回。这是退出注意力、不销毁数据的优雅设计既控制了常驻成本又保留了完整历史。其二压缩兜底。会话层面的 Compaction 按 safeguard 模式运行接近上限 → 触发记忆冲刷提醒 Agent 落盘重要内容→ 压缩旧历史为摘要 → 保留最近约 20K tokens 与最近几轮。可调参数包括保留窗口大小、保留轮数以及给压缩过程本身预留的空间社区经验建议至少 30,000 tokens避免压缩动作本身把窗口挤爆。但要清楚其边界紧急溢出路径没有冲刷机会上下文丢失最大——所以关键指令永远不要只依赖这条兜底链。其三人工策展。MEMORY.md需要定期体检每周问一次 Agent你对我有哪些了解核对有无偏差与过时条目删除失效信息把文件保持在精简水平实践中建议控制在 10,000 字符以内为 12,000 的截断线留出余量。记忆策展之于 Agent如同整理通讯录之于人——不整理再好的检索也架不住噪音堆积。五、修正、备份与版本管理记忆是文件于是一切文件工程手段都自然可用。记忆修正有两种途径小修走对话——“你记错了我的偏好是 X 不是 Y请更新记忆”Agent 执行更新大改走编辑器——直接修改MEMORY.md批量删除、结构调整都比对话高效。但直接编辑文件后必须重建记忆索引openclaw memory index --force否则旧索引残留检索结果与文件内容不一致。一个真实的坑Agent 在修正记忆时把 USER.md 里我David主要负责服务器稳定性的我误判为用户本人方向直接改反——修正记忆时主语归属必须写得不留歧义。备份与克隆则体现了文件化架构的最大红利。因为整个大脑就是一个目录三条命令覆盖三个场景# 版本管理立即做之后可随时回滚到任意历史状态cd~/.openclaw/workspacegitinitgitadd-Agitcommit-m初始备份# 定期备份把整个工作区打包到安全位置tar-czf~/openclaw-backup-$(date%Y%m%d).tar.gz ~/.openclaw/workspace/# 迁移与克隆复制目录即克隆一个配置与记忆完全相同的 Agentscp-r~/.openclaw/workspace/ userserver:~/.openclaw/workspace/用 git 管理记忆文件还有一层价值记忆变更是可审计、可回滚的。Agent 今天学会了什么、你昨天删掉了哪条错误认知都在提交历史里一清二楚一次失败的策展可以直接 checkout 回去。这是黑盒记忆产品完全无法提供的能力。六、常见坑速查关键指令只说在对话里压缩一来就蒸发务必写入不可变内核层。MEMORY.md 无限膨胀超过 12,000 字符被截断“写了等于没写”定期策展宁缺毋滥。直接编辑文件后不重建索引检索结果与文件脱节。修改记忆时主语含糊“我”你在记忆文件里极易被误读写明具体人名。Agent失忆就怪模型先用/context list排查加载状态文件是否 MISSING、是否被截断再查 Embedding 配置是否失效——多数失忆是工程问题不是模型问题。检索结果全是陈年旧账或重复片段分别考虑开启时间衰减与 MMR 去重。小结四层记忆架构的深层逻辑是把人的认知分层映射为一组磁盘文件不可变内核是价值观工具层是技能长期记忆是经验实时会话是工作记忆。窗口有限就让稳定性递减的层级各自承担不同生命周期的信息自动加载管近双引擎检索管远压缩与策展管忘最后用 git 给整颗大脑做版本管理。对 Agent 开发者而言这套设计给出的最重要提醒或许还是那句第一原则没有写入文件它就不存在。记忆系统的一切工程——分层、检索、淘汰、备份——本质上都是在为这句话修路。
