AgentScope记忆模块实战：从TemporaryMemory到DbMemory部署与调优-代码聚汇网

AgentScope记忆模块实战：从TemporaryMemory到DbMemory部署与调优

交易员.Coder·2026-09-02·阅读 106 GEO检测（免费）

AgentScope记忆模块DbMemory

|难度：普通|阅读约 34 分钟

1. 为什么要用AgentScope记忆模块，而不是自己存对话记录

我先说一个我自己踩过的坑。前两年做多轮对话应用，第一版为了图省事，直接用Python字典把用户说的话堆在一个列表里，每轮对话把整个列表塞给模型。结果用户聊了二十多轮之后，光是历史消息就占了几千个token，模型经常答非所问，而且服务一重启，用户上午聊的内容下午就全忘了。那时候我就意识到，所谓“记忆”，不是简单把消息存下来就完事，而是要在合适的时机取合适的部分，还要考虑遗忘、压缩、持久化。

后来我接触到AgentScope，发现它把记忆这块做成了一个独立模块，不是简单封装一个list完事。它抽象出了MemoryBase统一接口，提供了TemporaryMemory做临时记忆，还提供了DbMemory对接一个独立部署的agent-memory-server记忆服务。这个架构有几个直接好处：记忆的存取逻辑从业务代码里抽离出来了，多智能体可以共享同一份记忆存储，而且底层支持向量检索和快照压缩，记忆不会无限膨胀。

这篇文章我就围绕两件事展开：一是AgentScope内置记忆模块的设计思路和常用API，二是怎么从零把agent-memory-server部署起来，然后在代码里通过DbMemory接上它。整个过程我会按实际操作的顺序来写，每个参数的含义、每个配置项的作用都尽量说透，适合正在用AgentScope做多智能体应用、又觉得临时记忆不够用的开发者参考。

先说结论：如果你的智能体只需要单次会话内的上下文，TemporaryMemory就够了；但只要是做长期用户画像、跨会话记忆、多个Agent共享记忆这类场景，就直接上DbMemory加agent-memory-server，省得以后重构。

需要模型API调用？免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。

2. 记忆模块的核心设计：从接口抽象到两种内置实现

2.1 MemoryBase：为什么所有记忆类都要统一接口

AgeentScope的记忆模块不是一上来就给你一个大而全的类，而是先定了一个抽象基类MemoryBase。这个基类把记忆操作收敛成了几个核心方法，主要包括add、get_relevant_messages、get_retrieval_results、get_important_messages、delete、clear这一组。如果你用过LangChain的BaseChatMemory，会发现思路类似，但AgentScope的接口更偏消息级别而非字符串级别。

统一接口的意义在于，业务代码只依赖MemoryBase，不依赖具体实现。今天你项目里用的是临时内存，明天想切换成数据库持久化，只需要把实例换一下，Agent的消息流程完全不用动。我在实际项目里深有体会，前期不抽象，后期换存储方案的时候要动的地方太多了。

我自己在写自定义记忆类的时候，也习惯继承MemoryBase再实现这几个方法。比如我做过一个按用户ID分片的记忆类，底层用Redis存Message列表，add方法就是往对应用户的list里push，get_relevant_messages就是取最近N条再把超过阈值的消息过滤掉。因为接口是统一的，Agent代码里完全感知不到底层是Redis还是SQLite。

2.2 TemporaryMemory：临时记忆的遗忘策略

TemporaryMemory是AgentScope默认最常用的记忆实现，适合单轮会话或者不需要跨进程持久化的场景。它的核心参数有两个，一个是memory_size，控制最多保留多少条消息，另一个是memory_expire_time，控制消息存活时间。这两个参数不是叠加使用的，而是分别触发不同的清理机制。

memory_expire_time的作用是过期清理。每条消息写入时会带上时间戳，当记忆模块发现某条消息的存在时间超过设定值，就把这条消息丢弃。这一点在做定时任务型Agent时特别有用。比如每天早上九点运行的日报Agent，如果设置了6小时过期，那么它每轮启动时记忆都是干净的，不会把昨天的旧消息带进来。

memory_size的作用是容量淘汰。当消息条数超过上限时，TemporaryMemory会按照先入先出的策略丢弃最旧的消息。这个策略看着简单，但在实际对话场景里其实很合理，因为对话的最近上下文往往对当前回复影响最大。用过ChatGPT类产品的朋友应该能理解，聊天记录太长的时候，最早的几句可能已经完全跑题了。不过要注意的是，TemporaryMemory的淘汰是最基础的FIFO，不会根据消息重要性做智能筛选，所以它的定位就是轻量临时方案。

2.3 DbMemory：真正能跨会话长期保存的记忆

DbMemory是AgentScope连接agent-memory-server的桥梁。它的构造函数里有几个关键参数，我一个个说。

server_host和server_port就不用多解释了，是agent-memory-server的地址和端口。llm参数用来做快照压缩，也就是把一段冗长的历史对话交给大模型总结成一个简短摘要，从而控制记忆的存储体积。embedding_model参数用来对消息做向量化，这样查询时可以通过向量相似度检索到语义相关的历史消息，而不是单纯靠关键词匹配。

还有一个参数是snapshot_interval，表示每隔多少条消息触发一次快照。这个参数我刚开始没重视，默认值偏大，结果对话长了之后历史消息仍然会膨胀。后来调小到20左右，记忆的token占用明显下降。另外还有个ignore_older_than参数，用来过滤太久远的消息，避免检索时把过时信息捞出来。

实际使用中，DbMemory内部的工作流程大致是这样的：add消息时先把消息发送给agent-memory-server存储，同时生成向量索引；get_relevant_messages时把查询消息也向量化，然后到服务端做相似度检索，返回Top-K条相关消息。快照则在消息数量达到snapshot_interval时触发，服务端会把旧消息交给配置好的LLM生成摘要，再压缩存储。

我刚开始用DbMemory的时候犯过一个错误，就是只配了server_host和server_port，没配llm和embedding_model。结果记忆能存进去，但查询时返回的结果基本不相关，快照功能也一直没生效。后来把这两个模型参数补齐之后，整个记忆模块才算真正跑起来。

3. 部署agent-memory-server：从构建到启动的完整过程

3.1 环境准备：JDK、Maven、Zookeeper一个都不能少

agent-memory-server是个Java后端服务，所以第一件事就是把Java环境准备好。我建议用JDK 8或JDK 11，别一上来就装JDK 17，因为agent-memory-server的构建脚本和依赖对JDK版本有要求，版本太高反而容易遇到编译问题。Maven建议3.6以上。

除了JDK和Maven，还要准备Zookeeper。agent-memory-server用Zookeeper做服务注册和服务发现，客户端连接时不是直连某个固定节点，而是先去Zookeeper找到可用的记忆服务实例。这个设计的好处是服务可以横向扩容，多实例部署时客户端自动负载均衡。但缺点是部署时多了一个依赖，很多人第一次跑不起来就是因为忘了启动Zookeeper。

如果你本地没有Zookeeper，我推荐直接用Docker起一个，省去下载解压配置的麻烦。启动命令大致是这样的：

bash复制docker run -d --name zookeeper -p 2181:2181 zookeeper:3.6

Zookeeper起来之后，可以用zkCli.sh -server 127.0.0.1:2181验证一下连接，能连上就说明没问题。

3.2 构建服务端：用build.sh一步到位

环境准备好之后，进入agent-memory-server的源码目录。这个目录一般在AgentScope源码的server目录下。构建方式很简单，直接执行：

bash复制bash build.sh

build.sh会自动下载依赖、编译代码、打包成可执行的jar包。构建完成后，在target目录下会生成一个类似agent-memory-server-1.0-SNAPSHOT.jar的文件。我第一次构建的时候等了将近五分钟，主要是Maven在拉依赖，网络不好的时候可能更久，耐心等就行。

构建完成后，接下来是修改配置文件。agent-memory-server的配置在conf目录下，通常是application.properties。需要关注的配置项有服务端口、Zookeeper地址、存储相关配置等。默认的服务端口是8000，如果和本机其他服务冲突就改掉。Zookeeper地址要改成你实际部署的IP，如果是本机就是127.0.0.1:2181。

3.3 启动服务端：参数配置和验证

配置改好之后，启动命令就是一个标准的Java命令：

bash复制java -jar agent-memory-server-1.0-SNAPSHOT.jar

如果启动成功，日志中会显示服务监听的端口信息，同时会有连接Zookeeper成功的注册日志。这时候可以再开一个终端，到Zookeeper里看一下服务节点是否注册成功：

bash复制zkCli.sh -server 127.0.0.1:2181
ls /agentscope/memory

能看到服务节点列表就说明注册成功了。这里我想强调一点，如果在日志里看到端口启动成功，但Zookeeper里一直看不到节点，优先检查配置文件的Zookeeper地址是否写错，其次是防火墙是否拦截了2181端口。

3.4 服务端配置项说明

agent-memory-server的配置项不算多，但每个都值得理解。我把几个重点列出来：

server.port：gRPC服务监听端口，默认8000，客户端配置的server_port要与此一致。
zookeeper.address：Zookeeper连接地址，支持逗号分隔的集群地址。
storage.type：底层存储类型，支持sqlite和mysql。单机测试用sqlite就行，生产环境建议切mysql。
embedding.model：服务端做向量化用的模型标识，客户端传入的embedding_model需要与服务端配置匹配。

我在测试时直接用默认的sqlite存储，省掉了额外部署数据库的麻烦。但如果你要对接生产环境，强烈建议提前把storage.type切成mysql，因为sqlite在高并发写场景下会出现锁竞争，多Agent同时写记忆时会响应变慢。

4. 在客户端接入DbMemory，让Agent真正具备长期记忆

4.1 最小可用示例：创建带记忆的Agent

服务端部署好之后，客户端接入就简单了。首先确保安装的是支持DbMemory的AgentScope版本。新版本对旧版本的兼容性总体不错，但记忆模块的API有过调整，建议优先用较新的版本并参考官方文档核对参数名。

下面是一个最小示例，创建一个AgentBase实例，给它挂上DbMemory，然后写入几条消息再查询：

python复制from agentscope.agent import AgentBase
from agentscope.message import Msg
from agentscope.memory import DbMemory
from agentscope.models import OpenAIChat

# 初始化模型，用于快照压缩
llm = OpenAIChat(
    model_name="gpt-4o",
    api_key="YOUR_API_KEY",
)

# 初始化记忆，连接agent-memory-server
memory = DbMemory(
    server_host="127.0.0.1",
    server_port=8000,
    llm=llm,
    snapshot_interval=20,
)

agent = AgentBase(
    name="assistant",
    model=llm,
    memory=memory,
)

# 写入记忆
agent.memory.add(Msg(name="user", role="user", content="我叫小明，喜欢喝美式咖啡"))
agent.memory.add(Msg(name="user", role="user", content="我想在北京找一份数据分析师的工作"))

# 查询记忆
results = agent.memory.get_relevant_messages("这个用户喜欢什么咖啡？")
for msg in results:
    print(f"{msg.name}: {msg.content}")

运行这段代码后，如果能正确返回包含“美式咖啡”的消息，说明客户端到服务端的通道已经打通。

4.2 get_relevant_messages：语义检索不是字符串匹配

DbMemory的get_relevant_messages和TemporaryMemory的get_relevant_messages在行为上有个明显区别，TemporaryMemory会退化成基于关键词的简单过滤，而DbMemory走的是向量检索。查询消息先被embedding模型向量化，然后到agent-memory-server的向量索引里搜最接近的Top-K条。

这里有个实际经验：向量检索的效果强依赖embedding_model的选择。我试过用通用中文embedding模型，在技术类对话上表现不错，但在游戏领域就很一般。建议你根据自己的业务数据，跑几个查询样例对比一下检索结果相关性，再决定embedding模型。另外，get_relevant_messages可以传top_k参数控制返回条数，默认值如果偏大，会导致LLM上下文体积增大，推理成本上升。

4.3 多Agent共享记忆：一个值得注意的用法

DbMemory的另一个好处是支持多Agent共享同一个记忆服务。比如一个团队Agent、一个财务Agent、一个客服Agent，它们虽然负责不同职责，但都可以读写同一个用户对象的历史记录。实现上只需要让这些Agent指向同一个server_host和server_port即可。

但共享之后要注意一个坑，Agent之间如果没有做会话隔离，A写入的记录B也能查到。我当时处理的方式是在消息的metadata里加一个session_id字段，查询时先按session_id过滤再交给LLM。AgentScope的Message对象支持metadata扩展字段，这个方案实现起来不难，却能让多Agent共享记忆时保持数据隔离。

5. 记忆的遗忘、压缩与参数调优：别让记忆变成负担

5.1 遗忘机制：什么时候该忘记

很多人在设计记忆系统时只想着怎么记住更多，但在实际运行中，遗忘同样重要。AgentScope的TemporaryMemory通过memory_size和memory_expire_time实现遗忘，DbMemory则通过ignore_older_than参数来控制检索时忽略太久远的内容。

ignore_older_than这个参数我建议设置上，并且要根据业务场景调整。比如做短期任务型对话的Agent，三天前的消息基本没有参考价值，设成3天可以降低检索噪音。而做用户长期兴趣分析的Agent，可能需要保留数周甚至数月的记忆，那就可以把时间窗口拉长，或者干脆不设置限制。

5.2 快照压缩：为什么需要大模型参与记忆整理

DbMemory的快照机制是它区别于普通日志存储的核心功能。当消息条数达到snapshot_interval时，agent-memory-server会调用配置的LLM，把当前积累的历史消息合并成一个摘要。这样做的好处有两个，一是减少存储占用，二是提升检索效率，因为摘要本身可以被向量化，后续检索时能直接命中摘要。

我在实测中遇到过一个问题，快照生成了，但摘要内容非常模板化，丢失了大量细节。后来排查发现是我在初始化Llama时给的system prompt太简单，相当于没有引导模型做信息保留。后来我在快照前给LLM加了一段提示词，让它保留实体、时间、地点、用户偏好这些关键信息，摘要质量明显提升。

5.3 参数取值建议

根据我在项目里的经验，有几个参数取值可以供参考：

snapshot_interval：对话密集型应用建议20到30，非密集型可以设成50。设太小会导致频繁调用LLM做摘要，成本上升；设太大则记忆膨胀，检索变慢。
ignore_older_than：短期任务型Agent建议3到7天，长期用户分析型Agent建议30天以上。
top_k：检索返回条数建议4到8条，太多会引入噪音，太少可能丢信息。

这些参数没有绝对正确答案，最好结合你的token成本预算和对话场景做几组A/B对比。我自己是先按默认值跑通流程，再逐步调参，观察检索结果的相关性和响应时延变化。

6. 常见问题与排查实录：部署和接入阶段我踩过的坑

6.1 服务端部署阶段的问题

问题一：服务启动时报连接Zookeeper超时。这个基本就是Zookeeper没启动，或者启动的服务端口和配置不一致。先确认2181端口能不能通，再确认application.properties里的zookeeper地址是否写成127.0.0.1了。要注意，如果Zookeeper跑在Docker里，容器内和容器外的网络模式不同，映射端口要做对。

问题二：服务启动了，但Zookeeper里看不到注册节点。这种情况多半是配置里的Zookeeper根节点路径和客户端不一致。检查一下配置文件中是否有namespace之类的前缀配置，确保客户端和服务端一致。

问题三：端口8000被占用。这个最简单，改配置重启就行。但要注意客户端DbMemory初始化时的server_port也必须同步修改，否则会出现客户端连错服务的现象。

6.2 客户端接入阶段的问题

问题一：DbMemory初始化时一直超时。先确认服务端进程还活着，再用telnet测一下8000端口是否通。我遇到过一种情况，服务在服务器上监听的是127.0.0.1，而客户端在另一台机器访问，自然不通。解决办法是让Java服务监听0.0.0.0，也就是在启动参数或配置里把绑定的地址改成全网卡。

问题二：记忆能写入，但get_relevant_messages返回结果为空。这个问题我排查了很久，最终发现是embedding_model没有配置，或者配置的模型不对。DbMemory检索依赖向量相似度，如果embedding没生效，检索就会落空。

问题三：快照一直不生成。快照触发有两个条件，一是消息条数达到snapshot_interval，二是配置了有效的llm实例。如果llm的API Key失效或者网络不通，快照会静默失败，日志里不一定有明确报错。我在排查时会手动调大日志级别，看有没有调用LLM失败的记录。

6.3 使用阶段的问题

问题一：多Agent共享记忆导致信息混乱。这个前面提过，解决方案是给消息加session_id之类的元数据字段，在查询时做过滤。

问题二：记忆服务端存储膨胀。如果长期运行不上快照，或者快照间隔设置太大，存储量会持续增长。建议定期检查存储占用，并监控快照生成数量。

问题三：中文内容检索效果差。embedding模型对中文的支持差异很大，我测过几个通用模型，某些模型在中文长文本语义匹配上表现明显弱。建议在正式接入前，准备一组中文测试样例，分别验证记忆查询的命中率。

7. 深度实践：一个带长期记忆的客服Agent完整示例

为了让你把上面的内容串起来，我这里给出一个更贴近实际场景的完整代码示例。这个示例模拟一个社区客服Agent，它能记住用户上次反馈的问题，并在下次对话时主动关联。

python复制from agentscope.agent import AgentBase
from agentscope.message import Msg
from agentscope.memory import DbMemory
from agentscope.models import OpenAIChat

llm = OpenAIChat(model_name="gpt-4o", api_key="YOUR_API_KEY")

memory = DbMemory(
    server_host="127.0.0.1",
    server_port=8000,
    llm=llm,
    snapshot_interval=20,
    ignore_older_than=7 * 24 * 3600,  # 7天
)

agent = AgentBase(
    name="community_service",
    model=llm,
    memory=memory,
)

def handle_user_message(user_id: str, content: str) -> str:
    session_id = f"user_{user_id}"
    # 写入当前消息
    agent.memory.add(Msg(
        name="user",
        role="user",
        content=content,
        metadata={"session_id": session_id},
    ))
    # 查询历史相关消息
    history = agent.memory.get_relevant_messages(content, top_k=5)
    # 过滤当前会话的旧消息
    relevant_session = [
        msg for msg in history
        if msg.metadata.get("session_id") == session_id
    ]
    # 组装上下文
    context = "\n".join([f"{msg.name}: {msg.content}" for msg in relevant_session])
    prompt = f"用户当前说：{content}\n\n用户历史信息：\n{context}"
    response = agent.reply(Msg(name="user", role="user", content=prompt))
    # 写入回复
    agent.memory.add(Msg(
        name="assistant",
        role="assistant",
        content=response.content,
        metadata={"session_id": session_id},
    ))
    return response.content

# 模拟两次对话
print(handle_user_message("u001", "我的订单三天了还没发货"))
print(handle_user_message("u001", "你之前说帮我查的物流有结果了吗"))

这个示例里做了几件关键的事情：用session_id区分不同用户，写入和查询都带上元数据；查询历史时先经过向量检索，再按session_id过滤；回复结果也写回记忆，保证上下文连续。这套流程跑通之后，一个带长期记忆的Agent就已经具备雏形了。

我实际测试时，第二次问“你之前说帮我查的物流有结果了吗”，因为向量检索能命中之前订单相关的消息，Agent能准确回忆起订单号和之前的处理承诺。这种体验是临时记忆无法做到的。

8. 我对记忆服务选型的一些体会

如果只说一条心得体会，我会说：不要一开始就追求复杂的记忆方案。先用TemporaryMemory把业务流程跑通，确认整个Agent的对话链路没问题，再引入DbMemory和agent-memory-server。因为记忆服务一旦接入，排查问题的维度会多一层，服务端、客户端、Zookeeper、embedding模型、LLM快照，任何一环出问题都会影响记忆效果。

另外，agent-memory-server单机部署在测试环境完全够用，但上生产之前，我建议先确认底层的存储类型和容量规划。如果团队里已经有运维体系，可以用容器的方式把记忆服务、Zookeeper这些依赖都编排起来，避免手工启动多个进程的麻烦。我自己的项目里，是把Zookeeper和agent-memory-server分别放在两个容器里，通过docker-compose管理，这样每次重新部署环境都不用手忙脚乱。

最后分享一个小技巧，调试记忆模块的时候，先手动调用add写入几条固定消息，再手动调用get_relevant_messages看看能不能查出来。这个“写入再查询”的链路如果能走通，再把它挂到Agent上，排查问题会轻松很多。后面如果你要接入LangChain，也可以复用这套记忆服务思路，只需要在Agent的模型调用层做一个兼容封装即可。