方法介绍
search_atomic 用于对 L1 原子记忆笔记执行语义检索。功能说明如下：检索方式：基于
query 文本进行智能检索，结合语义理解与关键词匹配，返回带相关性评分（score）的笔记列表，结果按 score 降序排列，值越高表示与查询文本的相关性越强。过滤条件：支持按记忆类型（
type）过滤以缩小检索范围。time_start / time_end 参数当前可传入但检索时暂未生效，传时间范围不会影响检索结果。返回数量：单次最多返回 100 条结果，默认返回 5 条。
导入
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.search_atomic(query="用户工作时间偏好",type="persona",limit=5,)for item in result["items"]:print(f"[score={item['score']:.2f}] [{item['type']}] {item['content']}")
请求参数
参数名 | 类型 | 必填 | 描述说明 |
query | str | 是 | 检索关键词或短语，长度 1–4096 字符 |
limit | int | 否 | 返回的最大命中条数，范围 1–100，默认 5 |
type | str | 否 | 记忆类型： episodic / persona / instruction。注意： 当前 SDK 未强制校验枚举值，传入其他字符串亦可执行，但建议仅使用上述三种类型以确保后续兼容。 |
session_id | str | 否 | 覆盖默认 session_id 以限定检索范围 |
time_start | str | 否 | 检索起始时间（暂未生效），ISO 8601 格式，当前可传入但检索时暂未使用 |
time_end | str | 否 | 检索截止时间（暂未生效），ISO 8601 格式，当前可传入但检索时暂未使用 |
响应示例
{"items": [{"id": "note-xxxx","version": 3,"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","score": 0.97}]}
Running Environment
Operating System: Ubuntu 24.04.3 LTS / x86_64
Runtime Version: Python 3.11.1
响应参数说明
参数名 | 类型 | 参数含义 |
items | List[Dict] | 检索命中笔记列表，按 score 降序 |
items[].id | str | 笔记唯一 ID |
items[].version | int | 当前版本号，从 1 开始递增 |
items[].type | str | 记忆类型 |
items[].background | str | 背景信息或来源说明 |
items[].content | str | 记忆内容 |
items[].created_at | str | 创建时间，ISO 8601 格式 |
items[].updated_at | str | 更新时间，ISO 8601 格式 |
items[].score | float | 语义相关度评分，0–1，值越高越相关 |
错误码
错误码 | 触发场景 | 处理建议 |
400 | query 为空或超过 4096 字符 | 检查 query 长度 |
401 | API Key 无效或过期 | 检查 api_key 配置 |
422 | 构造参数缺失 | 确保构造时传入必填归属参数 |
