Agent记忆系统设计与实现

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 memory(Claude 自己写的记忆)。

CLAUDE.md 采用分层加载,从广到细依次是组织级(Managed Policy)、用户级(~/.claude/CLAUDE.md)、项目级(./CLAUDE.md,入版本控制团队共享)、本地级(./CLAUDE.local.md,gitignore 个人特定)。加载时从工作目录向上遍历目录树,发现的所有 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。

OpenCode:AGENTS.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移除旧的工具输出省 token,reserved留出压缩时的 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,返回聚焦报告给主代理。

Aider:repo 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 是小米开源的编程 Agent(github.com/XiaomiMiMo/MiMo-Code,MIT 协议,约 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 memory(MEMORY.md + 主题文件)
OpenCodeAGENTS.mdsession snapshot
CodexAGENTS.md
Cline.clinerules/ + AGENTS.mdcheckpoints
AiderCONVENTIONS.mdrepo map(符号地图)
MiMo CodeAGENTS.mdMEMORY.md + checkpoint.md + FTS5

分层与加载

Agent策略
Claude Code组织→用户→项目→本地,向上遍历全拼接
OpenCode本地(向上遍历)优先于全局,每类首匹配胜出
Codex根 + 嵌套,最近的优先
Cline工作区 + 全局合并,工作区优先
Aider配置文件指定 read
MiMo Code继承 OpenCode,记忆按 token 预算注入

压缩与重建

Agent策略
Claude Code/compact 结构化摘要,根 CLAUDE.md 存活
OpenCodecompaction agent + prune + reserved
Codex未找到公开文档
ClineAuto Compact + checkpoints 可回滚
Aider无自动压缩(靠 repo map 控量)
MiMo Code上下文重建(checkpoint + 记忆 + 预算注入)

子代理与隔离

Agent做法
Claude Code独立上下文,只回摘要,auto memory 不传入
OpenCode子会话独立,@mention 调用
Codex未找到公开文档
Cline并行只读 subagent,独立 token budget
Aider无子代理
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 memory,MiMo Code 用 checkpoint-writer 子代理自动维护状态快照也算半个。好处是省心,风险是写入质量依赖模型判断,可能写入错误模式。Claude Code 的做法是容量有限(前 200 行/25KB)且可审计(/memory命令查看和编辑)。

上下文快满时怎么处理,决定了 agent 能不能干长活。Claude Code 和 Cline 用结构化摘要保留意图、文件、决策和待办,丢弃逐字对话和工具输出,而不是简单砍掉头部;OpenCode 用 compaction agent 做类似的事。MiMo Code 更进一步,用上下文重建替代单纯压缩。

压缩之后还得有记忆存活机制。Claude Code 在 compact 后重新注入项目根 CLAUDE.md,Cline 用 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%免费