腾讯云数据库 AI 服务查询原子记忆

接口介绍
本接口（/atom/query）用于按条件分页查询原子记忆。在请求体顶层平铺分页参数与筛选参数，即可一次返回命中条件的原子记忆列表与命中总数：
分页控制：通过 limit 指定单页条数、offset 指定起始偏移；不传时按默认值 limit=20、offset=0 返回第一页。
筛选条件：通过 type 限定记忆类型（episodic（事实）/ persona（偏好）/ instruction（指令）），time_start / time_end 按 updated_at 限定时间窗（含端点）。三者均可选，全部缺省时等价于"不加筛选、仅按分页返回"。
说明：
原子记忆仅提供条件分页查询入口，不单独提供按主键取单条详情的接口；如需按 id 定位，可在筛选结果中按 id 过滤消费。每项含 id / type / content / created_at / updated_at 五个字段。
Method 与 URL
POST https://{服务访问地址}/v2/atom/query
使用示例
curl -i -k -X POST \\
  -H 'Content-Type: application/json' \\
  -H 'Authorization: Bearer ******************************' \\
  -H "x-tdai-service-id: mem-8i8t****" \\
  https://memory.tdai.tencentyun.com/v2/atom/query \\
  -d '{
    "type": "persona",
    "limit": 20,
    "offset": 0,
    "time_start": "2026-04-01T00:00:00Z",
    "time_end": "2026-04-30T23:59:59Z"
  }'
说明：
鉴权说明：所有接口都必须在请求头中携带 Authorization: Bearer <API Key> 与 x-tdai-service-id: <Service_ID>，否则将返回鉴权失败。
请求参数
参数名
类型
必填
默认值
描述说明
type
str
否
-
原子记忆类型。用于过滤特定类型的记忆片段。可选值包括：
"episodic"：事实类记忆（如用户说过的话、发生过的事）。
"persona"：偏好类记忆（如用户的习惯、人设、喜好）。
"instruction"：指令类记忆（如用户对 AI 下达的长期行为规范）。
limit
int
否
20
单页返回的条数。若不传或传 None，服务端默认单页返回 20 条记录。
offset
int
否
0
分页起始偏移量。指定从哪一条记录开始读取，常用于配合 limit 实现翻页。
time_start
str
否
-
更新时间筛选起点（包含该时刻）。
筛选依据：基于记忆的最后更新时间（updated_at）。
格式要求：ISO 8601 格式，例如："2026-05-25T10:00:00Z"。
time_end
str
否
-
更新时间筛选终点（包含该时刻）。
筛选依据：基于记忆的最后更新时间（updated_at）。
格式要求：ISO 8601 格式。与 time_start 配合组成闭区间时间窗。
响应示例
{
    "code": 0,
    "message": "ok",
    "request_id": "req-7fd3b2dd",
    "data": {
        "items": [
            {
                "id": "note-3a7b9c1d",
                "type": "persona",
                "content": "用户偏好关西线路，5 月出行，预算 1.5 万元。",
                "created_at": "2026-04-20T10:05:30Z",
                "updated_at": "2026-04-21T08:30:15Z"
            },
            {
                "id": "note-4e8d2f60",
                "type": "persona",
                "content": "用户偏好深度文化体验，避免过于密集的行程。",
                "created_at": "2026-04-20T10:08:12Z",
                "updated_at": "2026-04-20T10:08:12Z"
            }
        ],
        "total": 2
    }
}
字段名
类型
说明
data.items
List
原子记忆条目列表。每条记忆包含以下完整字段：
id (str): 原子记忆的唯一主键 ID（格式如 "atom-xxxx"）。
type (str): 记忆类型（例如 "persona" 代表用户画像/偏好标签）。
content (str): 原子记忆的正文文本内容。
created_at (str): 该条记忆的首次创建时间戳（ISO 8601 格式）。
updated_at (str): 该条记忆的最后修改时间戳（ISO 8601 格式）。
data.total
int
满足筛选条件的原子记忆总条数。
注意：该值为全量数据总数，完全不受当前请求中分页参数（如单页限制条数）的影响。
应用场景：前端可直接利用该数值来计算并渲染传统的分页组件或决定是否触发流式滚动加载（Infinite Scroll）。
﻿

参数名	类型	必填	默认值	描述说明
type	str	否	-	原子记忆类型。用于过滤特定类型的记忆片段。可选值包括： "episodic"：事实类记忆（如用户说过的话、发生过的事）。 "persona"：偏好类记忆（如用户的习惯、人设、喜好）。 "instruction"：指令类记忆（如用户对 AI 下达的长期行为规范）。
limit	int	否	20	单页返回的条数。若不传或传 None，服务端默认单页返回 20 条记录。
offset	int	否	0	分页起始偏移量。指定从哪一条记录开始读取，常用于配合 limit 实现翻页。
time_start	str	否	-	更新时间筛选起点（包含该时刻）。筛选依据：基于记忆的最后更新时间（updated_at）。格式要求：ISO 8601 格式，例如："2026-05-25T10:00:00Z"。
time_end	str	否	-	更新时间筛选终点（包含该时刻）。筛选依据：基于记忆的最后更新时间（updated_at）。格式要求：ISO 8601 格式。与 time_start 配合组成闭区间时间窗。

字段名	类型	说明
data.items	List	原子记忆条目列表。每条记忆包含以下完整字段： id (str): 原子记忆的唯一主键 ID（格式如 "atom-xxxx"）。 type (str): 记忆类型（例如 "persona" 代表用户画像/偏好标签）。 content (str): 原子记忆的正文文本内容。 created_at (str): 该条记忆的首次创建时间戳（ISO 8601 格式）。 updated_at (str): 该条记忆的最后修改时间戳（ISO 8601 格式）。
data.total	int	满足筛选条件的原子记忆总条数。注意：该值为全量数据总数，完全不受当前请求中分页参数（如单页限制条数）的影响。应用场景：前端可直接利用该数值来计算并渲染传统的分页组件或决定是否触发流式滚动加载（Infinite Scroll）。

查询原子记忆

本页目录：

接口介绍

Method 与 URL

使用示例

请求参数

响应示例