大家好我是张大鹏10年全栈开发经验。在研究了GenericAgent的架构之后最让我拍案叫绝的不是它的Agent循环也不是它的工具设计而是它的记忆系统。这篇文章我会带你从头到尾拆解这套四层记忆架构——它怎么存储、怎么检索、怎么进化以及为什么我说这是目前见过设计最清醒的Agent记忆系统。一、先说一个反常识的设计大多数Agent框架处理记忆的方式很直接把聊天历史全部塞进上下文。不够用了就扩窗口200K不够就上1M。这就像为了找一本书把整座图书馆背在身上。GenericAgent的做法完全不同——它的核心记忆代码不到100行但设计了一套四层架构让Agent每次只携带最必要的信息需要时再按图索骥去取。我看了这么多Agent项目这是第一个让我感觉到这个项目是真的在认真思考记忆问题的。它不是拍脑袋想出来的分层而是有一套完整的元规则在约束每一层该放什么、不该放什么。二、四层记忆架构总览先看整体结构我整理了一张表层级文件/位置容量控制核心作用L0memory/memory_management_sop.md~1页文档记忆系统的宪法——定义规则L1memory/global_mem_insight.txt≤30行1K token极简索引告诉Agent知识在哪L2memory/global_mem.txt小按需膨胀环境事实库路径、ID、配置L3memory/*.md*.py多个文件任务级SOP和工具脚本L4memory/L4_raw_sessions/自动归档ZIP压缩历史会话存档这套架构最精彩的设计是上层不存细节只存指针。也就是所谓的存在性编码——L1不会告诉你怎么操作浏览器它只写一行浏览器特殊操作: tmwebdriver_sop(文件上传/图搜/PDF blob/物理坐标/HttpOnly Cookie/autofill突破/跨域iframe/CDP/跨tab)Agent看到这行就知道“哦遇到浏览器特殊操作时去读tmwebdriver_sop这个文件。” 至于具体怎么操作那是L3的事。三、L0元规则——约束比能力更重要当我读到memory_management_sop.md里的核心公理时我就知道这个项目的作者是真正被Agent坑过的。四条不可违反的规则公理内容一句话理解行动验证原则只有成功的工具调用结果才能写入记忆没验证过的不算知识神圣不可删改性已验证信息在重构时严禁丢失可以压缩不能删除禁止存储易变状态不存时间戳、Session ID、PID等存了就过期的东西不要存最小充分指针上层只留定位下层的最短标识多一个词都是浪费其中第一条最狠——“No Execution, No Memory”。这意味着Agent不能在脑子里YY一些我觉得可能是这样的信息写入记忆。必须是code_run执行成功、file_read确认内容存在之后才能记下来。这直接解决了Agent记忆系统最大的痛点幻觉污染。没有这条规则Agent的自学能力越强记忆库里的垃圾就越多。四、L1存在性编码的实践L1 文件global_mem_insight.txt是整个记忆系统的入口也是唯一一个每次对话都会加载的文件。它长这样这是项目当前的实际情况# [Global Memory Insight] 浏览器特殊操作: tmwebdriver_sop(文件上传/图搜/PDF blob/物理坐标/...) 键鼠: ljqCtrl_sop(禁pyautogui/先activate) 截图/视觉: ocr/vision_sop | 禁全屏截图优先窗口 定时:scheduled_task_sop | 自主:autonomous_operation_sop 手机:adb_ui.py 需要时read L2 或 ls ../memory/ 查L3 L0(META-SOP): memory_management_sop L2: 公众号(微信ID/目录路径) L3: memory_cleanup_sop | skill_search | plan_sop | ... L4: L4_raw_sessions/ [RULES] 1. 搜索先行: 搜文件名严禁不用es... 2. 交叉验证: 禁信摘要... ...注意几个设计细节第一层高频场景直接映射。像浏览器特殊操作 →tmwebdriver_sop这种括号里放的是场景触发词不是操作方法。Agent读到的是一把钥匙不是说明书。第二层低频场景只列关键词。对于不常用的能力L1只写文件名Agent需要时再去读。RULES区存放的是红线规则——那些违反不会报错但会导致结果错误的事情。比如搜索用google不用百度、“交叉验证不要信摘要”。这些是项目实践中踩过的坑凝结成的教训。L1 的更新有一条硬性红线——只能 patch 修改严禁 overwrite。因为让 LLM 重写整个文件大概率会丢掉一些信息。每一次更新必须是精准的局部替换。五、L2 L3事实库与技能库L2你不该让LLM猜的东西L2global_mem.txt存放的是环境特异性事实——那些大模型不可能靠参数准确生成的信息## [公众号相关] # 公众号微信ID: yggaibc # 公众号文章目录: ../articles/公众号/这类信息的特点是零次学习失败率100%。你让LLM猜你的公众号ID它不可能猜对。所以必须存下来。L2禁止存储的内容也很有意思通用常识。比如Python列表怎么遍历——这种信息大模型已经会了存了就是浪费token。L3任务的肌肉记忆L3是memory/目录下的SOP文件*_sop.md和工具脚本*.py。每个文件对应一类任务的操作规范。一个SOP文件的典型内容结构关键前置条件开始前必须确认的事情典型易踩坑点上次在这个任务上反复失败的原因操作要点极简步骤不是教程设计原则很克制——只记录跨会话仍重要、且难以快速重建的要点。那些上网搜一下就能找到的东西不记。六、L4历史的归档与遗忘L4memory/L4_raw_sessions/是历史会话层也是唯一一个自动化运行的层级。它的工作机制在reflect/scheduler.py中定义——每12小时自动触发一次归档流程# reflect/scheduler.py:63-74defcheck():global_l4_tif_time.time()-_l4_t43200:# 12小时_l4_t_time.time()fromcompress_sessionimportbatch_process raw_dir../temp/model_responsesrbatch_process(raw_dir,dry_runFalse)归档流程分四步我在compress_session.py里梳理出了完整逻辑原始会话文件 → 压缩剥离系统提示和冗余回声 → 提取 [USER]/[Agent] 历史摘要 → 去重合并滑动窗口匹配 → 追加到 all_histories.txt 按月 ZIP 压缩 → 删除原始文件核心的压缩逻辑对于原始格式的会话文件会剥离系统提示和助手的冗余回声def_compress_raw(text):sections_parse_sections(text)out[]fori,(typ,line,body)inenumerate(sections):iftypprompt:out.append(line\n)ifnot(i1len(sections)andsections[i1][0]user):out.append(body)eliftypin(user,response):out.append(line\n)out.append(body)# assistant → skip (redundant echo)return.join(out)这段代码我特别喜欢——就20行干净利落地完成了去掉系统提示、去掉助手回声、保留用户和助手交互的压缩逻辑。不依赖任何第三方库。L4目前有一个状态只写不读。会话被压缩归档了但Agent在后续任务中不会主动去检索这些历史。这是当前设计中最明显的缺环——archive 的目的应该是 future retrieval但目前只完成了archive这一半。七、运行时记忆working history 双通道除了文件系统的持久化记忆运行时还有两个活的记忆结构定义在ga.py中。工作记忆 (Working Memory)# ga.py:263-268classGenericAgentHandler(BaseHandler):def__init__(self,parent,last_historyNone,cwd./temp):self.working{}self.history_infolast_historyiflast_historyelse[]self.working是一个字典最关键的是key_info字段——它通过update_working_checkpoint工具写入每轮自动注入下一轮提示词# ga.py:432-442defdo_update_working_checkpoint(self,args,response):key_infoargs.get(key_info,)related_sopargs.get(related_sop,)ifkey_infoinargs:self.working[key_info]key_infoifrelated_sopinargs:self.working[related_sop]related_sop self.working[passed_sessions]0yieldf[Info] Updated key_info and related_sop.\nnext_promptself._get_anchor_prompt(skipargs.get(_index,0)0)returnStepOutcome({result:working key_info updated},next_promptnext_prompt)这相当于Agent的便签纸——任务进行到一半时把关键的避坑点、当前进度、下一步计划记下来防止在长任务中迷失方向。summary协议这是我最喜欢的设计之一。每次LLM回复时必须输出一个summary标签内容是单行物理快照# llmcore.py:933-935THINKING_PROMPT_ZH 每次回复含工具调用轮都先在回复文字中包含一个summary/summary 中输出极简单行30字物理快照上次结果新信息本次意图。 # ga.py:523-534defturn_end_callback(self,response,tool_calls,tool_results,turn,next_prompt,exit_reason):rsummre.search(rsummary(.*?)/summary,_c,re.DOTALL)ifrsumm:summaryrsumm.group(1).strip()else:# 没有summary时自动生成summaryf调用工具{tool_name}, args:{clean_args}self.history_info.append(f[Agent]{summary})然后通过_get_anchor_prompt()将最近的40条摘要回注到下一轮# ga.py:511-521def_get_anchor_prompt(self,skipFalse):h_str\n.join(self.history_info[-40:])promptf\n### [WORKING MEMORY]\nhistory\n{h_str}\n/historyifself.working.get(key_info):promptf\nkey_info{self.working.get(key_info)}/key_inforeturnprompt这套强制摘要 回注机制的精妙之处在于让LLM自己负责压缩自己的历史。不是用算法去截取原始对话而是让LLM每轮输出一个它认为最重要的快照。压缩质量远高于简单的滑动窗口。八、完整数据流从启动到持久化我把整个记忆系统的运行流程串起来画成了一条完整的链路agentmain.py 启动 │ ├── 初始化 L1/L2 文件不存在则从模板创建 │ ├── get_global_memory() → 读取 L1 global_mem_insight.txt │ 固定结构模板 │ → 注入系统提示词 │ └── agent_runner_loop 开始循环 │ ├── 每轮开始: _get_anchor_prompt() │ ├── history_info[-40:] → history 块 │ ├── working[key_info] → key_info 块 │ └── working[related_sop] → SOP 提示 │ ├── Agent 回复包含 summary │ ├── turn_end_callback() │ ├── 提取 summary → 追加到 history_info │ ├── 每10轮: 重新注入 L1 全局记忆防遗忘 │ └── 检查是否注入 _keyinfo / _intervene │ ├── 工具调用分支 │ ├── update_working_checkpoint → 更新 key_info │ └── start_long_term_update → Agent 自行修改 L1-L3 │ └── 后台scheduler.py 每12小时 └── compress_session.batch_process() → 压缩 → 提取 → 去重 → 归档 L4这个流程里有一个特别关键的防遗忘设计每10轮自动重新注入全局记忆ga.py:539。因为在长对话中Agent很容易忘记自己在L1里有什么知识可用。定期重新注入相当于敲敲它的脑袋“别忘了你还有这些工具。”九、总结与评价经过这一轮深入源码的拆解我用一个表格总结GenericAgent记忆系统的设计维度评价设计哲学★★★★★ — 存在性编码比全量记忆聪明得多架构清晰度★★★★★ — L0-L4分层清晰职责分明不重叠token效率★★★★★ — 默认只加载L11K token按需取用深层防污染机制★★★★☆ — 无行动不记忆原则能有效阻挡幻觉闭环完整性★★★☆☆ — L4归档后缺乏检索利用只写了一半代码精简度★★★★★ — 记忆核心代码不到100行没有冗余这套系统最让我佩服的不是技术有多复杂而是设计上的克制。每一行代码都在问同一个问题“这条信息真的值得存吗”、“这个细节真的需要在L1里吗”在Agent开发中能存多少不是问题该存什么才是真正考验设计师功力的地方。GenericAgent用四层架构和一套元规则给出了目前我看到的最诚实的答案。参考资料GenericAgent GitHub仓库技术报告arXivDatawhale入门教程GenericAgent深度解析3K行代码打造自我进化的AI Agent框架作者张大鹏团队大鹏 AI 教育日期2026-05-01我是张大鹏10年全栈开发经验目前专注于 AI 全栈教育培训。关注我每周分享AI和全栈开发领域的深度实战经验。