TencentDB Agent Memory 的两个 SDK 与路线图上的五项
翻一个仓库的 SDK，我习惯先干一件很笨的事：把 README 里的安装命令，和包元数据文件里的 name 字段并排放在一起看一眼。多数时候这一眼白看，偶尔会看出点东西。
TencentDB Agent Memory 的 sdk/memory-core/ 就属于后者。
先把前提摆清楚：以下全部内容来自 2026-08-16 我们取到的仓库快照 97f9465，分支是 feat/server_team——这个仓库的默认分支就是它，不是 main 也不是 master，所以下文所有路径都请按这个分支去对。我们没有部署、没有运行、没有安装过这个项目的任何一个模块，也没有联网查过 PyPI 或 npm，下面说的每一句都是静态读文件读出来的。
一、包名与安装命令，两边差一个 -v2
sdk/ 下只有一个子目录 memory-core，其下再分 python/ 与 typescript/ 两侧。git 跟踪文件合计 44 个（git ls-files sdk | wc -l，截至 2026-08-16）。
把两侧的「元数据里的名字」和「自家 README 让你敲的名字」摆到一张表里：
| 侧 | 元数据 name | 出处 | README 安装命令里用的名字 | 出处 |
|---|---|---|---|---|
| Python | tencentdb-agent-memory-sdk-python-v2 | sdk/memory-core/python/pyproject.toml:6 | tencentdb-agent-memory-sdk-python | python/README_CN.md:14 |
| TypeScript | @tencentdb-agent-memory/memory-sdk-ts-v2 | sdk/memory-core/typescript/package.json:2 | @tencentdb-agent-memory/memory-sdk-ts | typescript/README_CN.md:13 |
Python 侧那一行的原文命令是 pip install tencentdb-agent-memory-sdk-python（python/README_CN.md:14）。
两侧都是同一种差异：元数据里的包名末尾有 -v2，README 的安装命令没有。Python 侧 README 还专门在 :7 用引用块写了「发布包名：tencentdb-agent-memory-sdk-python」，TypeScript 侧 README_CN.md:1 的文档标题也是不带 -v2 的那个名字。
版本号那一格同样对不上。pyproject.toml:7 写的是 1.0.1-beta.1，而 python/README_CN.md:17、:297 两处本地 .whl 安装示例里的文件名带的版本是 0.1.0；TypeScript 侧 package.json:3 是 1.0.1-beta.1，typescript/README_CN.md:16 的本地 .tgz 文件名带的版本是 1.0.0。
按规矩，我只陈述这几处差异并标出位置，不推断哪一个「是对的」，也不猜为什么两处没同步。
有一点必须一起说清楚：两份 README 的安装命令上方都带着「（发布后）」这三个字（python/README_CN.md:13、typescript/README_CN.md:12）。我们没有联网核实过任何 registry，因此不知道这两个包在公开源上的发布状态。所以这一节的正确读法不是「照着装会装错」，而是「照着装之前，先自己确认一遍你要装的到底是哪个名字」。
判定动作很具体，不用启动任何服务：打开 sdk/memory-core/python/pyproject.toml 的第 6、7 行，和 sdk/memory-core/python/README_CN.md 的第 7、14、17 行，两两对照；TypeScript 侧对应 package.json 的第 2、3 行与 README_CN.md 的第 1、13、16 行。四个文件、十来行，一分钟能对完。
还得补一句前提：这两个 SDK 的版本号都还带 beta.1 后缀（pyproject.toml:7、package.json:3 都是 1.0.1-beta.1），项目主模块也处于 beta 阶段，包名、安装命令、接口签名都属于随版本变动的部分。下面所有引用的行号，都只对 feat/server_team 分支上的 97f9465 这一份快照成立。
二、SDK 本体：两侧都只有一个运行依赖
包名之外，这两个 SDK 的骨架其实很瘦。
Python 侧（sdk/memory-core/python/pyproject.toml）：构建后端 hatchling（:2-3），license 字段写 { text = "MIT" }（:10），requires-python 是 >=3.9（:11），运行依赖只有一个 httpx>=0.24.0（:13），wheel 打包目录 tencentdb_agent_memory（:19）。dev 依赖是 pytest / pytest-asyncio / respx / build / python-dotenv（:16）。
TypeScript 侧（sdk/memory-core/typescript/package.json）：type: module（:5），exports 只暴露 . 与 ./v3 两个子路径（:8-17），engines.node 是 >=18.0.0（:29），运行依赖同样只有一个 undici ^6.21.3（:36），npm 发布内容含 dist/、src/、README.md（:26）。
模块布局上有一处设计值得单独指出来。Python 侧顶层 __init__.py:22 默认导出的 MemoryClient / AsyncMemoryClient 指向 v2，:5 的注释写明这是为了「老代码升级 SDK 后零修改即可继续工作」；要用 v3 得显式写 from tencentdb_agent_memory.v3 import MemoryClient（:6-7）。也就是说，光看 import 那一行，你分不出手上用的是 v2 还是 v3 路径——分辨点在导入语句的深度，不在类名。
三、session_id 到底必不必填，两侧文档说法不同
这是本篇第二处需要读者自己去核的地方。
Python 侧：python/README_CN.md:109 写「v3 与 v2 的主要差异：L0/L1 强制要求 session_id（strict session isolation）」，:195 的差异表进一步写「L0/L1 必填，缺失返回 422」，python/tencentdb_agent_memory/v3/__init__.py:3 也写「构造时必须提供 team_id / agent_id / user_id / session_id 四元组」。
TypeScript 侧：typescript/README_CN.md:26-30 写「构造时要求 teamId / agentId / userId 三元组」，sessionId 标为「可选」；typescript/src/v3/client.ts:111-118 的注释区分得更细——写路径 addConversation 要求 sessionId，读路径（query / search / count / delete）允许省略，L2/L3 是 team+agent 维度的 profile，不消费 sessionId。
一处说四元组必填，一处说三元组必填、第四个可选并按读写路径区分。两处位置都在上面了，以你实际用到的那一侧的源码注释为准；差异说到这里为止。
顺带一条同类的：python/README_CN.md:147-149 明写「删除路径不会回退到构造时的 session_id」，批量约束也写在同一节（:134-149）——L0 按 message_ids 批删 ≤5000、按 session_ids 批清 ≤100、L1 按 id 批删 ≤5000。这些是文档里给出的上限值，不是运行表现的承诺。
四、文档没覆盖到的那块
三个静态统计摆在这儿，都是可以自己复现的：
其一，SkillClient 在 SDK 文档里几乎不出现。sdk/memory-core/python/tencentdb_agent_memory/v3/__init__.py:10-12 导出了 SkillClient / AsyncSkillClient，自述封装 14 条 /v3/skill/* 接口，pyproject.toml:8 的 description 也写着 incl. /v3/skill/*。而我们对五份文档做 grep -c -i skill：python/README_CN.md、python/README.md、typescript/README_CN.md、两份 AGENT_GUIDE.*.zh-CN.md 全部为 0；只有 typescript/README.md 命中 1 行，另有两份 CHANGELOG 里有记录。而这个类本身方法不少，v3/skill_client.py 里 class SkillClient 起于 :151，公开方法从 create(203) 一路排到 close(578)。
其二，sdk/ 这个目录在根级文档里查不到。我们在 README_CN.md、README.md、INSTALL_CN.md、ROADMAP_CN.md、CHANGELOG.md 里 grep sdk/，命中 0 次；CHANGELOG.md:7-8 只在正文里提了一句「覆盖仓库全部开源模块：MemoryCore / MemoryPanel / MemoryKnowledge / MemoryProxy / SDK」，没有给出路径。
其三，测试文件我们一个都没找到。git ls-files sdk | grep -i test 只命中 sdk/memory-core/typescript/vitest.config.ts 这一个配置文件，.test.ts 一个也没有。
五、ROADMAP 上的五项，逐条都是「接下来要做」
ROADMAP_CN.md 全文 107 行。开篇三句把边界划得很清楚：:3「本文档说明我们接下来要做什么。已经发布的内容请看 CHANGELOG.md」；:5「当前版本：v2.0.1-beta.1」；:7-9「路线图列出的是团队正在推进的工作，不是承诺，范围与时间可能调整」。
「下个版本 · v2.0.1」下的五项（:13-69），照原文摘：
| 序 | 标题 | 所属模块 | 现状原文摘要 |
|---|---|---|---|
| 1 | Agent 模版：管理员定义默认资产 | Memory Hub | 新建团队自带默认 Agent，但「默认 Agent 带什么资产是内置的，管理员无法按团队实际情况调整」（:15-26） |
| 2 | mem: 指令增强：围绕 Task 展开 | Memory Proxy | 「当前的 mem: 指令只有 sync / create-skill / help 三个」（:28-40） |
| 3 | 记忆可编辑：L1 - L3 支持修改 | Memory Hub | 「目前面板只能查看和删除，无法修正」（:42-53） |
| 4 | L0 / L1 记忆搜索 | Memory Hub | 当前提供的是「按时间范围过滤记忆列表」（:55-63） |
| 5 | Cursor 支持 | Memory Proxy | 新增 Cursor 适配，复用相同的记忆注入与回写链路（:65-69） |
这张表最有用的其实不是右边那列「要做什么」，而是括号里那些对当前状态的自述：面板上的 L1-L3 记忆现在只能看和删、不能改；记忆列表现在只有时间范围过滤、没有搜索。这些是路线图为了说明动机而写下的现状描述，比任何功能列表都直接。
已经发布的 mem: 会话指令是三个（:73-85，所属 Memory Proxy，自述「已随 v2.0.0 发布」）：mem:sync 刷新本次会话的全部资产注入（Skill / 记忆 / Knowledge / Task & Agent 描述）、mem:create-skill [提示词] 把本次对话归档为 Skill 并后台异步提取、mem:help 显示帮助。格式约定写在 :85：mem:<command>，冒号后不加空格，命令名大小写不敏感。
文末 :87-95 那段容易读岔。它问的是「你希望在对话里直接完成哪些操作？」，举的三个例子——查看当前注入了什么、临时禁用某个资产、把某段对话存成记忆——是征集意见时的举例，不是已实现的功能。:99-106 是「一起决定路线图」，写 Issues「24 小时内响应」，并说特别欢迎「新框架适配器」与「Memory Hub 的新用法」。英文版 ROADMAP.md（120 行）章节结构与中文版一一对应，五项分别起于 16 / 32 / 46 / 60 / 72 行。
六、路线图有两份，版本号有四个
还有两处需要读者知道，同样只陈述、不延伸。
路线图摘要有两份，内容不重合。 根 README_CN.md:299 写：「当前版本 v2.0.0。下个版本（v2.0.1）的重点：零配置冷启动、更快的 Wiki 生成、用户 / 团队自定义 Prompt、Skill 导出，以及 Codex（IDE Plan 模式）接入。」而 ROADMAP_CN.md:5 写的当前版本是 v2.0.1-beta.1，:13-69 列的五项如上表。两份清单没有一项重合。另外 README_CN.md:287 与 :289 在同一个「相关文档」列表里两次链到 ./ROADMAP_CN.md，标签分别是「路线图」和「Roadmap」。
版本号在四个地方各不相同。 ROADMAP_CN.md:5 与 CHANGELOG.md:12 是 2.0.1-beta.1；MemoryPanel/package.json:3 与 MemoryPanel/web/package.json:3 是 0.1.0；两个 SDK 的 pyproject.toml:7 / package.json:3 是 1.0.1-beta.1；README_CN.md:299 是 v2.0.0。所以「这个项目现在是什么版本」这个问题，取决于你打开的是哪个文件。要在文章、工单或依赖声明里写版本号，请写明你指的是哪一个文件里的哪一行。
七、这一篇能带走的
看 SDK 时值得固化成动作的，就三件：
- 包名以元数据文件为准，安装命令以 registry 实际存在的名字为准，两者不一致时不要凭 README 决定敲什么——先各自核一遍。这个仓库里，
pyproject.toml:6和README_CN.md:14就是这么一对。 - 文档没写的能力，未必不存在。
SkillClient在 README 里 grep 不到，但它在v3/__init__.py:10-12里导出着。反过来同理：文档写了的目录、端点、脚本，也未必在仓库里。 - 路线图当现状读，比当承诺读有用。
ROADMAP_CN.md:7自己就写了「不是承诺」，而它为解释动机写下的那些现状句——只能查看和删除、只有时间范围过滤、只有三个mem:指令——才是当下能对齐预期的部分。
最后再提醒一次这些数字的保质期：主模块处于 beta 阶段，另外三个模块的 package.json 版本还是 0.1.0，仓库最后一次 push 是 2026-08-15，我们次日取的快照。行号、版本号、包名都可能已经变了，上面每一处我都给了文件与行号，是为了让你能自己去仓库里再核一遍，而不是让你把它们抄进配置。
延伸阅读
- 从头读起：TencentDB Agent Memory 是什么：团队级 Agent 记忆中枢怎么读
- 本专题共 40 篇，完整分组目录见专题页
- TencentDB Agent Memory 的两个路由守卫：八条路由一处没接线
- TencentDB Agent Memory 的接口条数：面板 55、SDK 54、OpenAPI 54
本文依据 TencentDB Agent Memory 官方仓库（github.com/TencentCloud/TencentDB-Agent-Memory）
feat/server_team 分支上的 README、INSTALL、CHANGELOG、ROADMAP 与四个模块的源码整理，
核对日 2026-08-16，对应仓库快照 97f9465。该仓库的默认分支即为 feat/server_team。
本文内容为仓库源码与文档口径，我们没有部署、也没有运行过该项目的任何一个模块，
因此不涉及运行效果、检索质量与性能的任何描述。
该项目主模块处于 beta 阶段、其余模块版本号仍为 0.1.0，参数与接口随版本变动，请以仓库最新内容为准。
该项目会采集并存储团队的对话、文档与代码，属于敏感数据，是否使用请结合自身合规要求评估。
许可条款请以官方 LICENSE 原文为准，本文不构成法律意见。
安全与合规相关做法请结合自身环境评估，本文不构成安全方案建议。