一、接口介绍
·过滤条件：支持按记忆类型（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 同级。 |