文档反馈官招募中，报名立赚积分兑换代金券！> HOT
文档中心>腾讯云数据库 AI 服务>Memory 应用指南>开发者参考>Python>原子记忆>query_atomic — 查询原子记忆

query_atomic — 查询原子记忆

最近更新时间：2026-05-26 21:12:00

我的收藏

本页目录：

接口介绍

按条件分页查询原子记忆。传入分页参数与筛选参数，即可一次返回命中条件的原子记忆列表与命中总数：
分页控制：通过 limit 指定单页条数、offset 指定起始偏移；不传时按服务端默认值 limit=20、offset=0 返回第一页。
筛选条件：通过 type 限定记忆类型（episodic / persona / instruction），time_start / time_end 按 updated_at 限定时间窗（含端点）。三者均可选，全部缺省时等价于"不加筛选、仅按分页返回"。
项
值
HTTP 方法与路径
POST /v2/atomic/query
HTTP 文档
函数签名
query_atomic(*, type=None, limit=None, offset=None, time_start=None, time_end=None)
说明：
原子记忆仅提供条件分页查询入口，不单独提供按主键取单条详情的接口；如需按 id 定位，可在筛选结果中按 id 过滤消费。每项含 id / type / content / created_at / updated_at 五个字段。

使用示例

# 全量分页
result = client.query_atomic()

# 仅查 persona 类型
result = client.query_atomic(type="persona", limit=50)

# 按时间窗筛选近 30 天的更新
result = client.query_atomic(
    time_start="2026-04-22T00:00:00+08:00",
    time_end="2026-05-22T23:59:59+08:00",
)

for item in result["data"]["items"]:
    print(f"[{item['type']}] {item['content']}")
说明：
client 实例的构造方式参见 新建客户端；异步调用时将方法前加 await 即可。

请求参数

参数名
类型
必填
默认值
描述说明
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 配合组成闭区间时间窗。

返回信息

返回字典包含命中的原子记忆列表、命中总数与请求追踪 ID：
{
  "data": {
    "items": [
      {
        "id": "atom-aaaa",
        "type": "persona",
        "content": "用户偏好关西线路",
        "created_at": "2026-05-22T14:30:00+08:00",
        "updated_at": "2026-05-22T14:30:00+08:00"
      }
    ],
    "total": 1
  },
  "trace_id": "tr-xxxxxxxx-xxxxxxxx"
}
字段名
类型
说明
data.items
List[Dict]
原子记忆条目列表。每条记忆包含以下完整字段：
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）。
trace_id
str
请求追踪 ID。用于全链路日志排查。该值与 HTTP 响应头中的 x-trace-id 保持一致，方便前后端协同定位查询或筛选过程中的异常。

错误处理

错误码
触发场景
处理建议
400
type 取值非法、limit / offset 越界、时间格式非法。
请校验入参后重试。
500
服务端错误。
记录 trace_id 后重试或上报。

中国站