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），僅供參考 TencentDB Agent Memory Python SDK 實戰指南：v2/v3 雙版本 API、團隊記憶隔離與 Metadata 管理面全解析
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），僅供參考