一、设计要点
SDK 与 HTTP API 的关系：
·接口一一对应：SDK 方法的方法名、参数、返回值与 HTTP API 一一对应；方法签名映射的 HTTP 路径在每篇接口文档顶部明确标注。
·同步与异步双客户端：MemoryClient（同步）与 AsyncMemoryClient（异步）的方法签名、参数、返回结构完全一致；同步基于 httpx.Client，异步基于 httpx.AsyncClient。接口文档中“函数签名”行展示的是同步版本，异步只需在同名方法前加 await 即可。
·统一鉴权与错误处理：构造客户端时配置一次 endpoint / api_key / service_id，SDK 自动在每次请求中注入鉴权头（Authorization: Bearer …、x-tdai-service-id: …），网关返回非 2xx 时统一抛出 TdaiMemoryError 异常。
二、包元信息
| 项 | 值 |
| 包名 | tencentdb-agent-memory-sdk |
| 导入名 | tencentdb_agent_memory |
| 版本 | 0.1.0 |
| Python 版本 | >= 3.9 |
| 依赖 | httpx >= 0.24 |
三、安装
获取 tencentdb_agent_memory_sdk_python-0.1.0-py3-none-any.whl SDK，通过本地 wheel 安装：
pip install ./tencentdb_agent_memory_sdk-0.1.0-py3-none-any.whl
四、接口一览
| 层级 | SDK 方法 | HTTP 路径 |
| 原始对话 | add_conversation | POST /v2/conversation/add |
| 原始对话 | query_conversation | POST /v2/conversation/query |
| 原始对话 | search_conversation | POST /v2/conversation/search |
| 原始对话 | delete_conversation | POST /v2/conversation/delete |
| 原子记忆 | query_atomic | POST /v2/atomic/query |
| 原子记忆 | search_atomic | POST /v2/atomic/search |
| 原子记忆 | update_atomic | POST /v2/atomic/update |
| 原子记忆 | delete_atomic | POST /v2/atomic/delete |
| 场景记忆 | list_scenarios | POST /v2/scenario/ls |
| 场景记忆 | read_scenario | POST /v2/scenario/read |
| 场景记忆 | write_scenario | POST /v2/scenario/write |
| 场景记忆 | rm_scenario | POST /v2/scenario/rm |
| 核心记忆 | read_core | POST /v2/core/read |
| 核心记忆 | write_core | POST /v2/core/write |
五、错误处理
SDK 在网关返回非 2xx 时统一抛出 TdaiMemoryError，异常对象暴露以下字段：
| 字段 | 类型 | 含义 |
| code | int | 业务错误码（与 HTTP API 的 code 字段一致，例如 400、404、429、500） |
| message | str | 错误信息（来自响应体 message 字段） |
| trace_id | str | 请求追踪 ID（来自响应头 x-trace-id） |
| http_status | int | 底层 HTTP 状态码 |
典型处理模式：
from tencentdb_agent_memory import MemoryClientfrom tencentdb_agent_memory.errors import TdaiMemoryErrorclient = MemoryClient( endpoint="https://memory.tdai.tencentyun.com", api_key="sk-xxxxxxxx", service_id="tdai-mem-xxxxxxxx",)try: result = client.read_core()except TdaiMemoryError as e: if e.code == 404: # 尚未沉淀出核心记忆，调用 write_core 即可创建 client.write_core(content="# Agent 核心记忆\\n（首次写入）") else: raise