帮你快速理解、总结文档立即下载

查询原子记忆

最近更新时间:2026-11-06 10:01:30
我的收藏

接口介绍

本接口(/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 同级。