最近在帮团队搭建多 Agent 协作平台时遇到了一个非常现实的问题每个 Agent 都能记住和用户的对话但 Agent 与 Agent 之间、不同业务会话之间记忆是相互孤立的。结果就是客服 Agent 刚跟用户确认了退货诉求转交给售后 Agent 后售后 Agent 完全不知道之前聊了什么只能让用户重新描述一遍。这种体验放在真实业务里几乎等于不可用。于是我开始研究 AI Agents 的“记忆层”设计也关注到了 TencentDB Agent Memory 这类面向团队级记忆共享的解决方案。本文就围绕“团队级 memory hub”这个概念展开讲清楚 AI Agent 记忆的分层逻辑、为什么单 Agent 记忆不够用、以及如何基于 TencentDB 这类云数据库底座设计一个可落地的多 Agent 共享记忆服务。内容会包含完整的架构思路、数据模型设计、核心代码示例和常见坑点适合正在做 Agent 应用落地、或者准备为多 Agent 系统设计记忆层的开发者。1. 背景AI Agent 的“记忆”到底缺什么1.1 单 Agent 记忆的技术现状在不少 AI 应用里“记忆”已经不是一个陌生词汇了。很多对话系统会保存用户的会话历史再把历史消息作为上下文拼接到大模型的请求里。这种做法可以追溯到早期的检索增强生成RAG架构——先把历史对话切片、向量化然后存到向量数据库里下次用户提问时先做相似度检索再把命中的历史片段交给模型参考。在单个 Agent 的层面这套方案是行得通的。一个 Agent 维护自己的 conversation history需要时自己查自己的记忆库逻辑上比较直接。但当我开始做多 Agent 协作时单 Agent 记忆的问题立刻暴露出来记忆隔离Agent A 积累的用户偏好、业务上下文Agent B 完全不可见。会话孤岛用户在不同会话里和不同 Agent 沟通历史无法串联。重复劳动每个 Agent 都要重新向用户确认已经提供过的信息。一致性差多个 Agent 对同一实体的状态理解不一致比如一个认为订单已退款另一个认为还在处理中。这些问题不是简单的“把历史消息存到同一个数据库”就能解决的因为还涉及记忆的归属、时效、共享范围、权限控制、更新策略等一系列问题。1.2 从对话历史到记忆层“记忆”和“对话历史”是两件事。对话历史是原始数据而记忆层是从原始数据中提炼出来的、可以被不同 Agent 复用的结构化知识。举个例子对话历史记录的是用户在某天某时说“我上次买的机械键盘空格键回弹有问题”。记忆层提炼的是用户有一个设备类型为机械键盘状态为“空格键回弹异常”关联订单号 XXX处理状态为“待售后跟进”。团队级 memory hub 的核心职责就是把散落在各个 Agent 手里的对话历史、状态信息、用户偏好汇总到一个统一的地方再按需提供给不同的 Agent 使用。TencentDB Agent Memory 的定位正是这种“team-level memory hub”它面向的是一个 Agent 团队而不是单个 Agent。1.3 为什么团队级记忆比个人记忆难做我一开始以为团队级记忆就是把个人记忆的数据表加一个 team_id 字段后来发现远远不止。个人记忆只需要服务一个 Agent它的读写模式相对简单而团队级记忆要面对的问题包括谁来写多个 Agent 都可能写入同一实体如订单、客户的记忆需要合并策略。谁来读不同 Agent 关注的信息维度不同客服关注情绪和诉求售后关注故障现象和售后进度运营关注转化和复购记忆服务要能按需提供不同视图。什么时候过期有些记忆是长期有效的用户收货地址、会员等级有些是短期有效的用户当前在活动页的浏览状态。可信度如何评判Agent 写入的记忆并不总是可靠的需要记录来源和置信度。如何避免干扰如果团队里有多个 Agent一个 Agent 的记忆写入不能对另一个 Agent 的检索结果造成持续污染。这些难点决定了团队级 memory hub 不能只是一个存储服务它需要包含写入、检索、更新、权限、生命周期管理等完整链路。2. TencentDB Agent Memory 是什么2.1 产品定位根据公开资料和相关设计思路TencentDB Agent Memory 是腾讯云数据库产品体系下面向 AI Agent 场景设计的一套记忆管理能力。它并不只是提供一个 MySQL 或 Redis 实例而是致力于成为整个 Agent 团队的共享记忆中枢Memory Hub让多个 Agent 可以围绕同一份业务上下文协作。从底层来看它构建在 TencentDB 的多种数据库引擎之上结合向量检索、KV 存储、结构化存储等能力为 Agent 的内存式短期记忆和外置长期记忆提供统一的读写接口。即便不依赖具体 SDK从架构思想来看它要解决的核心问题和业界讨论的“Agent Memory”方向是一致的让 AI Agents 拥有跨会话、跨 Agent、跨团队的记忆能力。2.2 Memory Hub 的抽象能力围绕“team-level memory hub”这一目标TencentDB Agent Memory 的产品设计大致包含以下几类核心能力记忆写入Agent 在运行过程中将用户偏好、业务关键信息、任务状态等写入记忆层。记忆检索其他 Agent 在需要时通过语义或结构化条件查询相关记忆。记忆更新与合并同一实体的记忆被多个 Agent 更新后系统需要解决冲突或保留最新版本。记忆过期与清理通过 TTL生存时间或业务规则自动清理过期记忆。权限与隔离不同团队、不同 Agent 之间的记忆数据相互隔离但同一团队内的 Agent 可以共享。来源可追溯每条记忆能追溯到是哪个 Agent、基于哪次会话写入的。这些能力组合起来就可以支撑起一个多 Agent 协作了。2.3 它和普通数据库的区别如果只是把对话记录存到 MySQL 里然后每次全量拼到 Prompt 里那不算使用 Memory Hub。区别在于普通数据库存储的是原始记录Memory Hub 存储的是经过结构化处理的记忆实体。普通数据库的查询条件是精确匹配Memory Hub 的检索可以是语义化的相似度匹配。普通数据库没有“记忆生命周期”的概念Memory Hub 明确管理记忆的创建时间、更新时间、过期时间、重要程度。普通数据库需要业务方自己处理多 Agent 写入冲突Memory Hub 会提供合并和版本控制机制。换句话说Memory Hub 是面向 AI Agent 应用场景的“记忆中间层”数据库是它底层的存储引擎。3. 团队级记忆系统的架构设计在了解了“是什么”之后我们来看“怎么设计”。无论最终选型是 TencentDB Agent Memory还是基于腾讯云数据库自建一套记忆服务架构设计上都有很多相通的地方。3.1 整体架构分层我习惯把团队级记忆系统拆成三层接入层面向各 Agent 提供读写记忆的 SDK 或 HTTP API。记忆管理层实现记忆的提取、结构化、更新策略、冲突处理、过期清理。存储层使用多种数据库引擎存储不同特性的记忆数据。接入层做的事情比较简单就是两件事往记忆库写东西、从记忆库查东西。真正复杂的是记忆管理层。Agent A ──┐ Agent B ──┼── Memory Hub API ── 记忆管理器 ── 存储层 Agent C ──┘ │ ├── 结构化记忆用户画像、订单状态 ├── 向量记忆语义检索 └── 短期 KV 记忆临时上下文在记忆管理层内部核心模块包括Extractor从 Agent 的对话原始文本中抽取结构化记忆。这个模块通常由大模型驱动例如判断“用户提到购买过机械键盘”是否可以转化为一条用户设备维度的记忆。Merger当新旧记忆冲突时决定保留哪个版本。常见的策略包括按时间覆盖、按来源优先级覆盖、多版本并存。Retriever根据 Agent 当前的查询需求从结构化数据和向量数据中召回最相关的记忆。Garbage Collector清理过期或无用的记忆。3.2 记忆的分类与存储选型不同特征的记忆适合用不同的存储引擎这部分我在实际项目里吃过不少亏。一开始我只用一个 MySQL 表存所有记忆结果向量检索做不了时效性高的缓存也没有独立出来导致两个问题一是 Agent 查一个“用户是否提到过退货”的语义问题时效果很差二是高频访问的短期记忆都在查库性能不够理想。后来我把记忆拆成三类分别使用不同存储记忆类型典型内容存储选型检索方式结构化记忆用户ID、订单状态、地址、偏好标签关系型数据库如 TencentDB for MySQL / TDSQL精确条件查询语义记忆用户描述过的问题描述、非结构化诉求向量数据库embedding 余弦相似度检索短期状态当前会话临时状态、最近一次操作记录Redis 或内存 KVKey 查询 TTL这种分层设计在 TencentDB Agent Memory 的架构思路里也能看到影子。它把不同存储引擎组合成一个对上层透明的 Memory HubAgent 不需要关心某条记忆到底存在哪个引擎里只需要按语义和条件调用即可。3.3 团队协作的核心机制团队级记忆和单 Agent 记忆最大的不同在于“共享”和“隔离”之间的平衡。一个团队里可能有十几个 Agent 并行工作它们共享同一个记忆池但并不是所有记忆对所有 Agent 都可见。在设计时我采用了一个较通用的做法为每条记忆存储多个维度的归属信息。team_id: 团队ID决定记忆归属哪个团队 agent_id: 写入该记忆的Agent scope: 可见范围例如 public(团队内可见)private(仅写入者可见) entity_type: 实体类型例如 order, user, ticket entity_id: 实体ID例如 order_12345这样在检索的时候就可以灵活控制团队内所有 Agent 都可以读 scopepublic 的记忆。只有指定的 Agent 才能读 scopeprivate 的记忆。按 entity_type entity_id 可以把同一实体的多个维度记忆聚合在一起。这个模型看起来简单但能解决多 Agent 场景里大部分共享和权限的问题。4. 环境准备与版本说明在进入代码之前先说明环境。因为不同版本的数据库和不同 Agent 框架差异较大下面的示例重点是演示设计思路和核心逻辑不依赖某个特定版本才能运行。4.1 基础环境操作系统Linux / macOS / Windows 均可示例使用 Linux 风格命令。开发语言Python 3.9本文示例使用 Python 编写记忆管理逻辑。数据库腾讯云 TencentDB for MySQL 8.0 或本地 MySQL 8.0 均可如果使用 TencentDB Agent Memory 的托管能力可以跳过部分存储细节。向量检索可以使用腾讯云向量数据库或本地使用 Chroma 等轻量方案演示。缓存Redis 6.x用于短期状态记忆。版本需要根据你的项目实际情况调整本文示例以常见环境为例重点演示配置思路。4.2 示例项目结构为了便于理解我把示例代码组织为一个简单的 Python 项目agent-memory-demo/ ├── memory/ │ ├── __init__.py │ ├── models.py # 记忆模型定义 │ ├── storage.py # 存储层封装 │ ├── extractor.py # 记忆提取(模拟) │ ├── manager.py # 记忆管理核心逻辑 │ └── api.py # 提供给Agent的读写接口 ├── test_agent.py # 模拟多Agent读写 └── requirements.txt5. 核心代码与实现思路这一节我会给出一个最小可运行的多 Agent 共享记忆实现思路。这里的代码不是官方 SDK 的调用代码而是一个架构演示帮助理解 Memory Hub 的核心机制。5.1 定义记忆模型首先定义一条记忆的数据结构。这里采用一个相对通用的模型包含归属、内容、生命周期和元信息。# 文件路径agent-memory-demo/memory/models.py from dataclasses import dataclass, field from datetime import datetime from typing import Optional dataclass class MemoryItem: memory_id: str team_id: str agent_id: str scope: str # public 或 private entity_type: str # 例如 user, order, ticket entity_id: str # 例如 user_001 content: str # 记忆内容可以是结构化JSON字符串 memory_type: str # structured, semantic, short_term importance: float # 重要程度0~1 created_at: datetime field(default_factorydatetime.now) updated_at: datetime field(default_factorydatetime.now) expire_at: Optional[datetime] None各字段说明memory_id记忆的唯一标识建议使用 UUID。team_id团队 ID实现团队级隔离。agent_id写入该记忆的 Agent ID。scopepublic 表示所有团队成员可见private 表示只有写入者可见。entity_type 和 entity_id用于把同一个业务实体的记忆聚合起来例如同一个订单的所有记忆。content记忆内容。对于结构化记忆可以存 JSON 字符串对于语义记忆可以存原文本。importance重要程度用于检索排序时加权。expire_at过期时间实现自动清理。5.2 存储层封装存储层我们做一个抽象接口方便替换成 TencentDB 或其他数据库。# 文件路径agent-memory-demo/memory/storage.py from typing import List, Optional from .models import MemoryItem class MemoryStorage: 记忆存储抽象接口 def save(self, item: MemoryItem) - None: raise NotImplementedError def get_by_id(self, memory_id: str) - Optional[MemoryItem]: raise NotImplementedError def search(self, team_id: str, entity_type: Optional[str] None, entity_id: Optional[str] None, agent_id: Optional[str] None, scope: Optional[str] None) - List[MemoryItem]: raise NotImplementedError def delete(self, memory_id: str) - None: raise NotImplementedError def update_content(self, memory_id: str, new_content: str) - None: raise NotImplementedError实际部署时如果使用 MySQLsearch方法对应的 SQL 大致如下SELECT * FROM agent_memory WHERE team_id %s AND (%s IS NULL OR entity_type %s) AND (%s IS NULL OR entity_id %s) AND (%s IS NULL OR agent_id %s) AND (%s IS NULL OR scope %s) AND (expire_at IS NULL OR expire_at NOW()) ORDER BY importance DESC, updated_at DESC在真实项目中我会把存储层替换成 TencentDB for MySQL 的客户端连接池并且为team_id entity_type entity_id建立联合索引确保高频检索不会全表扫描。5.3 记忆冲突处理团队级记忆最核心的难点是“多个 Agent 写入同一实体时如何合并”。下面给一个简单的合并策略实现。# 文件路径agent-memory-demo/memory/manager.py import json import uuid from typing import Dict, List, Optional from .models import MemoryItem from .storage import MemoryStorage class MemoryManager: 记忆管理核心逻辑 def __init__(self, storage: MemoryStorage): self.storage storage def add_memory(self, team_id: str, agent_id: str, entity_type: str, entity_id: str, content: Dict, scope: str public, memory_type: str structured, importance: float 0.5) - MemoryItem: 新增一条记忆。 如果同一实体下已经存在同类型的记忆则尝试合并。 existing_items self.storage.search( team_idteam_id, entity_typeentity_type, entity_identity_id, agent_idagent_id, scopescope ) for item in existing_items: if item.memory_type memory_type: # 模拟合并新的字段覆盖旧的字段 old_content json.loads(item.content) new_content json.loads(json.dumps(content)) old_content.update(new_content) merged_content json.dumps(old_content, ensure_asciiFalse) self.storage.update_content(item.memory_id, merged_content) return item item MemoryItem( memory_idstr(uuid.uuid4()), team_idteam_id, agent_idagent_id, scopescope, entity_typeentity_type, entity_identity_id, contentjson.dumps(content, ensure_asciiFalse), memory_typememory_type, importanceimportance, ) self.storage.save(item) return item def search_memory(self, team_id: str, entity_type: str, entity_id: str, agent_id: Optional[str] None) - List[MemoryItem]: 检索某个实体的记忆。 优先返回 public 记忆再返回当前 Agent 的 private 记忆。 public_items self.storage.search( team_idteam_id, entity_typeentity_type, entity_identity_id, scopepublic ) private_items [] if agent_id: private_items self.storage.search( team_idteam_id, entity_typeentity_type, entity_identity_id, agent_idagent_id, scopeprivate ) return public_items private_items这里的合并策略比较简单按字段级别的 update 合并。实际场景可能需要更精细的策略比如按写入时间合并新写入的字段覆盖旧字段。按 Agent 优先级合并某个 Agent 写入的数据具有更高可信度。多版本并存不覆盖而是保留多个版本检索时按时间和权重排序。TencentDB Agent Memory 这类产品在底层会内置更完善的合并机制但对于自建系统可以先从简单的策略开始再逐步迭代。5.4 给 Agent 的读写 API接下来封装一个简洁的接口方便不同的 Agent 接入。# 文件路径agent-memory-demo/memory/api.py from typing import Dict, List from .manager import MemoryManager from .storage import MemoryStorage class MemoryHub: 团队级 Memory Hub 入口。 所有 Agent 通过这个类读写团队记忆。 def __init__(self, storage: MemoryStorage): self.manager MemoryManager(storage) def remember(self, team_id: str, agent_id: str, entity_type: str, entity_id: str, content: Dict, scope: str public, memory_type: str structured, importance: float 0.5): Agent 写入一条记忆 return self.manager.add_memory( team_idteam_id, agent_idagent_id, entity_typeentity_type, entity_identity_id, contentcontent, scopescope, memory_typememory_type, importanceimportance, ) def recall(self, team_id: str, entity_type: str, entity_id: str, agent_id: str) - str: Agent 读取指定实体的记忆并拼接成提示词上下文。 items self.manager.search_memory( team_idteam_id, entity_typeentity_type, entity_identity_id, agent_idagent_id, ) if not items: return lines [] for item in items: lines.append(f[{item.agent_id} 写入] {item.content}) return \n.join(lines)remember方法负责写入recall方法负责读取并生成一段可以直接注入 Prompt 的文本。这里的recall返回的是纯文本实际项目中可以改为返回结构化 JSON由 Agent 自行决定如何使用。5.5 模拟多 Agent 协作下面用一个简单脚本模拟三个 Agent售前 Agent、客服 Agent、售后 Agent它们共享同一个团队记忆池。# 文件路径agent-memory-demo/test_agent.py from memory.storage import MemoryStorage from memory.models import MemoryItem from memory.api import MemoryHub from typing import List, Optional class InMemoryStorage(MemoryStorage): 基于内存的存储实现仅供演示 def __init__(self): self._items [] def save(self, item: MemoryItem) - None: self._items.append(item) def get_by_id(self, memory_id: str) - Optional[MemoryItem]: for item in self._items: if item.memory_id memory_id: return item return None def search(self, team_id: str, entity_type: Optional[str] None, entity_id: Optional[str] None, agent_id: Optional[str] None, scope: Optional[str] None) - List[MemoryItem]: results [] for item in self._items: if item.team_id ! team_id: continue if entity_type and item.entity_type ! entity_type: continue if entity_id and item.entity_id ! entity_id: continue if agent_id and item.agent_id ! agent_id: continue if scope and item.scope ! scope: continue results.append(item) return results def delete(self, memory_id: str) - None: self._items [item for item in self._items if item.memory_id ! memory_id] def update_content(self, memory_id: str, new_content: str) - None: for item in self._items: if item.memory_id memory_id: item.content new_content def main(): storage InMemoryStorage() hub MemoryHub(storage) # 售前 Agent 记录了用户的初步诉求 hub.remember( team_idteam_demo, agent_idagent_pre_sale, entity_typeorder, entity_idorder_001, content{ user_name: 张三, product: 机械键盘, issue: 空格键回弹异常, intention: 可能申请售后, }, scopepublic, importance0.8, ) # 客服 Agent 在和用户沟通后补充了用户的情绪和沟通偏好 hub.remember( team_idteam_demo, agent_idagent_cs, entity_typeorder, entity_idorder_001, content{ user_mood: 略有不满, preferred_contact_time: 工作日晚间, }, scopepublic, importance0.6, ) # 售后 Agent 开始处理订单先召回所有记忆 context hub.recall( team_idteam_demo, entity_typeorder, entity_idorder_001, agent_idagent_after_sale, ) print( 售后 Agent 召回的记忆 ) print(context) if __name__ __main__: main()运行结果大致如下 售后 Agent 召回的记忆 [agent_pre_sale 写入] {user_name: 张三, product: 机械键盘, issue: 空格键回弹异常, intention: 可能申请售后} [agent_cs 写入] {user_mood: 略有不满, preferred_contact_time: 工作日晚间}可以看到售后 Agent 在开始处理订单时已经能够直接获取售前和客服阶段沉淀的记忆不需要用户重新描述。这就是团队级 Memory Hub 的核心价值让信息在 Agent 团队中流动起来。6. 语义记忆向量检索的引入结构化记忆适合存储明确的字段但用户很多时候说的话是原生的自然语言没有固定的字段结构。比如用户说“键盘用了不到两个月就出问题了感觉品控不太行”如果只靠结构化字段很难把“品控不太行”这种主观感受存进去。这时就需要语义记忆。做法是把用户的原话切片生成 embedding 向量。把向量和原文一起存入向量数据库。检索时把 Agent 的查询语句也生成 embedding做相似度召回。下面是一个使用向量检索的示意代码这里使用一个简化的向量存储实现演示流程# 文件路径agent-memory-demo/memory/vector_storage.py from typing import List, Tuple class SimpleVectorStorage: 简化版向量存储仅演示语义检索流程。 实际生产建议使用腾讯云向量数据库等产品。 def __init__(self, embedding_func): self._items [] self._embedding_func embedding_func def add(self, text: str, metadata: dict, vector: List[float]): self._items.append({ text: text, metadata: metadata, vector: vector, }) def search(self, query: str, top_k: int 3) - List[Tuple[str, dict, float]]: query_vector self._embedding_func(query) scored [] for item in self._items: score self._cosine_similarity(query_vector, item[vector]) scored.append((item[text], item[metadata], score)) scored.sort(keylambda x: x[2], reverseTrue) return scored[:top_k] def _cosine_similarity(self, vec_a: List[float], vec_b: List[float]) - float: dot sum(a * b for a, b in zip(vec_a, vec_b)) norm_a sum(a * a for a in vec_a) ** 0.5 norm_b sum(b * b for b in vec_b) ** 0.5 if norm_a 0 or norm_b 0: return 0.0 return dot / (norm_a * norm_b)在真实环境中embedding 函数可以由腾讯云向量数据库或第三方嵌入模型提供这里不再展开。引入语义记忆后Agent 可以通过一句话描述来检索历史记忆例如“用户对产品质量有什么看法”而不是必须指定order_001这样的实体 ID。需要说明的是这个示例中的SimpleVectorStorage只用于演示向量检索的基本流程生产环境建议使用腾讯云向量数据库这类具备完整索引、持久化和高可用能力的服务。7. 常见问题与排查思路在设计和实现团队级记忆服务时有几个问题是很容易踩坑的。下面整理成表格方便排查时快速定位。问题现象常见原因解决思路Agent 检索不到其他 Agent 写入的记忆scope 设置了 private或 team_id 不一致检查写入和读取时的 team_id、scope 是否匹配记忆更新后旧数据仍然影响检索更新策略是“多版本并存”没有标记最新版本在检索时按 updated_at 排序并增加 is_latest 标记向量检索结果不相关embedding 模型和查询语句领域不匹配更换或微调 embedding 模型或增加关键词过滤同一实体存在大量重复记忆合并策略过于简单多次写入都新增记录对 entity_type entity_id memory_type 做唯一约束记忆数据增长太快没有设置 TTL 或清理策略为短期记忆设置 expire_at定期清理低重要性记忆高并发写入时数据冲突缺少事务或锁机制使用数据库行锁或乐观锁版本号控制并发更新权限越界Agent 读到不该读的记忆检索接口没有校验 agent_id 和 scope在存储层直接增加 team_id scope 校验避免业务层遗漏下面挑两个典型问题展开说明。7.1 记忆冲突问题当多个 Agent 同时更新同一个实体的记忆时最后的更新者覆盖之前的更新这看起来合理但存在一个问题Agent A 更新的字段和 Agent B 更新的字段可能完全不同。比如售前 Agent 写了product字段售后 Agent 写了delivery_status字段如果直接用“整条记忆覆盖”的策略售后 Agent 的写入会把售前 Agent 的product字段覆盖掉。这是我在实际项目中遇到的比较隐蔽的问题。解决方案是字段级合并而不是记录级覆盖。在写入时先把已有记录读取出来把新内容按字段合并进去再写回。如果更新频率很高可以结合数据库的行锁或乐观锁来避免并发丢失更新。7.2 记忆污染问题记忆污染是一个在团队级记忆里很常见的现象。一个 Agent 写入了错误信息之后所有 Agent 在检索时都会看到这条错误信息并且可能基于错误信息继续往下做判断。减少记忆污染的常用手段包括为每条记忆记录来源 Agent 和置信度检索时按置信度加权排序。设置记忆审核机制对高重要性记忆由人工或其他 Agent 确认后再写入共享池。提供记忆删除和纠错接口当 Agent 发现某条记忆不合理时可以主动标记或删除。在 TencentDB Agent Memory 这类产品设计中记忆的来源、版本和生命周期管理都会被显式支持这也是它相比自建临时表方案更完整的价值。8. 最佳实践与工程建议8.1 记忆粒度要适中记忆粒度太粗比如把整段对话原文存下来检索时会有大量噪音而且 Token 消耗会很大。记忆粒度太细比如把“用户今天早上九点三十分登录系统”也存为一条重要记忆存储量会爆炸且真正有用的信息被淹没。比较好的做法是区分核心记忆用户身份、偏好、关键业务状态和过程记忆某次会话中的临时上下文。核心记忆要结构化、长期保存过程记忆可以放进短期缓存设置较短 TTL。8.2 严格设计权限模型团队级记忆的权限模型至少要区分两个维度团队维度不同团队之间的记忆完全隔离。Agent 维度同一个团队内有的记忆是公开共享的有的记忆只对特定 Agent 可见。在实现上权限过滤要在存储层做不要依赖业务代码层层传递参数。每个查询必须显式携带team_id避免一个 Agent 通过拼接口查到了别的团队的数据。8.3 为记忆增加审计能力多人多 Agent 协作场景下记忆的写入来源很重要。我建议至少记录以下审计字段写入 Agent ID写入时间关联的会话 ID用于回溯原始对话置信度或来源类型人工确认、Agent 抽取、规则生成等这样当记忆出错时可以快速定位是哪条链路的哪次提取导致了错误。8.4 使用合适的存储引擎不要把所有的记忆都堆在一张表里。建议按记忆类型拆分存储结构化记忆使用 TencentDB for MySQL 或 TDSQL建立team_id entity_type entity_id联合索引。语义记忆使用向量数据库按团队隔离 collection 或 partition。短期状态使用 Redis设置合理的 TTL防止无限膨胀。如果使用 TencentDB Agent Memory 这类托管服务存储引擎的选择和分片可能已经被上层封装你只需要关注数据模型和调用方式如果是自建早期就做好存储拆分能省很多重构成本。8.5 定期治理记忆质量记忆系统上线后不能只写不治理。建议定期执行以下操作清理过期和低重要性记忆。合并重复实体下的冗余记忆。标记内容冲突的记忆触发人工复核。统计各 Agent 写入记忆的使用率和召回率调整提取策略。记忆质量和代码质量一样需要持续投入维护否则运行时间越长系统记忆噪音越多Agent 的判断质量反而会下降。9. 总结与下一步团队级 Memory Hub 是多 Agent 应用从“能跑”走向“好用”的关键基础设施。围绕 TencentDB Agent Memory 这一产品方向本文梳理了单 Agent 记忆的局限、团队级记忆要解决的共享与隔离问题并给出了一个可运行的架构示例包括记忆模型、存储抽象、冲突处理、读写 API 和模拟多 Agent 协作的完整代码。核心要点可以归纳为AI Agent 的记忆不等于对话历史需要从原始数据中提取结构化和语义化的记忆实体。团队级 memory hub 要解决的核心问题是多 Agent 之间的记忆共享、一致性和权限控制。存储选型建议分层结构化记忆用关系库语义记忆用向量库短期状态用缓存。记忆冲突处理要实现字段级合并避免互相覆盖。权限过滤要在存储层完成严格按 team_id 隔离。下一步如果你正在实践多 Agent 应用可以先从一个小场景入手选定一个业务实体比如订单或用户让两个 Agent 分别写读记忆跑通整个链路后再逐步增加语义检索、TTL 清理和权限模型。另外也建议多留意 TencentDB Agent Memory 这类产品在记忆合并、审计和向量检索方面的设计思路它们的工程实现比自建方案完整得多可以直接借鉴。本文的架构和代码适用于理解原理和快速原型验证如果你的项目已经进入生产阶段建议认真评估托管型 Memory Hub 和自建方案的边界结合团队规模、数据量和维护成本做选型。多 Agent 协作的体验优化空间还很大记忆层值得投入精力做好。 
长河君 · 2026/8/28 15:09:19 · 阅读 1.2k 多Agent共享记忆架构设计：团队级Memory Hub实践
最近在帮团队搭建多 Agent 协作平台时遇到了一个非常现实的问题每个 Agent 都能记住和用户的对话但 Agent 与 Agent 之间、不同业务会话之间记忆是相互孤立的。结果就是客服 Agent 刚跟用户确认了退货诉求转交给售后 Agent 后售后 Agent 完全不知道之前聊了什么只能让用户重新描述一遍。这种体验放在真实业务里几乎等于不可用。于是我开始研究 AI Agents 的“记忆层”设计也关注到了 TencentDB Agent Memory 这类面向团队级记忆共享的解决方案。本文就围绕“团队级 memory hub”这个概念展开讲清楚 AI Agent 记忆的分层逻辑、为什么单 Agent 记忆不够用、以及如何基于 TencentDB 这类云数据库底座设计一个可落地的多 Agent 共享记忆服务。内容会包含完整的架构思路、数据模型设计、核心代码示例和常见坑点适合正在做 Agent 应用落地、或者准备为多 Agent 系统设计记忆层的开发者。1. 背景AI Agent 的“记忆”到底缺什么1.1 单 Agent 记忆的技术现状在不少 AI 应用里“记忆”已经不是一个陌生词汇了。很多对话系统会保存用户的会话历史再把历史消息作为上下文拼接到大模型的请求里。这种做法可以追溯到早期的检索增强生成RAG架构——先把历史对话切片、向量化然后存到向量数据库里下次用户提问时先做相似度检索再把命中的历史片段交给模型参考。在单个 Agent 的层面这套方案是行得通的。一个 Agent 维护自己的 conversation history需要时自己查自己的记忆库逻辑上比较直接。但当我开始做多 Agent 协作时单 Agent 记忆的问题立刻暴露出来记忆隔离Agent A 积累的用户偏好、业务上下文Agent B 完全不可见。会话孤岛用户在不同会话里和不同 Agent 沟通历史无法串联。重复劳动每个 Agent 都要重新向用户确认已经提供过的信息。一致性差多个 Agent 对同一实体的状态理解不一致比如一个认为订单已退款另一个认为还在处理中。这些问题不是简单的“把历史消息存到同一个数据库”就能解决的因为还涉及记忆的归属、时效、共享范围、权限控制、更新策略等一系列问题。1.2 从对话历史到记忆层“记忆”和“对话历史”是两件事。对话历史是原始数据而记忆层是从原始数据中提炼出来的、可以被不同 Agent 复用的结构化知识。举个例子对话历史记录的是用户在某天某时说“我上次买的机械键盘空格键回弹有问题”。记忆层提炼的是用户有一个设备类型为机械键盘状态为“空格键回弹异常”关联订单号 XXX处理状态为“待售后跟进”。团队级 memory hub 的核心职责就是把散落在各个 Agent 手里的对话历史、状态信息、用户偏好汇总到一个统一的地方再按需提供给不同的 Agent 使用。TencentDB Agent Memory 的定位正是这种“team-level memory hub”它面向的是一个 Agent 团队而不是单个 Agent。1.3 为什么团队级记忆比个人记忆难做我一开始以为团队级记忆就是把个人记忆的数据表加一个 team_id 字段后来发现远远不止。个人记忆只需要服务一个 Agent它的读写模式相对简单而团队级记忆要面对的问题包括谁来写多个 Agent 都可能写入同一实体如订单、客户的记忆需要合并策略。谁来读不同 Agent 关注的信息维度不同客服关注情绪和诉求售后关注故障现象和售后进度运营关注转化和复购记忆服务要能按需提供不同视图。什么时候过期有些记忆是长期有效的用户收货地址、会员等级有些是短期有效的用户当前在活动页的浏览状态。可信度如何评判Agent 写入的记忆并不总是可靠的需要记录来源和置信度。如何避免干扰如果团队里有多个 Agent一个 Agent 的记忆写入不能对另一个 Agent 的检索结果造成持续污染。这些难点决定了团队级 memory hub 不能只是一个存储服务它需要包含写入、检索、更新、权限、生命周期管理等完整链路。2. TencentDB Agent Memory 是什么2.1 产品定位根据公开资料和相关设计思路TencentDB Agent Memory 是腾讯云数据库产品体系下面向 AI Agent 场景设计的一套记忆管理能力。它并不只是提供一个 MySQL 或 Redis 实例而是致力于成为整个 Agent 团队的共享记忆中枢Memory Hub让多个 Agent 可以围绕同一份业务上下文协作。从底层来看它构建在 TencentDB 的多种数据库引擎之上结合向量检索、KV 存储、结构化存储等能力为 Agent 的内存式短期记忆和外置长期记忆提供统一的读写接口。即便不依赖具体 SDK从架构思想来看它要解决的核心问题和业界讨论的“Agent Memory”方向是一致的让 AI Agents 拥有跨会话、跨 Agent、跨团队的记忆能力。2.2 Memory Hub 的抽象能力围绕“team-level memory hub”这一目标TencentDB Agent Memory 的产品设计大致包含以下几类核心能力记忆写入Agent 在运行过程中将用户偏好、业务关键信息、任务状态等写入记忆层。记忆检索其他 Agent 在需要时通过语义或结构化条件查询相关记忆。记忆更新与合并同一实体的记忆被多个 Agent 更新后系统需要解决冲突或保留最新版本。记忆过期与清理通过 TTL生存时间或业务规则自动清理过期记忆。权限与隔离不同团队、不同 Agent 之间的记忆数据相互隔离但同一团队内的 Agent 可以共享。来源可追溯每条记忆能追溯到是哪个 Agent、基于哪次会话写入的。这些能力组合起来就可以支撑起一个多 Agent 协作了。2.3 它和普通数据库的区别如果只是把对话记录存到 MySQL 里然后每次全量拼到 Prompt 里那不算使用 Memory Hub。区别在于普通数据库存储的是原始记录Memory Hub 存储的是经过结构化处理的记忆实体。普通数据库的查询条件是精确匹配Memory Hub 的检索可以是语义化的相似度匹配。普通数据库没有“记忆生命周期”的概念Memory Hub 明确管理记忆的创建时间、更新时间、过期时间、重要程度。普通数据库需要业务方自己处理多 Agent 写入冲突Memory Hub 会提供合并和版本控制机制。换句话说Memory Hub 是面向 AI Agent 应用场景的“记忆中间层”数据库是它底层的存储引擎。3. 团队级记忆系统的架构设计在了解了“是什么”之后我们来看“怎么设计”。无论最终选型是 TencentDB Agent Memory还是基于腾讯云数据库自建一套记忆服务架构设计上都有很多相通的地方。3.1 整体架构分层我习惯把团队级记忆系统拆成三层接入层面向各 Agent 提供读写记忆的 SDK 或 HTTP API。记忆管理层实现记忆的提取、结构化、更新策略、冲突处理、过期清理。存储层使用多种数据库引擎存储不同特性的记忆数据。接入层做的事情比较简单就是两件事往记忆库写东西、从记忆库查东西。真正复杂的是记忆管理层。Agent A ──┐ Agent B ──┼── Memory Hub API ── 记忆管理器 ── 存储层 Agent C ──┘ │ ├── 结构化记忆用户画像、订单状态 ├── 向量记忆语义检索 └── 短期 KV 记忆临时上下文在记忆管理层内部核心模块包括Extractor从 Agent 的对话原始文本中抽取结构化记忆。这个模块通常由大模型驱动例如判断“用户提到购买过机械键盘”是否可以转化为一条用户设备维度的记忆。Merger当新旧记忆冲突时决定保留哪个版本。常见的策略包括按时间覆盖、按来源优先级覆盖、多版本并存。Retriever根据 Agent 当前的查询需求从结构化数据和向量数据中召回最相关的记忆。Garbage Collector清理过期或无用的记忆。3.2 记忆的分类与存储选型不同特征的记忆适合用不同的存储引擎这部分我在实际项目里吃过不少亏。一开始我只用一个 MySQL 表存所有记忆结果向量检索做不了时效性高的缓存也没有独立出来导致两个问题一是 Agent 查一个“用户是否提到过退货”的语义问题时效果很差二是高频访问的短期记忆都在查库性能不够理想。后来我把记忆拆成三类分别使用不同存储记忆类型典型内容存储选型检索方式结构化记忆用户ID、订单状态、地址、偏好标签关系型数据库如 TencentDB for MySQL / TDSQL精确条件查询语义记忆用户描述过的问题描述、非结构化诉求向量数据库embedding 余弦相似度检索短期状态当前会话临时状态、最近一次操作记录Redis 或内存 KVKey 查询 TTL这种分层设计在 TencentDB Agent Memory 的架构思路里也能看到影子。它把不同存储引擎组合成一个对上层透明的 Memory HubAgent 不需要关心某条记忆到底存在哪个引擎里只需要按语义和条件调用即可。3.3 团队协作的核心机制团队级记忆和单 Agent 记忆最大的不同在于“共享”和“隔离”之间的平衡。一个团队里可能有十几个 Agent 并行工作它们共享同一个记忆池但并不是所有记忆对所有 Agent 都可见。在设计时我采用了一个较通用的做法为每条记忆存储多个维度的归属信息。team_id: 团队ID决定记忆归属哪个团队 agent_id: 写入该记忆的Agent scope: 可见范围例如 public(团队内可见)private(仅写入者可见) entity_type: 实体类型例如 order, user, ticket entity_id: 实体ID例如 order_12345这样在检索的时候就可以灵活控制团队内所有 Agent 都可以读 scopepublic 的记忆。只有指定的 Agent 才能读 scopeprivate 的记忆。按 entity_type entity_id 可以把同一实体的多个维度记忆聚合在一起。这个模型看起来简单但能解决多 Agent 场景里大部分共享和权限的问题。4. 环境准备与版本说明在进入代码之前先说明环境。因为不同版本的数据库和不同 Agent 框架差异较大下面的示例重点是演示设计思路和核心逻辑不依赖某个特定版本才能运行。4.1 基础环境操作系统Linux / macOS / Windows 均可示例使用 Linux 风格命令。开发语言Python 3.9本文示例使用 Python 编写记忆管理逻辑。数据库腾讯云 TencentDB for MySQL 8.0 或本地 MySQL 8.0 均可如果使用 TencentDB Agent Memory 的托管能力可以跳过部分存储细节。向量检索可以使用腾讯云向量数据库或本地使用 Chroma 等轻量方案演示。缓存Redis 6.x用于短期状态记忆。版本需要根据你的项目实际情况调整本文示例以常见环境为例重点演示配置思路。4.2 示例项目结构为了便于理解我把示例代码组织为一个简单的 Python 项目agent-memory-demo/ ├── memory/ │ ├── __init__.py │ ├── models.py # 记忆模型定义 │ ├── storage.py # 存储层封装 │ ├── extractor.py # 记忆提取(模拟) │ ├── manager.py # 记忆管理核心逻辑 │ └── api.py # 提供给Agent的读写接口 ├── test_agent.py # 模拟多Agent读写 └── requirements.txt5. 核心代码与实现思路这一节我会给出一个最小可运行的多 Agent 共享记忆实现思路。这里的代码不是官方 SDK 的调用代码而是一个架构演示帮助理解 Memory Hub 的核心机制。5.1 定义记忆模型首先定义一条记忆的数据结构。这里采用一个相对通用的模型包含归属、内容、生命周期和元信息。# 文件路径agent-memory-demo/memory/models.py from dataclasses import dataclass, field from datetime import datetime from typing import Optional dataclass class MemoryItem: memory_id: str team_id: str agent_id: str scope: str # public 或 private entity_type: str # 例如 user, order, ticket entity_id: str # 例如 user_001 content: str # 记忆内容可以是结构化JSON字符串 memory_type: str # structured, semantic, short_term importance: float # 重要程度0~1 created_at: datetime field(default_factorydatetime.now) updated_at: datetime field(default_factorydatetime.now) expire_at: Optional[datetime] None各字段说明memory_id记忆的唯一标识建议使用 UUID。team_id团队 ID实现团队级隔离。agent_id写入该记忆的 Agent ID。scopepublic 表示所有团队成员可见private 表示只有写入者可见。entity_type 和 entity_id用于把同一个业务实体的记忆聚合起来例如同一个订单的所有记忆。content记忆内容。对于结构化记忆可以存 JSON 字符串对于语义记忆可以存原文本。importance重要程度用于检索排序时加权。expire_at过期时间实现自动清理。5.2 存储层封装存储层我们做一个抽象接口方便替换成 TencentDB 或其他数据库。# 文件路径agent-memory-demo/memory/storage.py from typing import List, Optional from .models import MemoryItem class MemoryStorage: 记忆存储抽象接口 def save(self, item: MemoryItem) - None: raise NotImplementedError def get_by_id(self, memory_id: str) - Optional[MemoryItem]: raise NotImplementedError def search(self, team_id: str, entity_type: Optional[str] None, entity_id: Optional[str] None, agent_id: Optional[str] None, scope: Optional[str] None) - List[MemoryItem]: raise NotImplementedError def delete(self, memory_id: str) - None: raise NotImplementedError def update_content(self, memory_id: str, new_content: str) - None: raise NotImplementedError实际部署时如果使用 MySQLsearch方法对应的 SQL 大致如下SELECT * FROM agent_memory WHERE team_id %s AND (%s IS NULL OR entity_type %s) AND (%s IS NULL OR entity_id %s) AND (%s IS NULL OR agent_id %s) AND (%s IS NULL OR scope %s) AND (expire_at IS NULL OR expire_at NOW()) ORDER BY importance DESC, updated_at DESC在真实项目中我会把存储层替换成 TencentDB for MySQL 的客户端连接池并且为team_id entity_type entity_id建立联合索引确保高频检索不会全表扫描。5.3 记忆冲突处理团队级记忆最核心的难点是“多个 Agent 写入同一实体时如何合并”。下面给一个简单的合并策略实现。# 文件路径agent-memory-demo/memory/manager.py import json import uuid from typing import Dict, List, Optional from .models import MemoryItem from .storage import MemoryStorage class MemoryManager: 记忆管理核心逻辑 def __init__(self, storage: MemoryStorage): self.storage storage def add_memory(self, team_id: str, agent_id: str, entity_type: str, entity_id: str, content: Dict, scope: str public, memory_type: str structured, importance: float 0.5) - MemoryItem: 新增一条记忆。 如果同一实体下已经存在同类型的记忆则尝试合并。 existing_items self.storage.search( team_idteam_id, entity_typeentity_type, entity_identity_id, agent_idagent_id, scopescope ) for item in existing_items: if item.memory_type memory_type: # 模拟合并新的字段覆盖旧的字段 old_content json.loads(item.content) new_content json.loads(json.dumps(content)) old_content.update(new_content) merged_content json.dumps(old_content, ensure_asciiFalse) self.storage.update_content(item.memory_id, merged_content) return item item MemoryItem( memory_idstr(uuid.uuid4()), team_idteam_id, agent_idagent_id, scopescope, entity_typeentity_type, entity_identity_id, contentjson.dumps(content, ensure_asciiFalse), memory_typememory_type, importanceimportance, ) self.storage.save(item) return item def search_memory(self, team_id: str, entity_type: str, entity_id: str, agent_id: Optional[str] None) - List[MemoryItem]: 检索某个实体的记忆。 优先返回 public 记忆再返回当前 Agent 的 private 记忆。 public_items self.storage.search( team_idteam_id, entity_typeentity_type, entity_identity_id, scopepublic ) private_items [] if agent_id: private_items self.storage.search( team_idteam_id, entity_typeentity_type, entity_identity_id, agent_idagent_id, scopeprivate ) return public_items private_items这里的合并策略比较简单按字段级别的 update 合并。实际场景可能需要更精细的策略比如按写入时间合并新写入的字段覆盖旧字段。按 Agent 优先级合并某个 Agent 写入的数据具有更高可信度。多版本并存不覆盖而是保留多个版本检索时按时间和权重排序。TencentDB Agent Memory 这类产品在底层会内置更完善的合并机制但对于自建系统可以先从简单的策略开始再逐步迭代。5.4 给 Agent 的读写 API接下来封装一个简洁的接口方便不同的 Agent 接入。# 文件路径agent-memory-demo/memory/api.py from typing import Dict, List from .manager import MemoryManager from .storage import MemoryStorage class MemoryHub: 团队级 Memory Hub 入口。 所有 Agent 通过这个类读写团队记忆。 def __init__(self, storage: MemoryStorage): self.manager MemoryManager(storage) def remember(self, team_id: str, agent_id: str, entity_type: str, entity_id: str, content: Dict, scope: str public, memory_type: str structured, importance: float 0.5): Agent 写入一条记忆 return self.manager.add_memory( team_idteam_id, agent_idagent_id, entity_typeentity_type, entity_identity_id, contentcontent, scopescope, memory_typememory_type, importanceimportance, ) def recall(self, team_id: str, entity_type: str, entity_id: str, agent_id: str) - str: Agent 读取指定实体的记忆并拼接成提示词上下文。 items self.manager.search_memory( team_idteam_id, entity_typeentity_type, entity_identity_id, agent_idagent_id, ) if not items: return lines [] for item in items: lines.append(f[{item.agent_id} 写入] {item.content}) return \n.join(lines)remember方法负责写入recall方法负责读取并生成一段可以直接注入 Prompt 的文本。这里的recall返回的是纯文本实际项目中可以改为返回结构化 JSON由 Agent 自行决定如何使用。5.5 模拟多 Agent 协作下面用一个简单脚本模拟三个 Agent售前 Agent、客服 Agent、售后 Agent它们共享同一个团队记忆池。# 文件路径agent-memory-demo/test_agent.py from memory.storage import MemoryStorage from memory.models import MemoryItem from memory.api import MemoryHub from typing import List, Optional class InMemoryStorage(MemoryStorage): 基于内存的存储实现仅供演示 def __init__(self): self._items [] def save(self, item: MemoryItem) - None: self._items.append(item) def get_by_id(self, memory_id: str) - Optional[MemoryItem]: for item in self._items: if item.memory_id memory_id: return item return None def search(self, team_id: str, entity_type: Optional[str] None, entity_id: Optional[str] None, agent_id: Optional[str] None, scope: Optional[str] None) - List[MemoryItem]: results [] for item in self._items: if item.team_id ! team_id: continue if entity_type and item.entity_type ! entity_type: continue if entity_id and item.entity_id ! entity_id: continue if agent_id and item.agent_id ! agent_id: continue if scope and item.scope ! scope: continue results.append(item) return results def delete(self, memory_id: str) - None: self._items [item for item in self._items if item.memory_id ! memory_id] def update_content(self, memory_id: str, new_content: str) - None: for item in self._items: if item.memory_id memory_id: item.content new_content def main(): storage InMemoryStorage() hub MemoryHub(storage) # 售前 Agent 记录了用户的初步诉求 hub.remember( team_idteam_demo, agent_idagent_pre_sale, entity_typeorder, entity_idorder_001, content{ user_name: 张三, product: 机械键盘, issue: 空格键回弹异常, intention: 可能申请售后, }, scopepublic, importance0.8, ) # 客服 Agent 在和用户沟通后补充了用户的情绪和沟通偏好 hub.remember( team_idteam_demo, agent_idagent_cs, entity_typeorder, entity_idorder_001, content{ user_mood: 略有不满, preferred_contact_time: 工作日晚间, }, scopepublic, importance0.6, ) # 售后 Agent 开始处理订单先召回所有记忆 context hub.recall( team_idteam_demo, entity_typeorder, entity_idorder_001, agent_idagent_after_sale, ) print( 售后 Agent 召回的记忆 ) print(context) if __name__ __main__: main()运行结果大致如下 售后 Agent 召回的记忆 [agent_pre_sale 写入] {user_name: 张三, product: 机械键盘, issue: 空格键回弹异常, intention: 可能申请售后} [agent_cs 写入] {user_mood: 略有不满, preferred_contact_time: 工作日晚间}可以看到售后 Agent 在开始处理订单时已经能够直接获取售前和客服阶段沉淀的记忆不需要用户重新描述。这就是团队级 Memory Hub 的核心价值让信息在 Agent 团队中流动起来。6. 语义记忆向量检索的引入结构化记忆适合存储明确的字段但用户很多时候说的话是原生的自然语言没有固定的字段结构。比如用户说“键盘用了不到两个月就出问题了感觉品控不太行”如果只靠结构化字段很难把“品控不太行”这种主观感受存进去。这时就需要语义记忆。做法是把用户的原话切片生成 embedding 向量。把向量和原文一起存入向量数据库。检索时把 Agent 的查询语句也生成 embedding做相似度召回。下面是一个使用向量检索的示意代码这里使用一个简化的向量存储实现演示流程# 文件路径agent-memory-demo/memory/vector_storage.py from typing import List, Tuple class SimpleVectorStorage: 简化版向量存储仅演示语义检索流程。 实际生产建议使用腾讯云向量数据库等产品。 def __init__(self, embedding_func): self._items [] self._embedding_func embedding_func def add(self, text: str, metadata: dict, vector: List[float]): self._items.append({ text: text, metadata: metadata, vector: vector, }) def search(self, query: str, top_k: int 3) - List[Tuple[str, dict, float]]: query_vector self._embedding_func(query) scored [] for item in self._items: score self._cosine_similarity(query_vector, item[vector]) scored.append((item[text], item[metadata], score)) scored.sort(keylambda x: x[2], reverseTrue) return scored[:top_k] def _cosine_similarity(self, vec_a: List[float], vec_b: List[float]) - float: dot sum(a * b for a, b in zip(vec_a, vec_b)) norm_a sum(a * a for a in vec_a) ** 0.5 norm_b sum(b * b for b in vec_b) ** 0.5 if norm_a 0 or norm_b 0: return 0.0 return dot / (norm_a * norm_b)在真实环境中embedding 函数可以由腾讯云向量数据库或第三方嵌入模型提供这里不再展开。引入语义记忆后Agent 可以通过一句话描述来检索历史记忆例如“用户对产品质量有什么看法”而不是必须指定order_001这样的实体 ID。需要说明的是这个示例中的SimpleVectorStorage只用于演示向量检索的基本流程生产环境建议使用腾讯云向量数据库这类具备完整索引、持久化和高可用能力的服务。7. 常见问题与排查思路在设计和实现团队级记忆服务时有几个问题是很容易踩坑的。下面整理成表格方便排查时快速定位。问题现象常见原因解决思路Agent 检索不到其他 Agent 写入的记忆scope 设置了 private或 team_id 不一致检查写入和读取时的 team_id、scope 是否匹配记忆更新后旧数据仍然影响检索更新策略是“多版本并存”没有标记最新版本在检索时按 updated_at 排序并增加 is_latest 标记向量检索结果不相关embedding 模型和查询语句领域不匹配更换或微调 embedding 模型或增加关键词过滤同一实体存在大量重复记忆合并策略过于简单多次写入都新增记录对 entity_type entity_id memory_type 做唯一约束记忆数据增长太快没有设置 TTL 或清理策略为短期记忆设置 expire_at定期清理低重要性记忆高并发写入时数据冲突缺少事务或锁机制使用数据库行锁或乐观锁版本号控制并发更新权限越界Agent 读到不该读的记忆检索接口没有校验 agent_id 和 scope在存储层直接增加 team_id scope 校验避免业务层遗漏下面挑两个典型问题展开说明。7.1 记忆冲突问题当多个 Agent 同时更新同一个实体的记忆时最后的更新者覆盖之前的更新这看起来合理但存在一个问题Agent A 更新的字段和 Agent B 更新的字段可能完全不同。比如售前 Agent 写了product字段售后 Agent 写了delivery_status字段如果直接用“整条记忆覆盖”的策略售后 Agent 的写入会把售前 Agent 的product字段覆盖掉。这是我在实际项目中遇到的比较隐蔽的问题。解决方案是字段级合并而不是记录级覆盖。在写入时先把已有记录读取出来把新内容按字段合并进去再写回。如果更新频率很高可以结合数据库的行锁或乐观锁来避免并发丢失更新。7.2 记忆污染问题记忆污染是一个在团队级记忆里很常见的现象。一个 Agent 写入了错误信息之后所有 Agent 在检索时都会看到这条错误信息并且可能基于错误信息继续往下做判断。减少记忆污染的常用手段包括为每条记忆记录来源 Agent 和置信度检索时按置信度加权排序。设置记忆审核机制对高重要性记忆由人工或其他 Agent 确认后再写入共享池。提供记忆删除和纠错接口当 Agent 发现某条记忆不合理时可以主动标记或删除。在 TencentDB Agent Memory 这类产品设计中记忆的来源、版本和生命周期管理都会被显式支持这也是它相比自建临时表方案更完整的价值。8. 最佳实践与工程建议8.1 记忆粒度要适中记忆粒度太粗比如把整段对话原文存下来检索时会有大量噪音而且 Token 消耗会很大。记忆粒度太细比如把“用户今天早上九点三十分登录系统”也存为一条重要记忆存储量会爆炸且真正有用的信息被淹没。比较好的做法是区分核心记忆用户身份、偏好、关键业务状态和过程记忆某次会话中的临时上下文。核心记忆要结构化、长期保存过程记忆可以放进短期缓存设置较短 TTL。8.2 严格设计权限模型团队级记忆的权限模型至少要区分两个维度团队维度不同团队之间的记忆完全隔离。Agent 维度同一个团队内有的记忆是公开共享的有的记忆只对特定 Agent 可见。在实现上权限过滤要在存储层做不要依赖业务代码层层传递参数。每个查询必须显式携带team_id避免一个 Agent 通过拼接口查到了别的团队的数据。8.3 为记忆增加审计能力多人多 Agent 协作场景下记忆的写入来源很重要。我建议至少记录以下审计字段写入 Agent ID写入时间关联的会话 ID用于回溯原始对话置信度或来源类型人工确认、Agent 抽取、规则生成等这样当记忆出错时可以快速定位是哪条链路的哪次提取导致了错误。8.4 使用合适的存储引擎不要把所有的记忆都堆在一张表里。建议按记忆类型拆分存储结构化记忆使用 TencentDB for MySQL 或 TDSQL建立team_id entity_type entity_id联合索引。语义记忆使用向量数据库按团队隔离 collection 或 partition。短期状态使用 Redis设置合理的 TTL防止无限膨胀。如果使用 TencentDB Agent Memory 这类托管服务存储引擎的选择和分片可能已经被上层封装你只需要关注数据模型和调用方式如果是自建早期就做好存储拆分能省很多重构成本。8.5 定期治理记忆质量记忆系统上线后不能只写不治理。建议定期执行以下操作清理过期和低重要性记忆。合并重复实体下的冗余记忆。标记内容冲突的记忆触发人工复核。统计各 Agent 写入记忆的使用率和召回率调整提取策略。记忆质量和代码质量一样需要持续投入维护否则运行时间越长系统记忆噪音越多Agent 的判断质量反而会下降。9. 总结与下一步团队级 Memory Hub 是多 Agent 应用从“能跑”走向“好用”的关键基础设施。围绕 TencentDB Agent Memory 这一产品方向本文梳理了单 Agent 记忆的局限、团队级记忆要解决的共享与隔离问题并给出了一个可运行的架构示例包括记忆模型、存储抽象、冲突处理、读写 API 和模拟多 Agent 协作的完整代码。核心要点可以归纳为AI Agent 的记忆不等于对话历史需要从原始数据中提取结构化和语义化的记忆实体。团队级 memory hub 要解决的核心问题是多 Agent 之间的记忆共享、一致性和权限控制。存储选型建议分层结构化记忆用关系库语义记忆用向量库短期状态用缓存。记忆冲突处理要实现字段级合并避免互相覆盖。权限过滤要在存储层完成严格按 team_id 隔离。下一步如果你正在实践多 Agent 应用可以先从一个小场景入手选定一个业务实体比如订单或用户让两个 Agent 分别写读记忆跑通整个链路后再逐步增加语义检索、TTL 清理和权限模型。另外也建议多留意 TencentDB Agent Memory 这类产品在记忆合并、审计和向量检索方面的设计思路它们的工程实现比自建方案完整得多可以直接借鉴。本文的架构和代码适用于理解原理和快速原型验证如果你的项目已经进入生产阶段建议认真评估托管型 Memory Hub 和自建方案的边界结合团队规模、数据量和维护成本做选型。多 Agent 协作的体验优化空间还很大记忆层值得投入精力做好。