接口介绍
本接口(
/v3/atomic/query)用于按过滤条件分页查询 L1 原子记忆。功能说明如下:过滤条件:支持按记忆类型(
type)和时间范围(time_start / time_end)过滤,筛选字段均为可选。session_id 仅为 SDK 兼容参数,当前服务器不使用它筛选会话。默认行为:筛选字段均不传时,等价于不加筛选,仅按分页参数返回当前作用域下的原子记忆。
Method 与 URL
POST https://memory.tdai.tencentyun.com/v3/atomic/query
使用示例
curl -i -X POST \\-H 'Content-Type: application/json' \\-H 'Authorization: Bearer *********************************' \\-H "x-tdai-service-id: tdai-mem-xxxxxxxx" \\https://memory.tdai.tencentyun.com/v3/atomic/query \\-d '{"team_id":"team-abc123","agent_id":"agt-xyz789","user_id":"usr-456","type":"episodic","limit":20,"offset":0}'
SDK 调用时,
team_id / user_id / agent_id 在 V3 客户端构造时必填,可通过 with_isolation() 调整,SDK 会自动注入 HTTP 请求;HTTP 是否强制校验取决于服务端严格隔离配置,可通过请求体或对应请求头提供。请求参数
参数 | 是否必选 | 参数含义 | 配置方法及要求 |
team_id | 是 | 团队 ID。 | 数据类型:String。 |
agent_id | 是 | Agent ID(全局唯一)。 | 数据类型:String。 |
user_id | 是 | 用户 ID。 | 数据类型:String。 |
task_id | 否 | Task ID。 | 数据类型:String。 |
type | 否 | 按记忆类型过滤。 | 数据类型:String。 可选值: episodic:情节记忆persona:人设记忆instruction:指令记忆不传则返回全部类型。 |
time_start | 否 | 查询时间范围起点。 | 数据类型:String。 格式:UTC、以 Z 结尾的 ISO 8601(如 2026-07-01T00:00:00.000Z)。推荐统一毫秒 UTC 格式 YYYY-MM-DDTHH:mm:ss.sssZ(如 2026-07-01T00:00:00.000Z),并与存储时间格式一致;按最后更新时间 updated_time 过滤,对统一推荐格式包含边界(不早于该时间)。SQLite/Mongo 使用字符串比较,混用时间精度时不保证同一时刻的边界等价。 |
time_end | 否 | 查询时间范围终点。 | 数据类型:String。 格式:UTC、以 Z 结尾的 ISO 8601(如 2026-07-22T23:59:59.000Z)。推荐统一毫秒 UTC 格式 YYYY-MM-DDTHH:mm:ss.sssZ(如 2026-07-22T23:59:59.000Z),并与存储时间格式一致;按最后更新时间 updated_time 过滤,对统一推荐格式包含边界(不晚于该时间)。SQLite/Mongo 使用字符串比较,混用时间精度时不保证同一时刻的边界等价。 |
limit | 否 | 单次返回的最大条数。 | 数据类型:Integer。 取值范围:[1, 100]。 默认值:20。 |
offset | 否 | 分页偏移量。 | 数据类型:Integer。 最小值为 0。 默认值:0。 |
响应示例
{"code":0,"message":"ok","request_id":"req-7fd3b2dd","data":{"items":[{"id":"atm-aabb","type":"episodic","content":"用户每周三上午 10:00 参加产品评审会","created_at":"2026-07-22T10:00:00Z","updated_at":"2026-07-22T10:00:00Z"},{"id":"atm-ccdd","type":"episodic","content":"用户昨天参加团队周会并整理会议纪要","created_at":"2026-07-21T15:30:00Z","updated_at":"2026-07-21T15:30:00Z"}],"total":15}}
响应参数
参数名(一级) | 参数名(二级) | 参数含义 |
data | items | 查询到的原子记忆列表。 |
| items.id | 原子记忆唯一 ID。 |
| items.type | 记忆类型: episodic 情节记忆、persona 人设记忆、instruction 指令记忆。 |
| items.content | 记忆文本内容。 |
| items.background | 更新/创建背景说明(如有)。 |
| items.created_at | 创建时间,ISO 8601 格式。 |
| items.updated_at | 最后更新时间,ISO 8601 格式。 |
| total | 满足条件的原子记忆总数。 |
request_id | — | 请求唯一标识,用于问题排查。与 data 同级。 |