MemoryClient 和 AsyncMemoryClient 共享完全相同的19个数据面方法,覆盖 L0 – L3 四层记忆操作及资产级内容清空。说明:
同步 / 异步用法一致:下方所有方法在
MemoryClient 中直接调用,在 AsyncMemoryClient 中加 await 调用,参数和返回结构完全一致。异常说明:构造时缺少非空 team_id / agent_id / user_id,SDK 在发送请求前抛出 ParamError;add_conversation 缺有效 session_id 时抛出 ValueError。服务器422仅在服务开启严格隔离校验且请求缺少必需隔离字段时可能返回,不能与 SDK 构造校验混同。时间范围建议统一使用 UTC、固定三位毫秒并以 Z 结尾,例如 2026-07-01T00:00:00.000Z;time_start <= time_end。原子记忆按 updated_time 比较,勿混用省略毫秒或不同时区的同义写法。L0 原始对话
L0 层提供对话记录的写入、分页查询、语义检索、批量删除和统计能力。
方法 | 说明 | 文档 |
add_conversation | 追加对话记录;session_id 必须非空(构造或调用提供) | |
query_conversation | 分页查询对话记录;会话可选,支持时间闭区间 | |
search_conversation | 语义检索对话记录;时间参数暂未生效 | |
delete_conversation | 批量删除;message_ids ≤5000 / session_ids ≤100,至少一项 | |
count_conversation | 统计对话记录数量 |
L1 原子记忆
L1 层提供原子记忆的更新、分页查询、语义检索、批量删除和统计能力。原子记忆由系统从 L0 对话中自动抽取生成,也支持通过
update_atomic 手动干预。方法 | 说明 | 文档 |
update_atomic | 更新原子记忆 | |
query_atomic | 分页查询原子记忆;按更新时间过滤,会话参数暂未生效 | |
search_atomic | 语义检索原子记忆;会话及时间参数暂未生效 | |
delete_atomic | 按 ids 批量删除原子记忆,单次 ≤ 5000 条 | |
count_atomic | 统计原子记忆数量;按更新时间过滤,会话参数暂未生效 |
L2 场景记忆
L2 层提供场景记忆文件的列出、读取、写入、删除和统计能力。场景记忆以路径(path)为唯一标识,支持类文件系统的层级管理。
方法 | 说明 | 文档 |
list_scenarios | 列出场景记忆文件 | |
read_scenario | 读取最新场景记忆;无 version 入参 | |
write_scenario | 写入场景记忆内容 | |
rm_scenario | 按单个 path 删除场景记忆 | |
count_scenario | 统计场景记忆数量 |
L3 核心记忆
L3 层提供核心记忆的读取、写入和统计能力。核心记忆为最高层级的结构化长期记忆,由系统从 L1/L2 中归纳生成,也支持手动写入。
方法 | 说明 | 文档 |
read_core | 读取最新核心记忆;无 version 入参 | |
write_core | 写入核心记忆 | |
count_core | 统计核心记忆文件数量;SDK 无方法参数 |
资产级内容清空
clear_chat_memory(memory_ids: List[str]) -> Dict[str, Any] 接收1 – 100个 Chat Memory 资产 ID。清空内容但保留资产及其绑定、归属和权限;不使用构造时的隔离三元组。
result = client.clear_chat_memory(["mem-example"])if not result["all_cleared"]:for item in result["items"]:if not item["cleared"]:print(item["memory_id"], item.get("reason"), item.get("retryable"))
返回 items 和 all_cleared;每项包含 memory_id、cleared、l0_deleted、l1_deleted、profile_deleted,失败时可有 reason、retryable、attempts。检查结果后再重试失败项。异步客户端使用 await client.clear_chat_memory([...])。完整 HTTP 参数及错误说明见 HTTP → Memory → 清空 Chat Memory 内容。