TencentDB Agent Memory Python SDK 实战指南v2/v3 双版本 API、团队记忆隔离与 Metadata 管理面全解析【免费下载链接】TencentDB-Agent-MemoryTencentDB Agent Memory is a team-level memory hub for AI Agents — turning conversations, docs, and code into four reusable memory assets (Chat Memory, Skill, LLM-Wiki, Code-Graph) that are governed, shared, and equipped across agents and frameworks.项目地址: https://gitcode.com/GitHub_Trending/te/TencentDB-Agent-Memory本文以 TencentDB Agent Memory 官方 Python SDKsdk/memory-core/python/README_CN.md为主线系统讲解如何通过MemoryClient/AsyncMemoryClient接入团队级记忆中枢L0 对话、L1 原子记忆、L2 场景文件、L3 核心画像与 Offload 上下文压缩并结合仓库源码剖析 v2/v3 隔离机制、请求包络、错误体系与底层传输实现。读完本文你将能够独立完成 SDK 安装、同步/异步客户端接入、v3 严格隔离配置、管理面 Knowledge 实体管理以及错误排查与本地打包发布。一、SDK 概览包名、导入路径与版本策略SDK 的发布包与导入模块名并不相同使用时务必区分发布包名tencentdb-agent-memory-sdk-pythonPyPI通过pip install安装导入路径tencentdb_agent_memoryPython 模块SDK 采用“子模块拆版本”的布局风格参考 tencentcloud-sdk-python 的组织方式同时支持 v2 与 v3 两代 API并提供同步MemoryClient与异步AsyncMemoryClient两套客户端。默认导出指向 v2老代码升级 SDK 后无需任何改动即可继续工作需要切换到 v3 严格隔离版本时显式从tencentdb_agent_memory.v3导入即可。这一策略在 模块入口 的 docstring 中有明确说明# 老代码默认导出即 v2 from tencentdb_agent_memory import MemoryClient # 新代码严格 isolation走 /v3 路径 from tencentdb_agent_memory.v3 import MemoryClient client MemoryClient(endpoint, api_key, service_id..., team_idt1, agent_ida1, user_idu1)当前仓库中的 SDK 版本为 0.2.0见 pyproject.toml要求 Python 3.9唯一的核心依赖是httpx0.24.0。二、安装 SDK根据 README_CN.md 与 pyproject.toml有两种安装方式# 从 PyPI 安装发布后 pip install tencentdb-agent-memory-sdk-python # 从本地 .whl 安装 pip install ./tencentdb_agent_memory_sdk_python-0.1.0-py3-none-any.whl运行时依赖仅httpx0.24.0同时支撑同步与异步 HTTP 传输。开发/测试可选依赖包括pytest7.0、pytest-asyncio0.21、respx0.20HTTP mock 库、build、python-dotenv1.0。项目使用 hatchling 作为构建后端wheel 打包目录为tencentdb_agent_memory。三、快速开始一条代码走通 L0–L3 与 OffloadSDK 客户端构造需要三个关键参数参数含义来源endpoint记忆服务网关地址如http://127.0.0.1:8420部署方提供api_keyBearer 令牌通过Authorization: Bearer key头发送平台下发service_id记忆空间实例 ID通过x-tdai-service-id头发送平台下发以下代码覆盖了数据面的全部核心能力L0 对话、L1 原子记忆、L2 场景文件、L3 核心记忆、Offload 上报与压缩、pipeline 产物读取from tencentdb_agent_memory import MemoryClient client MemoryClient( endpointhttp://127.0.0.1:8420, api_keyyour-api-key, service_idyour-memory-space-id, ) # L0: 添加对话 result client.add_conversation( session_idsess-1, messages[ {role: user, content: Hello}, {role: assistant, content: Hi!}, ], ) print(result[accepted_ids]) # L1: 搜索结构化记忆 hits client.search_atomic(queryuser preferences, limit5) print(hits[items]) # L1: 更新一条记忆 client.update_atomic(idnote-xxx, contentupdated content, backgroundcontext) # L2: 列出场景文件 scenarios client.list_scenarios(path_prefix) print(scenarios[entries]) # L2: 读取场景文件 file client.read_scenario(工作.md) print(file[content]) # L2: 更新场景文件文件必须已存在 client.write_scenario(工作.md, # Updated content, summarynew summary) # L3: 读取核心记忆用户画像 core client.read_core() print(core[content]) # L3: 写入核心记忆 client.write_core(# User Profile\n...) # Offload v2: 上报工具调用对触发服务端 L1 异步处理可 fire-and-forget client.offload_ingest( session_idagent_sess_123, tool_pairs[ {tool_name: search, tool_call_id: call_1, params: {q: ...}, result: ..., timestamp: ...}, ], ) # Offload v2: 服务端上下文压缩同步等待结果 compacted client.offload_compact( session_idagent_sess_123, messages[...], ratio0.7, context_window128000, ) print(compacted[messages], compacted[report]) # 读取记忆 pipeline 产物如 persona.md、scene_blocks/*.md raw client.read_file(scene_blocks/工作.md)几点值得注意的细节均可在 v2 客户端源码 中得到印证read_scenario/read_core在文件或画像尚未生成时返回的content为None而非抛出异常offload_ingest是异步处理触发接口可 fire-and-forget 忽略返回值支持可选参数prompt最新 user message用于 L1.5 任务判断与recent_messages近期历史消息辅助 L1 提取上下文offload_compact中ratio表示当前 token 使用比例已用 / context_windowtotal_tokens是包含 system prompt、tool schemas 等隐性开销在内的完整上下文 token 总数服务端据此计算 fixed overhead 并校准 token 估算可选的message_tokens列表可跳过服务端估算提升性能offload_query_mmd可查询会话的任务流程图MMD 文件limit1时走快速路径只返回当前活跃 MMD返回结构为mmds每项含filename、content、versioncurrent_mmd。3.1 底层传输包络解包与 trace 传播所有数据面调用最终都经由HttpStub.post()完成见 HTTP 传输层。其工作流程为将endpoint与请求路径拼接携带Authorization: Bearer api_key、x-tdai-service-id: service_id、Content-Type: application/json三个固定请求头发送 JSON bodytimeout默认为 30 秒verifyFalsev2 传输默认关闭 TLS 校验v3 传输默认开启见下文解析响应包络{ code, message, data, request_id }code 0时解包返回data否则抛出TDAMError若响应头携带x-trace-id会自动注入返回结果中便于链路追踪。v2 传输层还支持注入自定义stub构造参数方便测试时替换真实 HTTP 传输。四、异步用法AsyncMemoryClientSDK 提供与同步客户端 API 面完全一致的异步客户端基于 httpx 的AsyncClient实现支持上下文管理器自动释放连接import asyncio from tencentdb_agent_memory import AsyncMemoryClient async def main(): async with AsyncMemoryClient( endpointhttp://127.0.0.1:8420, api_keyyour-api-key, service_idyour-memory-space-id, ) as client: result await client.search_atomic(querypreferences) print(result[items]) asyncio.run(main())同步与异步客户端均实现了上下文协议__enter__/__exit__、__aenter__/__aexit__在关闭时不仅会关闭 HTTP 连接还会释放内部懒加载的文件读取器COS 连接。五、API 方法全景v3 与 v2 双版本对照5.1 v3推荐严格隔离v3 与 v2 的主要差异L0/L1 强制要求session_idstrict session isolation请求路径从/v2/*升级为/v3/*响应包络结构一致。层级方法接口L0add_conversation()POST /v3/conversation/addL0query_conversation()POST /v3/conversation/queryL0search_conversation()POST /v3/conversation/searchL0delete_conversation()POST /v3/conversation/deleteL1update_atomic()POST /v3/atomic/updateL1query_atomic()POST /v3/atomic/queryL1search_atomic()POST /v3/atomic/searchL1delete_atomic()POST /v3/atomic/deleteL2list_scenarios()POST /v3/scenario/lsL2read_scenario()POST /v3/scenario/readL2write_scenario()POST /v3/scenario/writeL2rm_scenario()POST /v3/scenario/rmL3read_core()POST /v3/core/readL3write_core()POST /v3/core/writeOffloadoffload_ingest()POST /v3/offload/ingestOffloadoffload_compact()POST /v3/offload/compactOffloadoffload_query_mmd()POST /v3/offload/query-mmd需要说明的是README 中列出的offload_*三个接口在 v3 客户端源码中并未暴露——v3 客户端 的 docstring 明确写道“offload/read_file等非 L0–L3 接口未在 v3 暴露——继续使用 v2 客户端”。因此使用 Offload 与 pipeline 产物读取能力时应使用默认导出的 v2 客户端。此外v3 客户端相比 v2 还新增了一批count 统计接口count_conversationPOST /v3/conversation/count、count_atomicPOST /v3/atomic/count、count_scenarioPOST /v3/scenario/count、count_corePOST /v3/core/count与对应 query 接口同过滤器仅返回{total}适用于治理面板等需要聚合计数的场景。5.2 v2兼容v2 的 L0/L1 不强制session_id隔离仅基于(team_id, user_id, agent_id)三元组。层级方法接口L0add_conversation()POST /v2/conversation/addL0query_conversation()POST /v2/conversation/queryL0search_conversation()POST /v2/conversation/searchL0delete_conversation()POST /v2/conversation/deleteL1update_atomic()POST /v2/atomic/updateL1query_atomic()POST /v2/atomic/queryL1search_atomic()POST /v2/atomic/searchL1delete_atomic()POST /v2/atomic/deleteL2list_scenarios()POST /v2/scenario/lsL2read_scenario()POST /v2/scenario/readL2write_scenario()POST /v2/scenario/writeL2rm_scenario()POST /v2/scenario/rmL3read_core()POST /v2/core/readL3write_core()POST /v2/core/writeOffloadoffload_ingest()POST /v2/offload/ingestOffloadoffload_compact()POST /v2/offload/compactOffloadoffload_query_mmd()POST /v2/offload/query-mmdv2 客户端的所有方法都支持可选的team_id/agent_id/user_id/task_id四个隔离参数其中task_id是 v2 独有的第四个隔离维度。从 v2 客户端源码 可见这些字段通过_id_fields()统一收敛进请求 body且None值会被_strip_none()剔除——服务端resolveIsolation优先取 body 字段缺失时回退x-tdai-*header。5.3 v3 vs v2 差异说明维度v2v3路径前缀/v2/*/v3/*L0/L1 隔离(team_id, user_id, agent_id)三元组三元组 session_idstrict session isolationsession_id可选L0/L1 必填缺失返回 422L2/L3仅三元组隔离仅三元组隔离无变化响应包络{ code, message, data, request_id }同 v2结构不变六、深入 v3 隔离机制构造校验、session 解析与 with_isolationv3 的“严格隔离”在 v3 客户端源码 中有非常严谨的落地理解这套规则是正确使用 v3 的关键1. 构造时强制校验三元组。构造 v3MemoryClient时team_id、agent_id、user_id必填任一缺失立即抛出ParamError而非等到服务端返回 422session_id与task_id可选from tencentdb_agent_memory.v3 import MemoryClient client MemoryClient( endpointhttps://memory.tencentyun.com, api_keysk-..., service_idmem-..., team_idt1, agent_ida1, user_idu1, session_ids1, # 可选不传时 L0/L1 查询走跨 session 聚合 )2. 写入必须带 session_id。add_conversation的写入路径调用resolve_session_for_write()——如果构造与调用时都没有提供session_id会直接抛出ValueError。这样设计是为了避免服务端把无 session 的写入静默合并进默认 bucket与其他调用方的数据混在一起。3. 读取可跨 session 聚合。读接口query / search / count / delete的session_id可选传入则按 session 收敛缺省则按(team, agent, user)跨 session 聚合即“agent 维度全量视图”语义用于治理面板的 layer-counts、跨会话 L0/L1 列表等场景。4. L2/L3 不消费 session_id。场景文件与核心画像本来就是 teamagent 级的 profile 聚合请求 body 仅携带三元组base_body()因此调用read_scenario/write_core等无需 session。5.with_isolation()克隆视图。返回共享同一传输连接、仅覆盖部分隔离字段的客户端克隆可用于切换会话上下文或显式清除绑定的 session/task# 跨 session 拉某 agent 的全部 L0 对话总数 client.with_isolation(session_idNone).query_conversation(limit1)在with_isolation()中省略某参数表示保留当前值显式传None表示清除已绑定的值。6. v3 传输更严格。v3 使用独立的 v3 传输层构造时校验endpoint必须是合法 http(s) URL、api_key/service_id非空、timeout为正数且默认verifyTrue开启 TLS 证书校验与 v2 默认verifyFalse形成对比。v3 的解包逻辑还额外处理了“HTTP 错误但包络 code 缺失”等边界情况。七、MetadataClientv3 管理面Knowledge 实体管理MetadataClient/AsyncMetadataClient封装网关 v3 管理面接口与数据面MemoryClient有本质区别不需要isolation 四元组team/agent/user/session鉴权用 Bearer x-tdai-service-idteam_id等业务字段放在请求 body 里可选user_key走x-tdai-user-key头user/create、user/delete等 system_admin 接口需要。当前封装范围包括/v3/meta/*公开接口54 条与 Panel Control 的META_ACTIONS对齐覆盖 user / user-key / team / team-member / agent / task / task-agent / participation-log / asset / agent-fixed-asset / acl / auth / config-param 等实体以及/v3/knowledge/*Knowledge 实体 CRUD 5 条。from tencentdb_agent_memory.v3 import MetadataClient meta MetadataClient( endpointhttp://127.0.0.1:8420, api_keyverify-token, # 网关 BearerKERNEL_AUTH_TOKEN service_idknowledge-debug, # x-tdai-service-id # user_key..., # 可选system_admin 接口才需要 ) # 登记一个 wiki 知识源 k meta.create_knowledge({ knowledge_id: wiki-docs, type: wiki, service_url: http://127.0.0.1:8421/v3, # Knowledge Service 数据面地址 name: 团队文档 Wiki, summary: 内部技术文档, team_id: team-1, user_id: usr-1, }) print(k[knowledge_id], k[type], k[created_at]) # 列出某团队下的全部 code-graph lst meta.list_knowledge({team_id: team-1, type: code-graph}) print(lst[items], lst[total]) # 改名 / 换 service_url meta.update_knowledge({knowledge_id: wiki-docs, name: 改名后的 Wiki}) # 批量删除 meta.delete_knowledge([wiki-docs, cg-repo-1], team_idteam-1)Knowledge 管理面 CRUD 接口说明方法接口说明create_knowledge(p)POST /v3/knowledge/createupsert 元数据幂等重复 post 即覆盖get_knowledge(id, team_idNone)POST /v3/knowledge/get单条查询update_knowledge(p)POST /v3/knowledge/update部分更新name/summary/service_url/repo_url/branchdelete_knowledge(ids, team_idNone)POST /v3/knowledge/delete批量删除≤100list_knowledge(p)POST /v3/knowledge/list按 team_id 列出可选 type 过滤 / 按 id 批查明细注意这组接口是管理面 CRUD只管元数据真正去 wiki/code-graph 里搜内容、读页面、同步仓库是 Knowledge Service 数据面service_url指向的:8421的活不在这个客户端里。在 metadata 客户端源码 中可以看到管理面请求体经过_body()统一做类型校验与None剔除且部分接口如list_teams、list_tasks通过_require_any()强制要求至少一个定位字段把参数错误前置到客户端。八、错误处理TDAMError 与 ParamErrorSDK 定义了两种异常类型见 errors.pyTDAMError所有非零code的响应都会抛出。属性包含code业务错误码、message错误信息、request_id从x-qcloud-transaction-id响应头或包络request_id字段解析、details错误时包络data负载若为 dict 则保留。例如/v3/skill/*端点会通过details回传current_version40901 SKILL_VERSION_STALE或latest_version41002 SKILL_VERSION_EXPIRED便于调用方重试或升级。ParamError调用方参数非法时抛出如 v3 构造缺三元组、delete_conversation未提供任何选择器、message_ids为空列表等。from tencentdb_agent_memory import TDAMError try: client.read_core() except TDAMError as e: print(fcode{e.code} message{e.message} request_id{e.request_id})九、read_file读取记忆 pipeline 产物STS COS 直读read_file(path)与数据面其他接口不同它不走网关 JSON 包络而是直接读取对象存储中的 pipeline 产物文件如persona.md、scene_blocks/*.md。其底层链路见 COS 文件读取实现值得了解首次调用时懒加载StsCredentialManager向平台POST /v2/cos/secret申请 STS 临时密钥响应含CosUrl、TmpSecretId、TmpSecretKey、TmpToken、ExpirationTime、PathPrefix从CosUrl形如https://{bucket}.cos.{region}.myqcloud.com解析出 bucket 与 region临时密钥按过期时间缓存提前 120 秒视为失效带线程锁做双重检查与并发刷新合并async 版本用asyncio.Lock用 COS V5 签名_cos_v5_sign()sha1 HMAC 四步签名对 GET 请求签名token 走x-cos-security-token头最终 COS key 为{PathPrefix}{path}403 时自动失效缓存并重试一次404 抛出TDAMError(code404, messageFile not found: ...)。该 API 对外保持存储无关抽象——“当前后端是 COS但公开接口刻意与具体存储解耦”。十、构建与打包本地构建 wheel 有两种方式# 构建 wheel含 sdist python -m build # → dist/tencentdb_agent_memory_sdk_python-0.1.0-py3-none-any.whl # 或仅构建 wheel pip wheel . --no-deps -w dist/构建产物为纯 Python wheelpy3-none-any构建后端为 hatchling打包目录固定在tencentdb_agent_memory。十一、依赖与版本项值运行时依赖httpx0.24.0同步 异步 HTTP 客户端Python 版本要求3.9当前仓库版本0.2.0pyproject.toml许可证MIT十二、选型建议v2 还是 v3结合 README 与源码可以给出如下务实建议新接入、强隔离诉求多租户/多会话并存选择 v3team_id/agent_id/user_id构造必填 L0/L1 写入强制session_id从客户端层面杜绝数据串写存量代码平滑升级默认导出即 v2API 签名保持兼容零修改可用Offload 与 pipeline 产物读取无论哪种主客户端offload_*与read_file均需使用 v2 客户端v3 客户端未暴露这些接口治理/管理面操作使用MetadataClient它不需要隔离四元组当前重点覆盖 Knowledge 实体 CRUD其余 meta 实体user/team/agent/task/asset/acl/config也已具备完整封装。进一步可阅读的仓库资料SDK 中文 README、Python 使用指南AGENT_GUIDE、变更日志以及同仓库的 TypeScript SDK 作为跨语言参考。【免费下载链接】TencentDB-Agent-MemoryTencentDB Agent Memory is a team-level memory hub for AI Agents — turning conversations, docs, and code into four reusable memory assets (Chat Memory, Skill, LLM-Wiki, Code-Graph) that are governed, shared, and equipped across agents and frameworks.项目地址: https://gitcode.com/GitHub_Trending/te/TencentDB-Agent-Memory创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考