agno v2.8.4 发布：实体记忆全面改造，四工具驱动第二大脑能力升级

2026年7月27日，agno 正式发布 v2.8.4 最新版本。本次版本共包含 5 个提交、92 个文件变更，并由 9 位贡献者参与。整体代码变更规模达到 9,675 行新增、3,736 行删除。

从本次更新内容来看，v2.8.4 的核心重点并不只是常规修复，而是围绕学习系统中的实体记忆能力进行了一次明显的架构调整。原有实体记忆的自动提取模式被收敛，新的设计将实体记忆明确调整为仅支持 AGENTIC 工作方式，也就是由智能体主动通过工具调用完成实体信息的记录、关联、检索和遗忘。

与此同时，本次版本还修复了嵌套执行器需求序列化问题、Skill 脚本与引用工具处理空路径参数的问题，并新增 TrustedRouter 作为 OpenAILike 模型类。

一、本次 v2.8.4 更新概览

v2.8.4 于 2026 年 7 月 27 日发布，更新内容包括以下五项：

• 修复嵌套执行器需求无法正确序列化的问题
• 修复 Skill 脚本工具和引用工具无法接受空路径参数的问题
• 新增 TrustedRouter，使其作为 OpenAILike 模型类接入
• 重构第二大脑中的实体记忆能力
• 完成 v2.8.4 正式版本发布流程

从提交时间看，前三项修复与新增功能在 2026 年 7 月 26 日完成，实体记忆改造以及版本发布提交则在 2026 年 7 月 27 日完成。

本次变更涉及 92 个文件，说明实体记忆改造并非单点功能更新，而是牵动了示例、学习模块、团队学习示例、测试日志以及实体记忆专题示例等多个部分。

二、修复嵌套执行器需求序列化问题

本次版本首先修复了嵌套执行器需求的序列化问题。

对于具备多层执行结构的场景，执行器之间可能存在嵌套的依赖需求。当这些需求需要被保存、传递或重新构建时，若序列化过程无法正确处理嵌套层级，就可能导致配置丢失、结构异常或执行行为不一致。

v2.8.4 对这一问题进行了修复，使嵌套执行器需求能够被正确序列化。

虽然本次提供的内容没有展示该修复的具体实现代码，但提交说明已经明确指出，该问题属于嵌套执行器 requirements 的序列化修复。这意味着新版在处理复杂执行器配置时，将更好地保留原始需求结构。

三、Skill 脚本与引用工具支持空路径参数

第二项修复涉及 Skill 系统中的脚本工具与引用工具。

此前，当路径参数为空值时，相关工具可能无法正确接受或处理该参数。本次 v2.8.4 更新后，Skill 脚本工具和引用工具均支持接收空路径参数。

这一修复的目标非常明确：让工具调用在路径信息缺失或显式传入空值的情况下，仍然能够按照预期完成参数处理，而不是直接因为空路径导致失败。

本次提交说明中使用的是“accept null path args”，即接受空路径参数。该更新属于工具调用参数兼容性修复，有助于减少调用链路中的参数异常。

四、新增 TrustedRouter 作为 OpenAILike 模型类

v2.8.4 新增了 TrustedRouter，并将其纳入 OpenAILike 模型类体系。

这项更新意味着 TrustedRouter 可以按照 OpenAILike 模型类的方式进行使用和集成。对于项目中已经采用 OpenAILike 模型接口或模型抽象方式的场景而言，TrustedRouter 的加入使其能够进入统一的模型使用结构。

本次提供的更新内容没有给出 TrustedRouter 的具体初始化方式、参数结构或调用示例，因此可以确认的信息是：

• TrustedRouter 已被新增
• TrustedRouter 被定义为 OpenAILike 模型类
• 该功能已作为 v2.8.4 的正式更新内容发布

五、实体记忆迎来核心改造：从自动提取转向四工具驱动

本次 v2.8.4 最值得关注的变化，是第二大脑中的实体记忆重构。

实体记忆用于保存智能体对外部世界的知识。它关注的不是用户本身，而是用户周围的人、项目、公司、系统以及其他外部实体。

可以将两类记忆区分为：

• 用户记忆：关于用户自己的信息
• 实体记忆：关于用户所在世界中的人、项目、公司、系统等信息

在 v2.8.4 之前，实体记忆示例中存在 ALWAYS 模式和 AGENTIC 模式两种方式。而本次更新后，实体记忆被明确调整为仅支持 AGENTIC 模式。

也就是说，实体记忆不再通过自动提取流程进行维护，而是由智能体借助四个工具主动记录、关联、搜索和遗忘实体信息。

新的实体记忆能力围绕以下四个工具构建：

• remember_about
• link_entities
• search_entities
• forget

这四个工具共同构成实体记忆的新操作界面。

六、四个实体记忆工具分别解决什么问题

v2.8.4 中，实体记忆被定义为智能体关于世界的知识库。智能体围绕实体信息执行记录、关系建立、检索和清理操作。

1. remember_about：记录或更新实体信息

remember_about 用于根据名称新增或更新实体。

它可以记录的信息包括：

• 实体事实
• 实体事件
• 实体描述
• 笔记指针

在这个过程中，实体名称的解析和统一由存储层负责。实体标识会根据名称进行 slug 化处理，因此即使名称存在大小写差异，也可以被识别为同一个实体。

例如，某个名称以不同大小写形式出现时，存储层会将它们解析到同一个人或同一个实体上，而不会因为输入形式不同创建多个重复记录。

这项机制的重点在于：智能体负责表达要记录什么，存储层负责处理实体标识、名称规范化和实体归并。

2. link_entities：建立实体之间的关系

link_entities 用于记录实体之间的关系。

例如，一个项目与某位负责人之间可以形成关系；一个公司与其负责人、产品、系统之间也可以形成关系。

本次更新特别说明，关系边会保存在两个实体上。也就是说，当两个实体被建立关联后，这条关系不是只保存在单侧，而是会同时体现在双方实体记录中。

这种设计使实体关系能够从不同方向被访问和检索。

3. search_entities：搜索实体或按最近使用情况列出实体

search_entities 用于查找实体。

它支持两种核心使用方式：

• 根据查询条件搜索相关实体
• 不传入查询条件时，按照最近使用情况列出实体

这意味着 search_entities 不只承担关键词搜索职责，也可以用于查看近期实体目录。

在实体记忆中，实体目录和相关性召回共同参与上下文构建。即使是新的会话，只要系统能够根据当前问题找到相关实体，之前记录的信息仍然可以被注入到当前对话上下文中。

4. forget：遗忘事实或归档整个实体

forget 用于处理过时、不再需要或应当归档的记忆。

它支持两类操作：

• 退役某一条事实
• 归档整个实体

这里的“退役事实”并不等于物理删除。实体记忆强调的是事实的演进过程。对于出现修正的信息，系统不会简单粗暴地覆盖旧内容，而是将旧事实标记为失效或退役，让新事实成为当前有效信息。

七、事实修正机制：新事实会自动取代旧事实

v2.8.4 的实体记忆改造中，一个非常关键的能力是事实 supersession，也就是事实替代或事实继任机制。

当新的事实与旧的事实发生冲突时，新的信息会使旧信息退役。

例如，一个项目此前处于“因审核受阻”的状态，之后又明确说明该项目已经完成上线。此时，“受阻”这一旧状态不会继续作为当前有效事实存在，而会被新的“已上线”事实替代。

本次更新明确说明：

• 修正信息本身就是新事实
• 新事实会自动使旧事实退役
• 被替代的旧事实不会被直接删除
• 事实展示时会携带截至日期信息
• 较新的事实优先于较旧的事实

这种方式保证了实体记忆不只是保存一个静态结果，还能够表达信息的时间演变。

因此，实体记忆中的“已退役”事实仍然保留历史价值，但在当前知识表达中，最新事实拥有更高优先级。

八、基础示例合并：5_entity_memory.py 成为新的实体记忆入口

在基础学习示例目录中，v2.8.4 新增了：

cookbook/08_learning/01_basics/5_entity_memory.py

这个文件将原来的两个实体记忆示例统一为一个新的示例入口。

原先的两个文件被删除：

• cookbook/08_learning/01_basics/5a_entity_memory_always.py
• cookbook/08_learning/01_basics/5b_entity_memory_agentic.py

新的文件标题为“Entity Memory: The Four Tools”，即实体记忆：四个工具。

示例文件开头对实体记忆的定义非常明确：

• 实体记忆是智能体关于世界的知识
• 它关注用户周围的人、项目、公司和系统
• 它不同于用户记忆
• 用户记忆关注用户自身
• 实体记忆仅支持 AGENTIC 方式
• 智能体通过四个工具进行记录
• 存储层负责处理名称、标识和事实替代

该示例使用 PostgreSQL 作为数据库：

db=PostgresDb(db_url="postgresql+psycopg://ai:ai@localhost:5532/ai")

同时，为了保证每次运行演示时都拥有独立的干净空间，示例通过随机字符串生成命名空间：

NAMESPACE=f"basics_{uuid4().hex[:6]}"

这种写法的目的，是让每次演示运行从一个新的命名空间开始，避免历史演示数据互相干扰。

智能体初始化时配置了实体记忆：

learning=LearningMachine(entity_memory=EntityMemoryConfig(namespace=NAMESPACE),)

这里不再配置实体记忆的 ALWAYS 模式，而是直接配置带命名空间的 EntityMemoryConfig。

示例中的智能体定位为销售助手，并要求对笔记进行简短确认。

首次对话中，用户提供了一家公司、公司规模、所在地以及技术负责人等信息。智能体在第一个会话中记录这些实体信息。

随后，示例切换到一个新的会话，并询问“我们知道这家公司什么信息”。

这里要验证的核心能力是：

• 会话已经变化
• 实体目录仍然存在
• 相关性召回仍然能够带回相关知识
• 回答问题时不必再执行工具调用
• 已记录的实体信息可以直接通过注入上下文被用于回答

这也说明实体记忆的价值不局限于单一会话，而在于跨会话的世界知识延续。

九、团队学习示例同步调整

在团队学习示例中，文件：

cookbook/03_teams/12_learning/03_team_entity_memory.py

也进行了调整。

原先的配置中，实体记忆使用了 ALWAYS 模式：

entity_memory=EntityMemoryConfig(mode=LearningMode.ALWAYS,),

在 v2.8.4 中，这段配置被替换为：

entity_memory=EntityMemoryConfig(),

并附带说明：

# AGENTIC-only: the agent records through its four tools

这句说明直接点明了 v2.8.4 的设计变化：实体记忆仅支持 AGENTIC，智能体通过四个工具完成记录。

该团队示例中，用户档案仍然保持 ALWAYS 模式：

user_profile=UserProfileConfig(mode=LearningMode.ALWAYS,),

这进一步体现了用户档案与实体记忆的区别。

用户档案可以继续采用 ALWAYS 模式；实体记忆则不再采用自动提取模式。

十、团队 Agentic Learning 示例修正导入

文件：

cookbook/03_teams/12_learning/10_team_agentic_learning.py

中还包含一个导入调整。

更新前后出现的变化是 LearningMode 的导入来源调整。原先存在从一个位置导入 LearningMode 的写法，更新后使用了：

fromagno.learn.modeimportLearningMode

本次提供的差异信息显示，旧导入被删除，并保留了新的导入方式。

这项改动属于示例代码导入路径的整理，与实体记忆重构同步出现。

十一、提取限制示例移除实体记忆相关内容

文件：

cookbook/08_learning/01_basics/6_extraction_limits.py

在 v2.8.4 中删除了实体记忆相关配置和展示逻辑。

原先该示例中包含：

EntityMemoryConfig

并且在 LearningMachine 配置中设置了实体记忆的 ALWAYS 模式及独立限制：

entity_memory=EntityMemoryConfig(mode=LearningMode.ALWAYS,max_updates_per_run=15),

原有注释说明了不同存储的更新上限关系：

• LearningMachine 全局max_updates_per_run=5
• user_profile 继承全局上限 5
• user_memory 显式覆盖为 3
• entity_memory 显式覆盖为 15

更新后，实体记忆相关导入被删除，实体记忆配置也被删除。

保留下来的限制逻辑聚焦于：

• 用户档案
• 用户记忆

其中，用户档案使用 ALWAYS 模式，用户记忆使用 ALWAYS 模式并指定每次运行最多更新 3 次。

原先用于打印实体记忆搜索结果的代码也被删除，包括：

entities=lm.entity_memory_store.search(query="techcorp",limit=20)

以及打印实体记忆结果的逻辑。

原因已经在测试日志和 README 说明中明确：实体记忆已经没有自动提取流程，因此不再适用于 extraction limits，也就不存在提取过程中的更新次数限制问题。

换句话说，max_updates_per_run示例现在只用于用户档案和用户记忆，而不再覆盖实体记忆。

十二、基础学习 README 更新

文件：

cookbook/08_learning/01_basics/README.md

同步更新了实体记忆示例列表。

旧版本中包含两个实体记忆示例：

• 5a_entity_memory_always.py：ALWAYS 模式下的实体记忆提取
• 5b_entity_memory_agentic.py：AGENTIC 模式下的实体记忆管理

v2.8.4 中，这两个条目被删除，替换为：

• 5_entity_memory.py：四个实体工具，且在 2.8.4 中仅支持 AGENTIC

README 的变化准确反映了本次实体记忆能力的迁移结果：

• 两个模式示例合并为一个示例
• ALWAYS 模式实体记忆示例不再保留
• 四工具成为实体记忆的统一操作方式
• 实体记忆仅保留 AGENTIC 模式

十三、测试日志记录了实体记忆改造的验证结果

文件：

cookbook/08_learning/01_basics/TEST_LOG.md

也同步记录了这次实体记忆重构的测试情况。

测试日志新增说明指出：

• 原来的 5a 和 5b 示例已被5_entity_memory.py替代
• 实体记忆在四工具表面下仅支持 AGENTIC
• 新示例已经使用 gpt-5.5 实际运行验证
• 在第一个会话中，公司实体被成功记录
• 公司属性和技术负责人关系被成功记录
• 在第二个会话中，系统能够基于注入的信息回答问题
• 第二个会话的回答没有调用工具
• 6_extraction_limits.py不再包含实体记忆
• 原因是实体记忆没有提取流程，因此不存在需要限制的提取次数

测试日志中，新的5_entity_memory.py状态为 PASS。

其验证描述是：

• 通过四个实体工具完成记录
• 在一个会话中完成信息捕获
• 在全新的会话中完成信息召回

测试结果说明，实体记忆已经能够在首个会话中保存实体与关系，并在后续新会话中借助上下文注入完成回答。

与此同时，6_extraction_limits.py的说明调整为：

• max_updates_per_run只限制 user_profile 和 user_memory
• 实体记忆已从该示例中移除
• 原因是实体记忆不存在需要限制的提取过程

十四、实体记忆专题示例重构

在实体记忆专题目录中，原文件：

cookbook/08_learning/04_entity_memory/01_facts_and_events.py

已被删除。

新的文件为：

cookbook/08_learning/04_entity_memory/01_the_four_tools.py

该文件新增 86 行内容，完整展示了实体记忆的四工具工作方式，以及事实替代机制。

示例同样使用 PostgreSQL 数据库：

db=PostgresDb(db_url="postgresql+psycopg://ai:ai@localhost:5532/ai")

并生成每次运行独立的命名空间：

NAMESPACE=f"four_tools_{uuid4().hex[:6]}"

示例特别指出：

• 演示环境中使用新的命名空间，以便每次运行都从干净状态开始
• 真实部署环境中应固定一个命名空间
• 持久化本身正是实体记忆存在的意义

智能体初始化配置如下：

learning=LearningMachine(entity_memory=EntityMemoryConfig(namespace=NAMESPACE),)

智能体的角色是项目跟踪助手，要求在接收到信息后简短记录。

十五、专题示例演示了三轮实体记忆交互

新的01_the_four_tools.py示例包含三轮关键交互。

第一轮：记录项目与人员关系

第一轮中，用户要求追踪一个项目，并说明：

• 该项目当前被安全审核阻塞
• 某位人员是该项目的设计负责人

这一轮的目标是让智能体通过实体记忆工具记录：

• 项目实体
• 项目当前状态
• 人员实体
• 人员与项目之间的关系

这正对应 remember_about 和 link_entities 的使用方向。

第二轮：提交修正信息，触发事实替代

第二轮中，用户提供新的状态信息：

• 项目第一版已经在当天上线到生产环境

这条信息与第一轮中的“项目被审核阻塞”形成了状态演变。

示例明确指出，此时事实替代机制会让旧的“受阻”事实退役，而不是删除。

随后，示例会打印该项目当前有效的事实：

store.print(entity_id="radar",entity_type="project",namespace=NAMESPACE)

打印时关注的是“仍然有效的事实”。

旧的受阻信息虽然没有被物理删除，但已经退役，因此当前展示的重点是新的上线状态。

第三轮：在新的会话中完成召回

第三轮中，示例再次切换到一个新的会话，并询问项目相关信息。

此时要验证的是：

• 会话已经是全新的
• 实体目录仍然可用
• 相关性召回能够识别当前问题涉及的实体
• 系统能够将相关实体信息注入当前上下文
• 智能体可以回答关于该项目的问题

示例注释明确指出，实体目录加上相关性召回会注入当前轮次所关注的信息。

这与基础示例中跨会话召回公司的信息形成了呼应：实体记忆并不依赖原始会话持续存在，而是通过持久化实体信息和相关性召回，为新会话提供知识支持。

十六、v2.8.4 中实体记忆的最终使用方式

综合本次全部示例和代码变化，可以清晰看到 v2.8.4 对实体记忆的最终定位。

实体记忆不再使用 ALWAYS 自动提取模式。

实体记忆的操作方式收敛为四个工具：

• remember_about：记录或更新实体事实、事件、描述与笔记指针
• link_entities：建立实体关系，并在双方实体上保存关系边
• search_entities：按条件检索实体，或在没有查询条件时按最近使用情况列出实体
• forget：退役事实或归档实体

实体解析由存储层完成，包括：

• 名称 slug 化
• 大小写归一
• 同名实体合并
• 实体标识处理

事实演进由 supersession 机制处理，包括：

• 新事实自动替代旧事实
• 旧事实退役而非删除
• 事实附带截至日期
• 新事实优先级高于旧事实

实体记忆支持通过命名空间隔离不同的数据空间。

在示例中，随机命名空间用于保证演示环境的干净状态；在实际部署中，固定命名空间用于获得长期持久化的实体知识。

十七、总结：v2.8.4 的关键变化

代码地址：github.com/agno-agi/agno

agno v2.8.4 的更新重点可以总结为以下几个方面：

• 修复嵌套执行器需求序列化问题
• 修复 Skill 脚本与引用工具的空路径参数兼容问题
• 新增 TrustedRouter 作为 OpenAILike 模型类
• 全面重构第二大脑中的实体记忆
• 删除实体记忆 ALWAYS 模式示例
• 删除实体记忆自动提取限制相关配置
• 将实体记忆统一收敛为 AGENTIC 四工具模式
• 新增统一基础示例5_entity_memory.py
• 新增实体记忆专题示例01_the_four_tools.py
• 使用事实替代机制处理状态修正和知识演进
• 支持跨会话的实体目录与相关性召回
• 在测试日志中确认新实体记忆示例已通过实际运行验证

对于 v2.8.4 而言，实体记忆的变化不仅是 API 或示例文件名称的调整，更是学习机制使用方式的明确收敛。

用户档案和用户记忆仍然可以按照自动学习方式进行更新，而实体记忆则被定位为由智能体主动管理的世界知识库。通过记住实体、关联实体、搜索实体和遗忘实体，智能体能够持续构建关于项目、公司、人员和系统的结构化认知，并在新的会话中重新召回与当前问题最相关的信息。