方法介绍
query_atomic 用于按过滤条件分页查询 L1 原子记忆笔记。功能说明如下：过滤条件：支持按记忆类型（
episodic / persona / instruction）和时间范围（time_start / time_end）过滤，筛选参数均为可选。默认行为：筛选参数均不传时，等价于不加筛选，仅按分页参数返回当前作用域下的笔记。
跨 session 查询：如需跨所有 session 聚合查询，请使用
client.with_isolation(session_id=None).query_atomic(...)。注意：调用时传入 session_id=None 不会清除构造时已绑定的值，必须通过 with_isolation 创建新隔离上下文来跨 session 查询。返回内容：每条笔记包含 id、版本号、类型、背景、内容、创建和更新时间。
导入
from tencentdb_agent_memory.v3 import MemoryClient
使用示例
from tencentdb_agent_memory.v3 import MemoryClientwith MemoryClient(endpoint="https://memory.tdai.tencentyun.com",api_key="sk-xxxxxxxxxxxxxxxx",service_id="tdai-mem-xxxxxxxx",team_id="team-abc123",agent_id="agt-xyz789",user_id="usr-456",) as client:result = client.query_atomic(type="persona",limit=20,offset=0,time_start="2026-07-01T00:00:00Z",time_end="2026-07-22T23:59:59Z",)print(f"共 {result['total']} 条笔记")for item in result["items"]:print(f"[{item['type']}] {item['content']}")# 跨 session 查询所有笔记（需通过 with_isolation 创建隔离上下文）cross = client.with_isolation(session_id=None).query_atomic(limit=20)print(f"所有会话共 {cross['total']} 条笔记")for item in cross["items"]:print(f"[session={item.get('session_id','-')}] [{item['type']}] {item['content']}")
请求参数
参数名 | 类型 | 必填 | 描述说明 |
type | str | 否 | 记忆类型： episodic / persona / instruction |
session_id | str | 否 | 覆盖默认 session_id。调用时传 None 不会清除构造值，需跨 session 查询请用 with_isolation(session_id=None) |
limit | int | 否 | 单次返回最大条数，范围 1–100，默认 20 |
offset | int | 否 | 分页偏移量，最小值为 0 |
time_start | str | 否 | 查询起始时间，ISO 8601 格式 |
time_end | str | 否 | 查询截止时间，ISO 8601 格式 |
响应示例
{"items": [{"id": "note-xxxx","version": "v3","type": "persona","background": "源于 2026-07-20 工作时间偏好的多轮讨论","content": "用户偏好在早晨 9:00–11:00 处理重要任务","created_at": "2026-07-20T09:15:00Z","updated_at": "2026-07-22T14:30:00Z","team_id": "team-abc123","agent_id": "agt-xyz789","user_id": "usr-456"}],"total": 15}
Running Environment
Operating System: Ubuntu 24.04.3 LTS / x86_64
Runtime Version: Python 3.11.1
响应参数说明
参数名 | 类型 | 参数含义 |
items | List[Dict] | 笔记列表 |
items[].id | str | 笔记唯一 ID |
items[].version | str | 当前版本号 |
items[].type | str | 记忆类型 |
items[].background | str | 背景信息或来源说明 |
items[].content | str | 记忆内容 |
items[].created_at | str | 创建时间，ISO 8601 格式 |
items[].updated_at | str | 更新时间，ISO 8601 格式 |
items[].team_id | str | 团队 ID（可选） |
items[].agent_id | str | Agent ID（可选） |
items[].user_id | str | 用户 ID（可选） |
items[].task_id | str | Task ID（可选） |
total | int | 满足条件的笔记总数 |
错误码
错误码 | 触发场景 | 处理建议 |
401 | API Key 无效或过期 | 检查 api_key 配置 |
422 | 构造参数缺失 | 确保构造时传入必填归属参数 |
