AI Agent记忆架构解析:从短时到长期的Python实现
在开发 AI Agent 的过程中很多同学会遇到一个非常典型的场景第一轮对话里用户明确说了“我习惯用 Python 写脚本”到了第十轮Agent 却开始推荐 Java 方案昨天刚让 Agent 记住的项目代码规范今天重新开一个会话它又什么都不记得了。这类问题不是提示词写得不够好而是 Agent 缺少一套可用的记忆架构。这篇文章我会从短时记忆和长期记忆的区分讲起完整梳理 Agent 记忆分层、检索、遗忘机制的设计思路并提供一个不依赖第三方库、可以直接运行的 Python 实现。只要你具备基础的 Python 语法知识就能跟着一步步把代码跑起来并把这套思路迁移到自己的 Agent 项目中。1. 为什么 Agent 需要记忆架构从无状态到有状态1.1 Agent 的“失忆”困扰早期的对话机器人基本是无状态的每次请求进来模型只看到当前这轮用户输入上一轮说了什么完全不知道。后来出现了上下文窗口模型可以读取历史消息但上下文窗口的长度是有限的而且对话一结束这些信息就清零了。到了 Agent 阶段问题变得更加复杂。Agent 不仅要处理多轮对话还要执行任务、调用工具、记录中间状态。比如一个科研辅助 Agent可能需要连续几天围绕同一个课题检索文献、设计实验、整理结论。如果它没有跨会话的记忆那每天都是在从零开始。卡内基梅隆大学研发的 Coscientist 系统能够自主检索知识资源、设计实验方案、编写代码正是因为它把“知识检索”和“任务状态”都纳入了一套可复用的系统中而不是只靠模型上下文硬扛。所以Agent 记忆架构要解决的核心问题不是“怎么存”而是“怎么让 Agent 在正确的时间想起正确的事”。1.2 短时记忆与长期记忆的区别我们可以把人脑的记忆模型映射到 Agent 上最基础的是两个概念短时记忆对应当前会话内的上下文包括最近几轮对话、当前任务进度、临时变量。它的特点是容量小、更新快、有效期短。长期记忆对应跨会话、跨任务的知识积累包括用户偏好、历史决策、领域知识、项目规范。它的特点是容量大、需要检索、需要维护。很多人会误以为“把对话记录存进数据库”就是长期记忆。实际上长期记忆要比这复杂得多。它需要解决三个问题怎么写入、怎么检索、怎么遗忘。1.3 记忆分层工作记忆、情景记忆、语义记忆在工程实现中很多 Agent 框架会把记忆进一步分成分层结构常见的分法是三层层级对应概念示例工作记忆当前任务需要立即使用的信息当前对话的最新问题、正在执行的工具调用结果情景记忆过去发生过的事件昨天帮用户修复了登录超时问题语义记忆从经验中提炼出的事实与偏好用户喜欢 Python、项目使用 PostgreSQL工作记忆可以理解为短时记忆的一部分它通常由上下文窗口来承载。情景记忆和语义记忆都属于长期记忆只是抽象程度不同情景记忆是“发生了什么”语义记忆是“我知道了什么”。分层的好处是Agent 可以把不同类型的信息用不同的策略管理。比如情景记忆更容易过时遗忘策略可以更激进语义记忆更稳定检索优先级应该更高。2. 环境准备与项目结构2.1 运行环境说明本文的示例代码使用 Python 3.8不依赖任何第三方库。因为演示的重点是记忆架构本身而不是某个特定框架所以我把所有实现都放在一个文件里方便你复制运行。python --version本文示例对 Python 小版本没有特殊要求只要大于 3.8 即可。如果你已经在使用虚拟环境建议先创建一个干净目录mkdir agent-memory-demo cd agent-memory-demo2.2 项目目录结构生产环境中记忆模块通常会拆分成多个文件例如存储层、检索层、策略层。为了演示直观本文把核心逻辑全部放在memory_demo.py中实际工程落地时可以参考下面的拆法agent-memory-project/ ├── memory/ │ ├── models.py # 记忆数据模型 │ ├── short_term.py # 短时记忆存储 │ ├── long_term.py # 长期记忆存储 │ ├── retriever.py # 混合检索 │ └── forgetting.py # 遗忘策略 ├── main.py └── requirements.txt下面我们先把核心数据结构搞定。3. 记忆数据模型与向量化基础3.1 MemoryItem一条记忆需要哪些字段设计记忆架构前先要定义一条记忆长什么样。一个最小的记忆条目至少需要包含以下信息content记忆的文本内容。memory_type记忆类型常见有 episodic情景、semantic语义、preference偏好。importance重要程度0 到 1。created_at创建时间。last_access_at最近一次被访问时间。access_count被访问次数用来衡量记忆的使用频率。代码实现如下import time from dataclasses import dataclass, field from typing import Dict dataclass class MemoryItem: content: str memory_type: str episodic importance: float 0.5 created_at: float field(default_factorytime.time) last_access_at: float field(default_factorytime.time) access_count: int 0 metadata: Dict field(default_factorydict) def touch(self): self.access_count 1 self.last_access_at time.time()这里有一个容易被忽视的设计点memory_type表示的是记忆的性质而不是“存在短期还是长期”。短期和长期是存储位置情景/语义是记忆内容性质两者不要混在一个字段里。touch()方法会在记忆被检索命中时调用用来更新访问时间和访问次数。这个信息在遗忘机制中很关键。3.2 文本向量化的简易实现要做检索首先得让文本之间能计算相似度。生产环境通常会使用 OpenAI Embedding、BGE 等向量模型但为了让示例不依赖外部 API我使用一个简化版的 Hash 词袋向量。思路是对文本分词后把每个 token 通过 MD5 映射到一个固定维度的向量槽位统计词频并做归一化。import re import math import hashlib from typing import List def tokenize(text: str) - List[str]: text text.lower() tokens re.findall(r[a-z0-9_], text) chinese_chars re.findall(r[\u4e00-\u9fa5], text) if chinese_chars: if len(chinese_chars) 1: tokens.append(chinese_chars[0]) else: tokens.extend([a b for a, b in zip(chinese_chars, chinese_chars[1:])]) return tokens def _md5_int(s: str) - int: return int(hashlib.md5(s.encode(utf-8)).hexdigest(), 16) def hash_vector(text: str, dim: int 256) - List[float]: vec [0.0] * dim for token in tokenize(text): idx _md5_int(token) % dim vec[idx] 1.0 norm math.sqrt(sum(v * v for v in vec)) if norm 0: return vec return [v / norm for v in vec]中文文本没有天然的空格分词所以这里对中文使用了“相邻字符二元组”的方式来生成特征。例如“数据库”会被拆成“数据”“据库”。这样比整句话作为一个 token 的区分度更高。这个方法只是一个演示方案在真实项目中建议使用 jieba 分词配合词向量或者直接使用语义向量模型。3.3 相似度计算有了向量之后计算相似度最常用的方式是余弦相似度def cosine_sim(a: List[float], b: List[float]) - float: return sum(x * y for x, y in zip(a, b))由于hash_vector已经做了归一化处理所以余弦相似度可以直接通过点积得到。两个文本语义越相近向量方向越一致相似度得分越高。4. 短时记忆与长期记忆存储实现4.1 短时记忆容量有限的滑动窗口短时记忆的特性是容量小、更新快。实现上最简单的方式是使用deque并设置maxlen。当新记忆写入时超出容量的旧记忆会被自动挤出。from collections import deque from typing import List, Optional class ShortTermMemory: def __init__(self, max_size: int 20): self.items: deque deque(maxlenmax_size) def add(self, item: MemoryItem): self.items.append(item) def recent(self, k: int 5) - List[MemoryItem]: return list(self.items)[-k:] def hit(self, content: str) - Optional[MemoryItem]: for item in self.items: if item.content content: item.touch() return item return Nonemax_size是短时记忆的容量上限。这个值应该与模型上下文窗口大小匹配。如果上下文窗口只能容纳 5000 token那短时记忆塞得太多也没有意义因为最终无法全部进入模型。4.2 长期记忆持久化存储与向量索引长期记忆在演示中可以用一个简单的列表实现同时保存每条记忆的向量方便后续检索。class LongTermMemory: def __init__(self, dim: int 256): self.dim dim self.items: List[MemoryItem] [] self._vectors: List[List[float]] [] def save(self, item: MemoryItem): self.items.append(item) self._vectors.append(hash_vector(item.content, self.dim)) return len(self.items) - 1 def vector_search(self, query: str, top_k: int 3): qvec hash_vector(query, self.dim) scored [] for idx, vec in enumerate(self._vectors): score cosine_sim(qvec, vec) scored.append((score, idx, self.items[idx])) scored.sort(keylambda x: x[0], reverseTrue) return scored[:top_k]在生产环境中LongTermMemory应该替换为真正的持久化存储。这里有两种路线向量数据库路线使用 Milvus、Weaviate、Chroma 等向量数据库每条记忆写入时计算 Embedding检索时直接查相似向量。传统存储加索引路线使用 PostgreSQL、Redis 等存储记忆文本再配合 ES 或数据库扩展做关键词检索。演示版本的_vectors每次都在内存中遍历数据量小的时候没问题数据量到达十万条以上时就必须依赖专门的向量索引了。4.3 记忆固化从短时到长期短期记忆不会自动变成长期记忆需要一个“固化”过程。策略可以是短时记忆中的重要条目被重复访问或者本身重要性很高就会被转入长期记忆。def consolidate(short_term: ShortTermMemory, long_term: LongTermMemory, min_access: int 2, importance_threshold: float 0.75): promoted [] for item in short_term.items: if item.access_count min_access or item.importance importance_threshold: if not any(exist.content item.content for exist in long_term.items): long_term.save(item) promoted.append(item) return promoted这里有两个触发条件访问次数达到min_access或者重要性超过importance_threshold。同时还要做一次去重避免同一条记忆被重复写入长期记忆。固化是 Agent 记忆架构中很关键的一步。它决定了长期记忆的质量如果所有短期记忆都被固化长期记忆会迅速膨胀如果固化条件太苛刻重要信息又容易丢失。5. 记忆检索向量召回 BM25 RRF 融合5.1 向量检索向量检索擅长解决“语义相近”的问题。比如用户问“数据库应该选什么”即使记忆里没有出现“选”这个词只要出现过“数据库使用 PostgreSQL”语义向量也能把它们关联起来。上面LongTermMemory.vector_search已经实现了向量检索这里不过多重复。需要关注的是query 在进入检索前必须使用和记忆写入时相同的向量化方式否则相似度计算没有意义。5.2 BM25 关键词检索BM25 是一种经典的关键词检索算法它在 TF-IDF 的基础上加入了文档长度归一化

相关新闻

如何用 DBeaver 五步把 MySQL 数据搬进 PostgreSQL:跨数据库数据迁移完整实战教程

如何用 DBeaver 五步把 MySQL 数据搬进 PostgreSQL:跨数据库数据迁移完整实战教程

如何用 DBeaver 五步把 MySQL 数据搬进 PostgreSQL:跨数据库数据迁移完整实战教程 【免费下载链接】dbeaver Free universal database tool and SQL client 项目地址: https://gitcode.com/GitHub_Trending/db/dbeaver 把一整套表从 MySQL 挪到 PostgreSQL&a…

2026/11/17 2:15:01 阅读更多 →
如何为投稿生成AI使用声明?Academic Research Skills disclosure模式与15个期刊政策数据库

如何为投稿生成AI使用声明?Academic Research Skills disclosure模式与15个期刊政策数据库

如何为投稿生成AI使用声明?Academic Research Skills disclosure模式与15个期刊政策数据库 【免费下载链接】academic-research-skills Academic Research Skills for Claude Code: research → write → review → revise → finalize 项目地址: https://gitcode…

2026/11/17 2:15:01 阅读更多 →
贝壳算法岗笔试2023卷2考点拆解:KMP到XGBoost全覆盖

贝壳算法岗笔试2023卷2考点拆解:KMP到XGBoost全覆盖

2023届秋招那会儿,贝壳找房的算法岗笔试一共出了好几套卷子,这套“卷2”的题型和考点组合很有代表性,覆盖了数据结构、经典算法、机器学习基础以及业务场景设计几个大类,难度梯度也拉得比较开。当时我刷完这套题最大的感受是&…

2026/11/12 11:33:33 阅读更多 →

最新新闻

Electron桌面应用开发实战:从环境搭建到打包发布全流程

Electron桌面应用开发实战:从环境搭建到打包发布全流程

做前端这些年,我大部分时间都在跟浏览器标签页打交道,直到第一次把桌面应用跑起来,才发现原来自己一直被限制在地址栏和刷新按钮围起来的框框里。Electron这个词,最开始是在某段时间频繁出现在同事的讨论里,一个用HTML…

2026/11/16 8:22:12 阅读更多 →
滑盖智能锁T109深度解析:结构原理、安装调试与故障排查

滑盖智能锁T109深度解析:结构原理、安装调试与故障排查

简介:亚太天能T109滑盖智能锁产品说明书是一份PDF格式的官方技术文档,主要面向智能锁安装人员、终端用户及售后维护者,帮助快速掌握产品安装、配置与常见故障处理。全包仅1个PDF文件,大小4.37MB,内容结构清晰&#xff…

2026/11/16 6:41:34 阅读更多 →
PMSM弱磁控制原理与Simulink建模:高速AGV驱动系统设计指南

PMSM弱磁控制原理与Simulink建模:高速AGV驱动系统设计指南

上个月我在调试一台高速AGV的驱动系统,整车要求空载跑到8m/s,电机转速已经拉到额定点,驱动器的输出电压也顶到了母线电压极限附近。再往上踩速度指令,转速纹丝不动,三相电流反而开始震荡。那会儿我的第一反应就是&…

2026/11/16 8:22:12 阅读更多 →
C++核心知识点:从内存管理到STL的实战指南

C++核心知识点:从内存管理到STL的实战指南

C 这门语言我前前后后折腾了十几年,用它写过嵌入式驱动、做过游戏服务端,也搭过基础组件库。每次看到新人一头扎进"C 核心知识点"这个搜索词,我其实挺感慨的——这门语言的难点从来不是语法多,而是知识点之间的耦合太深…

2026/11/16 8:22:12 阅读更多 →
T109滑盖智能锁怎么装?安装调试与故障排查全攻略

T109滑盖智能锁怎么装?安装调试与故障排查全攻略

简介:亚太天能T109滑盖智能锁产品说明书以PDF格式发布,适合智能锁用户、安装人员与售后维修人员阅读。内容围绕T109系列指纹密码刷卡锁展开,先介绍前面板、后面板、锁体、机械钥匙、电池盒盖等部件名称与功能,再给出完整安装步骤&…

2026/11/16 7:30:18 阅读更多 →
LLM知识降熵:从信息垄断到理解权下放

LLM知识降熵:从信息垄断到理解权下放

你有没有过这种经历:翻开源码注释、论文摘要或者一份专业报告,每个字都认识,连在一起却像天书。想找人聊聊,身边要么没人懂,要么懂的懒得跟你解释。后来我试着把同一段内容丢给一个大语言模型,几秒钟之后&a…

2026/11/16 8:22:12 阅读更多 →

日新闻

周新闻

月新闻