TencentDB Agent Memory TypeScript SDK 实战指南：v3 严格隔离数据面与元数据管理面详解

TencentDB Agent Memory TypeScript SDK 实战指南v3 严格隔离数据面与元数据管理面详解【免费下载链接】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 的官方 TypeScript SDK包名tencentdb-agent-memory/memory-sdk-ts-v2展开系统讲解 v3 严格隔离数据面MemoryClient与/v3/meta/*、/v3/knowledge/*管理面MetadataClient的完整用法并深入剖析 SDK 底层实现隔离上下文解析、HTTP 传输、错误模型。读完本文你将掌握如何在一个 TS/Node 项目中接入团队级 Agent 记忆中心完成对话写入、原子记忆检索、场景与核心记忆读写、团队/用户/资产元数据治理及知识源注册等全流程操作。一、SDK 定位与安装tencentdb-agent-memory/memory-sdk-ts-v2是 TencentDB Agent Memory 的 TypeScript 客户端覆盖三组能力v3 数据面 API/v3/*对话L0、原子记忆L1、场景记忆L2、核心记忆L3的读写与检索v3 元数据管理面 API/v3/meta/*共 54 条路由与面板 Control 的META_ACTIONS对齐涵盖 user / user-key / team / team-member / agent / task / asset / ACL / config 等治理能力Knowledge 实体管理面 CRUD/v3/knowledge/*5 条路由注册与管理 wiki、code-graph 两类知识源的元数据。从包的导出结构看src/index.ts 的顶级导出直接export * from ./v3/index.js即默认MemoryClient就是 v3 严格 isolation 版本老代码如果之前从.../v2/v3子路径导入package.json 中的exports保留了./v3子路径作为向后兼容别名指向同一个实现可无缝迁移。安装命令npm install tencentdb-agent-memory/memory-sdk-ts-v2运行环境要求根据 package.json 中engines字段需要 Node.js 18.0.0包采用 ESMtype: moduleHTTP 层基于undici实现见 package.json。二、MemoryClient 快速开始五分钟接入 v3 数据面v3 数据面要求构造客户端时必须传入完整的隔离身份。以下代码完整取自官方 README 的 Quick Start 并加以注释import { MemoryClient } from tencentdb-agent-memory/memory-sdk-ts-v2; const client new MemoryClient({ endpoint: http://127.0.0.1:8420, // MemoryCore 网关地址 apiKey: your-user-key, // 从面板拿的 sk-mem-… 用户密钥 serviceId: your-memory-instance-id, // 记忆实例 IDx-tdai-service-id teamId: team-xxx, // 团队 IDv3 必填 agentId: agt-xxx, // Agent IDv3 必填 userId: usr-xxx, // 用户 IDv3 必填 sessionId: sess-1, // 可选省略/清空后 L0/L1 跨 session 聚合 }); // L0写对话 await client.addConversation({ messages: [ { role: user, content: Hello }, { role: assistant, content: Hi! }, ], }); // L0查限定在当前 session const l0 await client.queryConversation({ limit: 20, offset: 0 }); // L0跨 session 聚合查询显式清空 sessionId const allSessions await client.withIsolation({ sessionId: null }).queryConversation({ limit: 20 }); // L1 / L2 / L3 const l1 await client.searchAtomic({ query: user preferences, limit: 5 }); const scene await client.readScenario({ path: work.md }); const core await client.readCore();v3 数据面差异要点官方明示所有请求路径统一走/v3/*前缀源码中const V3 /v3见 v3/client.ts构造时teamId/agentId/userId均必填严格 isolationsessionId可选语义分三种情况传入L0/L1 限定在单个 session 内读写不传或通过withIsolation({ sessionId: null })显式清空L0/L1 跨 session 聚合到 team agent user 维度L2/L3是 team agent 维度的 profile 数据不消费sessionId。三、隔离模型源码级解析teamId / agentId / userId / sessionId / taskIdv3 的“严格隔离”不是简单的参数校验而是贯穿客户端构造、请求体组装、写入保护三个环节的完整机制可以从 v3/client.ts 逐层验证。3.1 IsolationContext身份快照与逐请求覆盖SDK 内部用IsolationContext类v3/client.ts保存一份不可变身份快照。构造时requireNonEmpty强制校验teamId/agentId/userId非空缺任一字段都会抛出ParamError// v3/client.ts 中 IsolationContext 构造逻辑 requireNonEmpty(teamId, teamId); requireNonEmpty(agentId, agentId); requireNonEmpty(userId, userId);baseBody()将身份字段序列化为请求体中的team_id/agent_id/user_id/task_id值为undefined的字段会被stripUndefined过滤掉。这对应基础类型 types.ts 中IdFields的四个可选隔离字段设计——在 v2 时代它们全部可选而 v3 在客户端层强制要求前三个。3.2 写入保护addConversation 必须携带 session_id这是 v3 一个容易被忽略但很关键的设计写路径必须解析出非空 session_id。resolveSessionForWrite()v3/client.ts在构造参数和单次调用参数都没有提供sessionId时会直接抛ParamError源码注释解释了原因防止无 session 的写入在服务端被静默合并到默认 bucket从而与其他调用方的数据混在一起。而读路径query / search / count / delete允许省略 session服务端会按 team agent user 聚合。3.3 withIsolation函数式隔离切换withIsolation(overrides)v3/client.ts基于当前快照创建一个新MemoryClient实例并复用同一个 HTTP transport。注意sessionId: null和taskId: null表示显式清除该字段而undefined表示沿用默认值。类型定义见 v3/types.ts 的V3IsolationOverrides。这种不可变快照 覆盖合并的模式让你可以在一个 endpoint 上安全地复用连接、按调用粒度切换隔离维度而不会污染其他调用。四、v3 数据面 API 全览L0L3 四层记忆官方 README 给出了完整的 API 方法表这里完整继承并补充请求参数说明层方法Endpoint核心入参L0addConversation()POST /v3/conversation/addmessages[]必填、session_id必填L0queryConversation()POST /v3/conversation/querylimit、offset、time_start、time_end、session_idL0searchConversation()POST /v3/conversation/searchquery必填、limit、time_start、time_end、session_idL0deleteConversation()POST /v3/conversation/deletemessage_ids[]或session_id二选一L0countConversation()POST /v3/conversation/countsession_id、time_start、time_endL1updateAtomic()POST /v3/atomic/updateid、content必填、backgroundL1queryAtomic()POST /v3/atomic/querytype、limit、offset、time_start、time_endL1searchAtomic()POST /v3/atomic/searchquery必填、limit、type、time_start、time_endL1deleteAtomic()POST /v3/atomic/deleteids[]必填L1countAtomic()POST /v3/atomic/counttype、time_start、time_endL2listScenarios()POST /v3/scenario/lspath_prefixL2readScenario()POST /v3/scenario/readpath必填L2writeScenario()POST /v3/scenario/writepath、content必填、summaryL2rmScenario()POST /v3/scenario/rmpath必填L2countScenario()POST /v3/scenario/countpath_prefixL3readCore()POST /v3/core/read无纯身份上下文L3writeCore()POST /v3/core/writecontent必填L3countCore()POST /v3/core/count无纯身份上下文4.1 L0 对话记忆最原始的记录层对话是记忆的原材料。ConversationItem的结构定义在 types.tsrole取值user | assistant | systemcontent为消息文本id与timestamp可选。写入成功返回{ accepted_ids, total_count }查询返回{ messages, total }搜索命中项额外携带score相似度分数见 types.ts。值得注意的两个边界行为源码可见deleteConversation在既没有message_ids也没有session_id时抛ParamError且message_ids必须是「非空字符串的非空列表」v3/client.ts所有 L0 请求都会通过resolveSession合并构造期默认值与调用期覆盖值v3/client.ts。4.2 L1 原子记忆可检索的事实碎片L1 是经抽取后的原子化记忆条目AtomicDetailtypes.ts包含id、type、content、background以及创建/更新时间。type字段用于记忆分类可结合业务自行定义如preference、fact等searchAtomic和queryAtomic都支持按type过滤搜索命中同样带score。4.3 L2 场景记忆按路径组织的文档文件L2 将记忆组织为带路径的“文件”适合存放工作场景、项目背景等结构化工件。ScenarioFiletypes.ts的content/created_at/updated_at在文件不存在时为null方便做存在性判断。listScenarios支持path_prefix前缀过滤writeScenario可附带summary摘要。由于 L2 是 team agent 维度调用时无需也不消费session_id。4.4 L3 核心记忆Agent 的长期画像L3 是最高层级的核心记忆相当于 team agent 维度一份可覆盖写入的 profile 文件。readCore()/writeCore()/countCore()三个方法请求体只携带隔离上下文见 v3/client.ts无其他业务参数。五、MetadataClientv3 管理面/v3/meta/*数据面之外SDK 提供MetadataClient封装网关的 v3 元数据管理端点。它覆盖 54 条META_ACTIONS路由含user-key/*并额外包含/v3/knowledge/*。鉴权方式为Bearertoken x-tdai-service-id请求头可选携带x-tdai-user-key。这些头部在 v3/http.ts 中统一设置this.headers { Authorization: Bearer ${opts.apiKey}, x-tdai-service-id: opts.serviceId, Content-Type: application/json, }; if (opts.userKey) this.headers[x-tdai-user-key] opts.userKey;构造示例完整继承自官方 READMEimport { MetadataClient } from tencentdb-agent-memory/memory-sdk-ts-v2; const meta new MetadataClient({ endpoint: http://127.0.0.1:8420, apiKey: verify-token, // gateway Bearer (KERNEL_AUTH_TOKEN) serviceId: knowledge-debug, // x-tdai-service-id // userKey: ..., // 可选system_admin 端点user/create、user/delete需要 });注意MetadataClient与MemoryClient的apiKey语义不同——前者是网关 Bearer 密钥KERNEL_AUTH_TOKEN后者是用户的sk-mem-…用户密钥。5.1 管理面能力矩阵从 v3/metadata-client.ts 的实现可以梳理出完整能力分组端点统一挂载在const V3 /v3/meta前缀下见该文件 L72分组代表方法端点说明UsercreateUser/getUser/deleteUsers/listUsers/v3/meta/user/*用户治理user/create、user/delete需要 system_admin 级 userKeyUserKeycreateUserKey/listUserKeys/getUserKey/revokeUserKey/updateUserKey/v3/meta/user-key/*用户 API 密钥生命周期管理TeamcreateTeam/getTeam/updateTeam/deleteTeams/listTeams/v3/meta/team/*团队治理TeamMemberaddTeamMember/removeTeamMember/listTeamMembers/getTeamMember/v3/meta/team-member/*团队成员管理AgentcreateAgent/getAgent/updateAgent/deleteAgents/listAgents/archiveAgent/v3/meta/agent/*Agent 治理与归档TaskcreateTask/getTask/updateTask/deleteTasks/listTasks/archiveTask/v3/meta/task/*任务治理与归档TaskAgentlinkTaskAgent/unlinkTaskAgent/listTaskAgents/v3/meta/task-agent/*Agent-任务关联ParticipationLogappendParticipationLog/listParticipationLogs/v3/meta/participation-log/*参与日志AssetcreateAsset/getAsset/updateAsset/deleteAssets/listAssets/listAccessibleAssets/touchAssetUsage/v3/meta/asset/*资产治理与使用统计AgentFixedAssetsetAgentFixedAssets/listAgentFixedAssets/listAgentFixedAssetsWithDetail/summarizeAgentFixedAssetsByAgents/v3/meta/agent-fixed-asset/*Agent 固定资产绑定ACLgrantAcl/revokeAcl/listAcl/checkAcl/v3/meta/acl/*资产访问控制AuthverifyAuth/v3/meta/auth/verify用户密钥校验body 传user_keyConfigParam (v3.2)getInstanceQuota/getUserConfig/setUserConfig/v3/meta/instance-quota/get、/v3/meta/config/user/*实例配额与用户配置实现细节部分list*方法做了重载设计——如listTeams既接受(userId, pagination)二元参数也接受完整ListTeamsRequest对象同时通过requireAnyString在客户端前置校验关键字段如listTeams要求user_id或user_key至少一个把参数错误尽早拦截在本地v3/metadata-client.ts。六、Knowledge 知识源管理/v3/knowledge/*MetadataClient还封装了 Knowledge 实体的管理面 CRUD。重要边界这些是管理面的元数据操作——实际搜索 wiki 内容、阅读页面、同步代码仓库属于 Knowledge Service 数据面service_url指向的服务的职责本客户端不做。官方 README 的完整方法表方法EndpointNotescreateKnowledge()POST /v3/knowledge/createupsert 元数据幂等重复提交覆盖getKnowledge(id, teamId?)POST /v3/knowledge/get按 id 查询updateKnowledge()POST /v3/knowledge/update部分更新name/summary/service_url/repo_url/branchdeleteKnowledge(ids, teamId?)POST /v3/knowledge/delete批量删除≤100listKnowledge()POST /v3/knowledge/list按 team_id 列出可选 type 过滤 / 批量 id 查询类型上Knowledge 实体分为wiki与code-graph两种KnowledgeType。代码示例完整继承自官方 README// 注册一个 wiki 知识源 const k await meta.createKnowledge({ knowledge_id: wiki-docs, type: wiki, service_url: http://127.0.0.1:8421/v3, // Knowledge Service 数据面 URL name: Team Docs Wiki, summary: Internal tech docs, team_id: team-1, user_id: usr-1, }); console.log(k.knowledge_id, k.type, k.created_at); // 列出某个团队下所有 code-graph const list await meta.listKnowledge({ team_id: team-1, type: code-graph }); console.log(list.items, list.total); // 重命名 / 更换 service_url await meta.updateKnowledge({ knowledge_id: wiki-docs, name: Renamed Wiki }); // 批量删除 await meta.deleteKnowledge([wiki-docs, cg-repo-1], team-1);返回类型KnowledgeEntity/KnowledgeListResult { items, total }/BatchDeleteResult { deleted_ids, failed }。源码层面Knowledge 端点挂在/v3/knowledge前缀V3_KNOWLEDGE常量见 v3/metadata-client.ts不属于/v3/meta前缀其 handler 不读 user-keyteam_id直接放在请求 body 中。七、SkillClient技能记忆/v3/skill/*README 主文档之外SDK 还附带SkillClient封装 src/gateway/skill-handlers.ts 定义的 15 个/v3/skill/*端点create / update / patch / delete / get / list / search / versions / files-write / files-remove / files-read / listing / extract / conversation-add / conversation-force-archive。SkillClient与MemoryClient的隔离语义不同v3/skill-client.tsCRUD / file / listing / search 端点在 schema 层全部可选隔离字段因此 SDK 把它们作为构造期 defaults 接受、每次调用可覆盖且缺失 id 时不会在客户端抛错交由服务端按需返回 40001/40301/40302。而/extract、/conversation/add、/conversation/force-archive有更严格的字段要求/extractSDK 合并构造期 defaults 后本地校验user_id / team_id / agent_id非空、messages至少一条随后发起异步抽取任务立即返回{ task_id, archive_key, archived_at_ms }真正的技能挖掘在 core worker 异步完成可通过/v3/skill/list或/v3/skill/search按task_ref_id过滤观察结果v3/skill-client.ts/conversation/add、/conversation/force-archivesession_id / user_id / team_id / agent_id均为必填且 SDK不合并构造期 defaults调用方必须显式传参。八、错误处理TDAMError 统一模型所有非零code响应都会抛出TDAMError。官方 README 的错误处理示例import { TDAMError } from tencentdb-agent-memory/memory-sdk-ts-v2; try { await client.readCore(); } catch (e) { if (e instanceof TDAMError) { console.error(code${e.code} message${e.message} request_id${e.requestId}); } }从 errors.ts 看SDK 定义了两类错误ParamError extends TypeError客户端参数校验失败如 v3 必填 id 缺失、endpoint 非法 URL、timeout 非正数TDAMError extends Error服务端业务/传输错误携带code、requestId、可选details三个字段。TDAMError.details有明确的实战用途部分端点在code ! 0时会把诊断字段放进data例如/v3/skill/update在40901 SKILL_VERSION_STALE时返回{ current_version }/v3/skill/files/read在41002 SKILL_VERSION_EXPIRED时返回{ latest_version }这些信息被保留在details中供调用方做冲突恢复见 errors.ts 注释。底层判定逻辑位于 v3/http.ts!response.ok || businessCode ! 0时抛错code优先取业务码、否则回退 HTTP statusrequestId的解析顺序为响应头x-qcloud-transaction-id→x-trace-id→ 响应体request_id。此外每次成功响应还会把响应头x-trace-id注入返回对象若为对象方便全链路追踪v3/http.ts。九、构建、测试与打包官方 README 给出了标准的三步流程npm run build # tsc 编译到 dist/ npm test # vitest 运行测试 npm pack # 打 npm 包package.json 中的脚本细节build为tscprepack/prepublishOnly都会先执行clean清空 dist再构建保证发布产物干净test使用vitest run支持test:watch开发模式。包发布内容为dist/、src/、README.md见files字段。十、进阶传输层与自定义 TransportV3HttpTransportv3/http.ts是 v3 客户端的唯一 HTTP 实现值得注意的配置项endpoint必须为合法的http:/https:URL否则抛ParamError末尾多余的/会被去掉timeout默认30000 ms必须是正数超时通过AbortController中止请求rejectUnauthorized: false可关闭 TLS 证书校验通过 undiciAgent的connect.rejectUnauthorized实现仅建议在自签名证书的内网环境使用所有请求统一POSTContent-Type: application/json。同时index.ts 还从./cos.js导出了MemoryFileReader、StsCredentialManager、cosV5Sign、createMemoryFileReader等能力供需要以 STS 临时凭证直读 COS 文件的调用方使用Transport接口见 v3/client.ts 的构造重载允许传入自定义 Transport实现 mock 或特殊网络策略。十一、小结tencentdb-agent-memory/memory-sdk-ts-v2用一个包覆盖了 TencentDB Agent Memory 的完整客户端能力MemoryClient负责 L0L3 四层记忆数据面的严格隔离读写MetadataClient负责团队级元数据治理与知识源管理SkillClient承接技能记忆的抽取与文件管理。理解隔离模型必填的 team/agent/user 三元组 可选 session 的读写差异与统一的TDAMError错误模型是在生产环境中正确使用该 SDK 的关键。更多示例与详细类型可继续阅读仓库中的 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），仅供参考