TencentDB Agent Memory 的数据模型：代码自述还在演示阶段

读一个还在 beta 阶段的仓库，最有信息量的往往不是 README，而是某个 domain 文件顶上那段没打算给外人看的注释。

我们在 TencentCloud/TencentDB-Agent-Memory 的 feat/server_team 分支上（这个仓库的默认分支就是 feat/server_team，不是 main 也不是 master），沿着「一个 Agent 怎么借用另一个 Agent 的记忆」这条线往下翻，翻到了 MemoryPanel/src/panel/domain/chat-memory-governance.ts。文件头的注释里有这么一段（:10-13 原文）：后端 schema 还没落 chat_memory_rel 真字段，演示阶段把它塞进 Agent.metadata_json 的 "chat_memory" namespace，与前端共用同一份契约；后端补字段后，把 readChatMemoryRel / writeChatMemoryRel 的实现切到真字段即可。

这句话本身没什么惊悚的地方，工程里临时借一个 JSON 列过渡是常见做法。值得写一篇的，是它把「哪些东西已经定型、哪些东西还会挪窝」这条线画得很清楚——而这条线，恰恰是你决定要不要现在就往这个项目上压业务时最需要知道的。

先看这条关系到底长什么样

chat-memory-governance.ts 这个文件不长，但它是 Chat Memory 这类资产的归属与共享模型的唯一定义处。文件头另一句注释写得也很直接：跟 skill / wiki / code 不共用，因为每种资产的归属模型不同。

结构上只有三样东西：

• MAX_IMPORTED_AGENTS = 2（:16）——借入上限，一个 Agent 最多借入 2 个其他 Agent 的记忆。注释里说明这是 chat_memory 专属的常量，其他资产将来如有借入概念自行定义。
• ChatMemoryAgentRel 接口（:18-23）只有两个字段：memory_shared_with_team: boolean 和 imported_agent_ids: string[]。
• 默认值 { memory_shared_with_team: true, imported_agent_ids: [] }（:25-28）。

注意第一个字段旁边的注释（:20）：本期 UI 锁定 true。也就是说，这个字段在类型上是布尔，但按这句注释的口径，当前这一期它被锁定为 true。你如果只照着类型定义去设计上层逻辑，把它当成一个可自由切换的开关，会和注释写下的口径对不上。

校验规则在 validateImportedAgents（:33-52），一共五条，逐条都在代码里：必须是数组；数量不超过 MAX_IMPORTED_AGENTS；不能借入自己；被借入的 agent 必须在同一个 team 中；列表内不能重复。注释写明这份校验是前端、后端共用的。

持久化的落点是 METADATA_NS = 'chat_memory'（:54），读写各一个函数：readChatMemoryRel（:62）与 writeChatMemoryRel（:77）。

把上面这几行连起来看，这个设计是把「不确定会不会变」的部分收在了两个函数背后：校验规则、上限常量、字段形状都是显式定义的，存储位置则被 read/write 这一对函数包住。注释里那句「切到真字段即可」，说的就是这层包装的作用。这属于架构选择，效果如何我们没有依据评价。

「演示阶段」这个词在这个仓库里不止一处

翻到这里我们做了件顺手的事：把仓库里同一类自述都找出来，看看范围有多大。截至 2026-08-16 的快照 97f9465，在 MemoryPanel 这一层能核到的有这些。

前端有五个明确自述为演示阶段的 localStorage store，共用底座 MemoryPanel/web/src/services/storage-utils.ts，其 :12-13 原文写「这些 store 均为前端演示阶段的 localStorage 实现，后端上线后整批替换为 fetch 即可」：

文件	localStorage key	自述要点
account-store.ts	tdai-memory.accounts.v1	「演示阶段的本地账号表」，种子账号已清空为 []
agent-template-store.ts	tdai-memory.agentTemplates.v1	内置模板不落库
asset-scope-store.ts	tdai-memory.assetScopes.v1	「后端上线后换成一张 asset_acl 表即可」
user-asset-store.ts	tdai-memory.userAssets.v1	全部资产已切到真实后端 API，本文件仅保留读写能力
user-profile-store.ts	见 storage-utils.ts:4-5 的清单	—

后端也有一处同性质的临时态：MemoryPanel/src/panel/state/knowledge-task-registry.ts 把 owner_user_key 暂存在进程内存里（字段定义 :20），TTL 默认 1 小时（:25）；文件头注释自述「本期临时方案，下期持久化」，并写明「进程重启会丢任务——已知 corner，由前端 register-meta 兜底补建」（:2、:10-11）。

还有几处标着「本期 / 一期 / 暂未开放」的边界：

• MemoryPanel/web/src/lib/api/base.ts:22-24 有 export const PANEL_CAPABILITIES = { assets: false } as const;，:18-20 的注释说明为 false 时应展示「暂未开放」占位，不要发起注定 501 的请求。
• MemoryPanel/src/panel/api/meta-actions.ts:86-92 写 agent-fixed-asset/* 前缀「仍暂不开放」；对应到 meta/proxy.ts:149-151，命中 NOT_IN_SCOPE_PREFIXES 会返回 501 NOT_IN_SCOPE。
• MemoryPanel/web/src/pages/workbench/WorkbenchPage/components/workbench-utils.ts:13 写「Task 状态在演示阶段简化为二态：进行中 / 已完成」。
• MemoryPanel/web/src/pages/team/components/TeamManagementPanel.tsx:15-16 写 Agent owner 暂不支持转交、Team 删除接口后端尚未稳定支持。

这些都是仓库自己写在代码里的话，我们照抄，不加解释。配置里出现一个字段、注释里提到一项能力，跟它现在能不能用是两回事——这是读任何 beta 仓库都得自己守住的一条。

同一件事在不同层的口径不一致，怎么写进你自己的笔记

围绕 Chat Memory 的可见性，我们在同一个快照里数到三种口径，位置都能指到：

• 后端 knowledge 侧 MemoryPanel/src/panel/http/routes/knowledge/allocate-routes.ts:47 的 VALID_VISIBILITY 是 5 种：private / team / restricted / agent / task；前端类型 MemoryPanel/web/src/lib/api/types.ts:74 同样是这 5 种。
• 根 README_CN.md:230-235 的可见性表只列 4 种，没有 task。
• Chat Memory 这条线上的前端只暴露二元 scope：MemoryPanel/web/src/lib/api/chat-memory.ts:140 的 patchScope(blockId, scope: 'team' | 'private')；前端服务层 asset-scope-store.ts:24 的 AssetConfigScope 也是 'team' | 'private' 两值。

三处不一致，我们只陈述差异、标明位置，不推断哪个是对的，也不去解释为什么。以我们实读的仓库状态为准，写进笔记时把三处位置一并记上，比记一个结论有用得多。

这一点和前面那条「借入」的数据模型是有关联的：MemoryPanel/src/panel/http/routes/chat-memory.ts:1999-2036 的 authorizeChatMemoryRead 是三选一放行——资产 owner 是自己；或者 visibility === "team" 且调用方是该 team 成员；或者该资产已绑定到调用方名下某个 agent（也就是「借入」这条路径，实现是遍历调用方在该 team 下的 active agent 逐个查 agent-fixed-asset/list，:2010-2031），异常时 fallthrough 到 deny。换句话说，那份塞在 metadata_json 里的关系，是读权限判定里实打实用到的一环，不是一个纯展示用的字段。

你自己怎么核这一处

不用等谁给结论，下面几步都能自己走一遍（我们做的也是静态阅读，没有部署过任何一个模块）：

1. 先确认分支。这个仓库默认分支是 feat/server_team，任何按 main 拼出来的 raw 链接都会指错地方。
2. 打开 MemoryPanel/src/panel/domain/chat-memory-governance.ts，从文件头注释读到 METADATA_NS，前后不到 60 行，能把整个数据形状读完。
3. 在 MemoryPanel/ 下检索 metadata_json、readChatMemoryRel、writeChatMemoryRel，看这对函数被谁调用——这决定了「切到真字段」时的改动面。
4. 在 MemoryPanel/web/src/services/ 下检索 localStorage，对照 storage-utils.ts 的清单，把五个演示态 store 一次性圈出来。
5. 检索「演示阶段」「本期」「一期」「暂不」「TODO」这几个词，仓库里这类自述基本都能被捞出来。

判定的落点很简单：如果你关心的能力落在上述任一处自述里，那它现在的形态就有明确的变更预告；如果你检索这几步都没有命中，那说明它至少不在仓库自己标出来的临时清单上——这不等于它稳定，只是说仓库没在这处写下临时字样。

顺带一提两个容易写错的名字

写文档、写内部 wiki 的时候，这两处特别容易出错：目录叫 MemoryPanel，而 MemoryPanel/package.json:2 里的包名是 team-memory-control，前端包名（MemoryPanel/web/package.json:2）是 community-loop-lab-web；根 README_CN.md:131、:206 里对它的产品称呼又是「Memory Hub」。三层名字互不相同，写安装或部署说明时别把目录名当包名用。

版本号同样要注意：截至 2026-08-16，MemoryPanel/package.json:3 与 MemoryPanel/web/package.json:3 都是 0.1.0，而 CHANGELOG.md:12 与 ROADMAP_CN.md:5 写的是 2.0.1-beta.1。这是我们实读到的差异，同样只记录，不做推断。

最后回到那句注释。它把两件事写在了同一处：当前的持久化落点是 Agent.metadata_json，以及后端补字段后要改的是 readChatMemoryRel / writeChatMemoryRel 这两个函数。你要不要现在就基于这层做东西，取决于你能接受多大的变更面——项目自己在 ROADMAP_CN.md:7 也写了，路线图列出的是团队正在推进的工作，不是承诺，范围与时间可能调整。

延伸阅读

• 从头读起：TencentDB Agent Memory 是什么：团队级 Agent 记忆中枢怎么读
• 本专题共 40 篇，完整分组目录见专题页
• TencentDB Agent Memory 的接口条数：面板 55、SDK 54、OpenAPI 54
• TencentDB Agent Memory 的隐私边界：那个三选一的读取授权判定

---

本文依据 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，参数与接口随版本变动，请以仓库最新内容为准。 该项目会采集并存储团队的对话、文档与代码，属于敏感数据，是否使用请结合自身合规要求评估。 安全与合规相关做法请结合自身环境评估，本文不构成安全方案建议。