Agent记忆系统设计与实现
一个 Agent 有没有记忆很大程度上决定了它只是用完即弃的工具还是能越用越懂你的搭档。没有记忆的 Agent每次会话都从零开始你得反复交代项目背景、代码风格、踩过的坑有记忆的 Agent能跨会话保留对你的项目和偏好的理解把重复的沟通成本压缩到接近零。记忆对 Agent 意味着什么记忆对 Agent 的作用具体说有四方面跨会话连续性上次改到哪、为什么这么改、还有哪些待办下次接着干而不是重新摸索个性化适配记住你的技术栈、沟通风格、代码偏好不用每次重申避免重复探索项目结构、构建命令、常见坑已经记下不用每次重新读一遍代码库长程任务状态保持跨多次会话推进的大任务进度不会丢从认知科学的角度Lilian Weng 在 2023 年的综述 《LLM Powered Autonomous Agents》 里把人类记忆分为三层并给出了到 LLM Agent 的映射感官记忆对应原始输入的嵌入表示短期/工作记忆对应 LLM 的上下文窗口——受限于 Transformer 的有限上下文长度长期记忆则对应外部存储靠检索来访问。长期记忆又细分为三种情景记忆记具体经历语义记忆记事实和概念程序记忆记技能和流程。这套分类不只是学术上的类比。Park 等人在 2023 年的 Generative Agents 论文就是那个 25 个虚拟角色在沙盒里生活的实验里把记忆做成了一个可运行的系统用自然语言记录 agent 的完整经历memory stream按相关性、近期性、重要性三个维度检索retrieval再把记忆合成为更高层的反思reflection来指导后续行为。这套 memory stream retrieval reflection 的框架到现在仍被广泛引用。主流 Agent 怎么做记忆下面挑几个有代表性的编程 Agent看它们各自的记忆系统是怎么落地的。虽然底层的 LLM 能力在趋同但记忆系统的设计差异很大这也成了产品间的分水岭。Claude Code 的记忆系统Claude Code 的记忆系统是两套互补的机制CLAUDE.md用户写的指令和 auto memoryClaude 自己写的记忆。CLAUDE.md 采用分层加载从广到细依次是组织级Managed Policy、用户级~/.claude/CLAUDE.md、项目级./CLAUDE.md入版本控制团队共享、本地级./CLAUDE.local.mdgitignore 个人特定。加载时从工作目录向上遍历目录树发现的所有 CLAUDE.md 和 CLAUDE.local.md 全部拼接进上下文——不是覆盖而是叠加越靠近工作目录的越后读。子目录里的 CLAUDE.md 是按需加载的Claude 读取该子目录的文件时才会把对应的 CLAUDE.md 纳入上下文。另外.claude/rules/*.md支持pathsfrontmatter可以做 path-scoped 的按需加载——只有匹配的文件被操作时才激活那条规则。auto memory 是 Claude 自己维护的记忆存在~/.claude/projects/project/memory/包含一个 MEMORY.md 索引和若干主题文件。它按 git 仓库派生路径同一个 repo 的所有 worktree 共享但机器本地不跨机。启动时加载前 200 行或 25KB取小超出部分按需读取。这是目前主流编程 Agent 里最成熟的模型自动维护记忆机制。上下文快满时/compact命令用结构化摘要替换对话历史保留用户意图、关键技术概念、查看和修改的文件、错误及修复、待办事项丢弃逐字对话、完整工具输出和中间推理。压缩后项目根的 CLAUDE.md 会重新注入但子目录嵌套的 CLAUDE.md 不会自动重注入——下次读那个目录的文件时才重新加载。子代理subagent是 Claude Code 上下文管理的另一招。每个子代理有独立的上下文窗口和 system prompt主会话的 auto memory 不会传入。子代理只把最终文本摘要返回主上下文它读取的大量文件不占主上下文。Explore 子代理甚至跳过 CLAUDE.md 和 git status用更便宜的 Haiku 模型做只读探索把扫描成本隔离在外面。需要留意一点CLAUDE.md 是 context不是 enforced configuration。它靠模型读到了、记住了来影响行为不是硬性阻断。要硬性阻断某个操作得用 PreToolUse hook。OpenCodeAGENTS.md 与兼容回退OpenCode 用 AGENTS.md 作为主记忆文件/init命令扫描仓库并生成或更新它建议提交到 Git。加载时本地文件从工作目录向上遍历 AGENTS.md 和 CLAUDE.md优先于全局~/.config/opencode/AGENTS.md每类首个匹配胜出。OpenCode 有个很实际的设计Claude Code 兼容回退。项目里没有 AGENTS.md 时回退读 CLAUDE.md全局没有 AGENTS.md 时回退读~/.claude/CLAUDE.md甚至~/.claude/skills/也能用。对从 Claude Code 迁移过来的用户记忆文件不用重写。上下文压缩通过compaction配置控制auto默认开启在上下文满时自动压缩prune移除旧的工具输出省 tokenreserved留出压缩时的 token 缓冲避免溢出。压缩由一个内置的 compaction agent 负责把长上下文压成摘要。会话层面OpenCode 用 snapshot 系统跟踪文件变更内部是个 git 仓库支持/undo/redo回滚。Codex 与 AGENTS.md 规范跨工具的通用记忆AGENTS.md 规范 本身值得单独说。它由 OpenAI Codex、Amp、Google Jules、Cursor、Factory 协作制定现在由 Linux Foundation 下的 Agentic AI Foundation 托管是一个跨工具的通用记忆文件标准。加载规则很简单放仓库根目录大型 monorepo 用嵌套 AGENTS.md子项目各放一个agent 自动读目录树中最近的 AGENTS.md最近的优先。冲突时最近的 AGENTS.md 胜出用户聊天时的提示覆盖一切。文件是纯 Markdown无必填字段。Codex、Cursor、Windsurf、Gemini CLI、Cline、OpenCode、Aider 等都支持这个规范。这意味着你写一份 AGENTS.md换个工具也能用——记忆不再绑死在某个 Agent 上。Cline条件规则与检查点Cline 的规则系统支持多来源自己的.clinerules/、自动检测的.cursorrules和.windsurfrules、以及 AGENTS.md。工作区规则和全局规则合并工作区优先。最有特色的是 conditional rules规则的 YAML frontmatter 里写paths字段glob 模式只有当前上下文匹配那些路径时才激活——匹配依据包括消息里提到的路径、打开的 tab、可见文件、编辑过的文件。这和 Claude Code 的.claude/rules/paths 思路一致都是按需加载、避免 token 浪费。上下文管理上Cline 有 Auto Compact接近窗口限制时自动生成结构化摘要保留技术细节、代码变更和决策替换对话历史。它利用已有的 prompt cache成本约等于一次普通工具调用。压缩后可以用 checkpoints 回滚到摘要前的状态不是不可逆的。子代理方面Cline 的 subagent 是并行只读研究代理独立上下文窗口和 token budget只配只读工具不能编辑文件、用浏览器或访问 MCP返回聚焦报告给主代理。Aiderrepo map结构化检索式记忆Aider 走了一条不太一样的路。它有 CONVENTIONS.md 做文件式记忆/read标记只读启用 prompt caching 时会被缓存也能通过.aider.conf.yml接入 AGENTS.md。但真正有特色的是 repo map。repo map 用 tree-sitter 解析整个 git 仓库生成一份简洁的符号地图——最重要的类、函数及其类型和调用签名。然后用图排序算法每个源文件是节点依赖关系是边类似 PageRank选取最相关的部分纳入上下文。token budget 是动态的默认 1k tokens当没有文件加入聊天时会自动扩大帮 Aider 理解全局结构。说白了这是结构化检索式记忆不是向量检索也不是文件式记忆。它不存偏好和规则存的是代码库的骨架。在这次调研的几个 Agent 里Aider 是唯一用这种方式做记忆的。MiMo Code在 OpenCode 上把记忆做成核心MiMo Code 是小米开源的编程 Agentgithub.com/XiaomiMiMo/MiMo-CodeMIT 协议约 11k stars明确是 OpenCode 的 fork。它保留了 OpenCode 的全部核心能力多 provider、TUI、LSP、MCP、插件在此基础上把记忆系统做成了重点增强方向。它的持久记忆用 SQLite FTS5 全文搜索驱动包含四类文件MEMORY.md项目知识、规则、架构决策checkpoint.md由 checkpoint-writer 子代理自动维护的状态快照notes.md临时笔记区tasks//progress.md逐任务的进度日志会话恢复时这些记忆自动注入不用重新教 agent 项目背景。最有意思的是它的上下文重建机制。上下文逼近上限时不是简单压缩而是从最新 checkpoint、项目记忆、任务进度和保留的近期消息重建上下文按 token 预算和重要性排序控制注入量。agent 重建后能继续当前任务而不是从压缩摘要里猜之前在干什么。MiMo Code 还有 dream / distill 两个自我改进命令和 Generative Agents 的 reflection 机制遥相呼应/dream扫描近期会话痕迹把持久知识提取到项目记忆同时删除过时条目/distill发现重复的手动工作流把高置信度的候选打包成可复用的 skill、subagent 或 command。等于是让 agent 自己反思、自己沉淀经验。横向对比把上面几个 Agent 按维度拆开看记忆载体Agent主记忆文件其他记忆Claude CodeCLAUDE.mdauto memoryMEMORY.md 主题文件OpenCodeAGENTS.mdsession snapshotCodexAGENTS.md—Cline.clinerules/ AGENTS.mdcheckpointsAiderCONVENTIONS.mdrepo map符号地图MiMo CodeAGENTS.mdMEMORY.md checkpoint.md FTS5分层与加载Agent策略Claude Code组织→用户→项目→本地向上遍历全拼接OpenCode本地向上遍历优先于全局每类首匹配胜出Codex根 嵌套最近的优先Cline工作区 全局合并工作区优先Aider配置文件指定 readMiMo Code继承 OpenCode记忆按 token 预算注入压缩与重建Agent策略Claude Code/compact 结构化摘要根 CLAUDE.md 存活OpenCodecompaction agent prune reservedCodex未找到公开文档ClineAuto Compact checkpoints 可回滚Aider无自动压缩靠 repo map 控量MiMo Code上下文重建checkpoint 记忆 预算注入子代理与隔离Agent做法Claude Code独立上下文只回摘要auto memory 不传入OpenCode子会话独立mention 调用Codex未找到公开文档Cline并行只读 subagent独立 token budgetAider无子代理MiMo Code共享会话上下文可并行生命周期跟踪记忆系统的关键设计点从上面这些实现里能提炼出几个关键设计点。文件式记忆是当前主流。这几个 Agent 里除 Aider 的 repo map 外主记忆都是 Markdown 文件。原因是文件可读、可 diff、可入版本控制、可团队协作——这些都是向量库做不到的。向量检索在这些编程 Agent 里基本没有用于主记忆更多用在通用对话型 agent 的历史会话检索上。分层加载是共同的选择。Claude Code、AGENTS.md 规范、OpenCode、Cline 都遵循越靠近工作目录越优先/越后读的原则。Claude Code 是全部拼接不覆盖AGENTS.md 是最近的胜出Cline 是工作区优先于全局。这套分层让组织规范、个人偏好、项目约定能各安其位。光分层还不够还得按需加载。Claude Code 的.claude/rules/paths、Cline 的 conditional rules paths、Aider 的 repo map 动态选取都是匹配到才加载避免把所有规则一股脑塞进上下文。自动记忆要不要做是个取舍。目前只有 Claude Code 有成熟的 auto memoryMiMo Code 用 checkpoint-writer 子代理自动维护状态快照也算半个。好处是省心风险是写入质量依赖模型判断可能写入错误模式。Claude Code 的做法是容量有限前 200 行/25KB且可审计/memory命令查看和编辑。上下文快满时怎么处理决定了 agent 能不能干长活。Claude Code 和 Cline 用结构化摘要保留意图、文件、决策和待办丢弃逐字对话和工具输出而不是简单砍掉头部OpenCode 用 compaction agent 做类似的事。MiMo Code 更进一步用上下文重建替代单纯压缩。压缩之后还得有记忆存活机制。Claude Code 在 compact 后重新注入项目根 CLAUDE.mdCline 用 checkpoints 允许回滚到摘要前。压缩不该是不可逆的信息黑洞。子代理隔离上下文是变相扩容。把大文件读取和搜索隔离在子代理的独立上下文里只把最终摘要返回主上下文这几个 Agent 都在用这招。下面这张图把一个好的记忆系统的运转闭环串起来看设计不好会出什么问题记忆系统设计不当轻则 agent 行为飘忽重则跨会话传播错误。下面是几种常见的失败模式。指令冲突两份 CLAUDE.md 或 AGENTS.md 给出不同的指导模型可能随便选一个。Claude Code 官方文档在 Troubleshoot 里明确指出这个问题建议人工清除冲突。AGENTS.md 规范的 FAQ 给出的规则是最近的胜出。记忆污染auto memory 写入了错误模式或过时偏好然后跨会话传播。Claude Code 的 auto memory 跨会话共享需要定期用/memory审计和编辑。过期记忆规则文件没跟着技术栈更新反而误导模型。Cline 官方文档直言Keep rules current. Outdated rules confuse Cline。token 爆炸CLAUDE.md 写太长官方建议不超过 200 行否则 adherence 下降、规则全量加载、子代理返回过多结果都会把上下文撑爆。Claude Code 官方警告many subagents returning detailed results can consume significant context。compact 后指令丢失只在对话里给过的指令或子目录嵌套的 CLAUDE.md在 compact 后会消失。要持久就得写进 CLAUDE.md这是 Claude Code 的明确建议。子代理上下文不继承以为子代理能看到主对话历史或 auto memory实际上不能。Claude Code 明确说明 subagent 不含主会话历史与 auto memory除非自定义 memory 字段。规则被当强制配置以为 CLAUDE.md 会硬性阻断某个操作。实际上它是 context不是 enforced configuration要硬阻断得用 PreToolUse hook。幻觉性记忆auto memory 写入了编造的内容或模型声称记得某事但实际没存储。auto memory 可审计但写入质量依赖模型判断什么值得记。跨机不一致auto memory 是机器本地的不跨机、不跨云环境共享。换台电脑记忆就没了。压缩信息损失摘要会丢弃逐字代码和完整工具输出后续无法精确引用。这是结构化摘要的固有代价。monorepo 噪音祖先目录里其他团队的规则被加载进来。Claude Code 提供claudeMdExcludes排除AGENTS.md 用嵌套就近解决。好的记忆系统长什么样把上面的设计点和失败模式反过来好的记忆系统大概长这样持久层用可读、可 diff 的文件能入版本控制做团队协作加载时分层 向上遍历让组织规范、个人偏好、项目约定各安其位冲突有明确的解决规则按需加载避免 token 浪费只有匹配的上下文才激活对应规则上下文快满时做结构化摘要或重建而非截断保留意图、文件、决策和待办压缩后核心记忆重新注入、状态可回滚子代理隔离独立上下文只把摘要返回主窗口token 占用始终受预算约束有重要性排序自动记忆可审计、可编辑、容量有限强制 agent 做信息蒸馏最好还有类似 dream / distill 的反思机制让 agent 自己沉淀经验、清理过时条目。说到底记忆系统的核心矛盾是记住更多和上下文有限之间的博弈。好的设计在这两端之间做取舍让该进来的进来、该留住的留住、该丢掉的丢掉把有限的窗口留给真正重要的信息。学AI大模型的正确顺序千万不要搞错了2026年AI风口已来各行各业的AI渗透肉眼可见超多公司要么转型做AI相关产品要么高薪挖AI技术人才机遇直接摆在眼前有往AI方向发展或者本身有后端编程基础的朋友直接冲AI大模型应用开发转岗超合适就算暂时不打算转岗了解大模型、RAG、Prompt、Agent这些热门概念能上手做简单项目也绝对是求职加分王给大家整理了超全最新的AI大模型应用开发学习清单和资料手把手帮你快速入门学习路线:✅大模型基础认知—大模型核心原理、发展历程、主流模型GPT、文心一言等特点解析✅核心技术模块—RAG检索增强生成、Prompt工程实战、Agent智能体开发逻辑✅开发基础能力—Python进阶、API接口调用、大模型开发框架LangChain等实操✅应用场景开发—智能问答系统、企业知识库、AIGC内容生成工具、行业定制化大模型应用✅项目落地流程—需求拆解、技术选型、模型调优、测试上线、运维迭代✅面试求职冲刺—岗位JD解析、简历AI项目包装、高频面试题汇总、模拟面经以上6大模块看似清晰好上手实则每个部分都有扎实的核心内容需要吃透我把大模型的学习全流程已经整理好了抓住AI时代风口轻松解锁职业新可能希望大家都能把握机遇实现薪资/职业跃迁这份完整版的大模型 AI 学习资料已经上传CSDN朋友们如果需要可以微信扫描下方CSDN官方认证二维码免费领取【保证100%免费】