概述
云数据库 Agent Memory（TencentDB Agent Memory）的 V3 API 是一套面向 Agent 应用的记忆管理接口，覆盖从对话记录到长期画像的完整记忆生命周期。通过 V3 API，您可以：
写入与检索对话：将 Agent 与用户的交互记录写入 Memory，通过条件查询或语义检索获取历史对话。
管理原子记忆：查询、修正或删除从对话中自动抽取的原子事实。
组织场景记忆：以文件系统方式管理归纳后的场景知识。
维护核心记忆：读写长期稳定的用户画像、偏好与领域知识。
版本说明
V3 是当前推荐使用的版本。相比 V2，V3 在原有的用户、Agent、任务维度基础上新增了团队（
team_id）维度，支持团队级记忆的隔离与共享：同一团队下的多个 Agent 与成员可以共享同一份团队记忆（如团队规范、协作上下文与领域知识），从而更好地支撑多 Agent 协作与团队级应用场景。新接入：建议直接使用 V3 API，接口路径统一以
/v3/ 为前缀。存量 V2 应用：建议迁移至 V3，以获得团队记忆等新增能力。V3 兼容原有的用户（
user_id）、Agent（agent_id）、会话（session_id）、任务（task_id）维度，迁移成本低。记忆层级与接口组织
V3 API 按记忆的四层金字塔结构组织，自下而上从原始对话逐步沉淀为核心认知：
层级 | 定位 | 接口分组 | 说明 |
L0 原始对话 | 完整对话记录、工具调用日志 | /v3/conversation/ | 基础层原始数据，支持追加、分页查询、语义检索、批量删除与计数 |
L1 原子记忆 | 从对话中抽取的原子事实，每条带来源链接 | /v3/atomic/ | 支撑精准检索与溯源，支持更新、查询、语义检索、批量删除与计数 |
L2 场景记忆 | 同类原子事实归纳出的场景模式与高频路径 | /v3/scenario/ | 以文件系统方式组织，支持列出、读写、删除与计数 |
L3 核心记忆 | 跨场景的稳定洞察、用户画像与团队规范 | /v3/core/ | 键值对形式的长期记忆，支持读写与计数 |
说明：
通过 L0 接口写入的对话，系统会自动在后台逐层抽取与归纳，逐步沉淀为 L1 原子记忆、L2 场景记忆和 L3 核心记忆。各层查询接口可观测沉淀结果。
记忆组织模型
V3 API 通过一组归属维度实现记忆的隔离与共享。其中
team_id、user_id、agent_id、session_id 构成一条由大到小、逐级从属的作用域链：一个团队下有多个用户，一个用户可使用多个 Agent，一个 Agent 下可开启多个会话。层级越高，作用域越大、覆盖的记忆越多；层级越低，定位越精确。维度 | 参数 | 层级 | 从属关系 |
团队 | team_id | 最高 | 一个团队包含多个用户 |
用户 | user_id | 次高 | 一个用户使用多个 Agent |
Agent | agent_id | 较低 | 一个 Agent 下有多个会话 |
会话 | session_id | 最低 | 每条对话归属一个会话 |
除上述层级链外，
task_id（任务）为可正交叠加的辅助维度，用于在同一作用域内进一步区分不同任务。说明：
各维度均为可选参数，可按需从高到低逐级收窄作用域：仅指定
team_id 时命中整个团队的记忆；叠加 user_id 后收窄到“该团队下的某个用户”；再叠加 agent_id、session_id 则进一步限定到具体 Agent 与具体会话。由此，同一套接口既能做团队级的记忆共享，也能做会话级的精确检索。
