TencentDB Agent Memory 插件侧：3 个 tool、2 个 hook 与注册入口

2026-08-16

看 TencentDB Agent Memory 这个仓库，很容易只盯着 Gateway 那一侧——一个监听 8420 的 HTTP 服务，几十条 /v3/* 路由，读起来像个后端项目。但 MemoryCore/package.json 的 description 原文第一个词就是 Four-layer local memory system plugin for OpenClaw，它首先把自己定义成一个宿主插件。那么问题就具体了：当它被 OpenClaw 加载进同一个进程，它到底往宿主里塞了什么？

这篇只回答这一个问题，沿着 MemoryCore/index.ts 的调用点走一遍。先把口径说清楚：以下全部来自 feat/server_team 分支上快照 97f9465 的源码与配置文件，核对日 2026-08-16。该分支就是这个仓库的默认分支，不是 main。MemoryCore/package.json 里的 version 是 2.0.0-beta.1，同仓另外三个模块还停在 0.1.0，接口与字段随版本变动。我们没有 npm install、没有 build、没有启动过任何进程，下面出现的所有数字都是文件里写着的，不是运行结果。

三处 registerTool，三个工具名

index.ts 共 1,034 行，里面有三处 api.registerTool(：index.ts:379、index.ts:466、index.ts:619。与之对应的工具名字不在 index.ts 里，而是声明在 MemoryCore/openclaw.plugin.json:10 的 contracts.tools 字段上，三个：tdai_memory_search、tdai_conversation_search、tdai_read_cos。

这三个名字值得记一下，它们是这份插件声明要向宿主注册的工具名。前两个从名字上分别对着记忆检索与会话检索，第三个 tdai_read_cos 的名字里带 cos。顺带一个可以直接对照的位置：MemoryCore/SKILL.md:166-167 给出的冒烟验收动作是调用 tdai_memory_search 与 tdai_conversation_search 两个工具，tdai_read_cos 不在这份冒烟清单里。这只是两处文件写的内容不同，我们不去推断为什么。

紧挨着前两处 registerTool 的位置还各有一行相同的 TODO 注释，index.ts:377 与 index.ts:465 原文都是 // TODO: implement hard per-turn call limit via before_tool_call hook + execute early-return (方案 D)。也就是说，按回合的硬性调用次数上限，在这份快照里还写着 TODO，不是已经具备的能力。写文章的人容易把这类注释跳过去，但它恰恰是判断某个能力到底有没有落地的直接依据。

两处 api.on：一进一出

卡在会话生命周期上的挂钩，我们核到的是两处：

api.on("before_prompt_build", ...)，index.ts:681
api.on("agent_end", ...)，index.ts:808

从名字看，一处在提示词组装之前、一处在 agent 回合结束之后，正好是”注入”与”采集”两个方向。这个形状在同仓的另一套插件里写得更直白：openclaw-plugin/docs/architecture.md:39-40 记录的映射是，agent_end 钩子调 client.addConversation()，before_prompt_build 钩子并行调 client.searchAtomic()、client.readCore()、client.listScenarios() 三个客户端方法。

这里有必要把一件事说明白，而不是绕过去：agent_end 这条路径的作用就是把对话内容送进记忆系统。MemoryCore/SKILL-DIAGNOSTIC-EXPORT.md:57-63 的导出包隐私风险表里，memory-tdai/ 那一栏标的是”高”，理由原文写的是”包含用户对话原文”。也就是说这个插件在宿主里挂上钩子之后，会采集并存储团队的对话内容，这属于敏感数据，用不用要按自己的合规要求判断。

两个注册入口：CLI 与 Context Engine

除了 tool 和 hook，index.ts 还有另外两类往宿主里注册东西的调用。

第一个是 CLI。 api.registerCli(...) 出现在 index.ts:160 与 index.ts:1017 两处，注册的子命令空间是 memory-tdai。命令描述的原文（index.ts:164）是 memory-tdai plugin commands (seed, query, stats)，字面上是三个子命令。而实际注册的地方在 src/cli/index.ts:56，只调了 registerSeedCommand(program, ctx)；紧接着的 :58-59 是两行注释：// Future: registerQueryCommand(program, ctx); 与 // Future: registerStatsCommand(program, ctx);。src/cli/commands/ 目录下也只有 seed.ts 一个文件。描述里写着三个、代码里注册了一个，两处的位置都在上面，差异到此为止。

seed 这一个子命令的参数在 src/cli/README.md:21-27 有完整记录：--input（必填）、--output-dir、--session-key、--config、--strict-round-role、--yes。它的输出目录结构写在同文件 143-153：conversations/、records/、scene_blocks/、vectors.db、.metadata/manifest.json、.metadata/checkpoint.json、.backup/。另外 src/cli/commands/seed.ts:123 有一行注释 // Checkpoint exists → resume scenario → P0 not implemented，:125 对应的用户可见报错文案是 Resume from checkpoint is not implemented in P0 yet.——断点续跑这条路在本快照里是明写未实现的，别按”跑挂了再续上”来规划用法。

第二个入口不在 index.ts，而在 src/offload-client/index.ts:66：

api.registerContextEngine("memory-tencentdb", () => engine)

它注册的是一个 Context Engine，注册用的 id 是字符串 "memory-tencentdb"。这条路径对应的是 offload 那一整套能力，而 openclaw.plugin.json:156-180 的 offload 段里，enabled 的默认值是 false。同一段配置里还有三个字段的描述以”【已废弃，请使用 mode=client】“开头：offload.backendUrl、backendApiKey、backendTimeoutMs（openclaw.plugin.json:176-178）。

宿主是怎么认出这个插件的

三处声明串起来：

MemoryCore/package.json:139-152 的 openclaw 段，extensions: ["./index.ts"]——入口就是那个 1,034 行的文件；同段还有 compat.pluginApi: >=2026.3.13、compat.minGatewayVersion: >=2026.3.13、build.openclawVersion: 2026.3.13、build.pluginSdkVersion: 2026.3.13、bundle.stageRuntimeDependencies: true。
MemoryCore/openclaw.plugin.json:2-8：id: memory-tencentdb、name: Memory (TencentDB)、commandAliases: ["memory-tdai"]、activation.onStartup: true。
package.json:127-130 的 peerDependencies：openclaw >=2026.3.7 与 node-llama-cpp ^3.16.2，两者在 peerDependenciesMeta 里都标了 optional: true（package.json:131-138）。

关于宿主版本门槛，三个位置写的数值不一样，都列在这里：peerDependencies 是 >=2026.3.7，openclaw 段的 compat.pluginApi 是 >=2026.3.13，SKILL.md:28-29 的环境预检门槛写的是 OpenClaw >= 2026.3.13、Node.js >= 22.16.0（Node 的门槛与 package.json:107 的 engines.node: >=22.16.0 一致）。三处数值不一致，位置都在上面，具体门槛以官方文档与宿主侧的实际校验为准。

还有一处安装期的差异值得在装之前先看一眼：package.json:48 的 postinstall 指向 scripts/openclaw-after-tool-call-messages.patch.sh（该路径同时出现在 package.json:73 的 files 里），而这个文件在我们采集的快照里不存在。这条命令原文带着 2>/dev/null || true，我们只陈述文件不存在这一个事实，不去推断它执行时会发生什么。

插件被宿主加载之后，数据落在哪里也由这条路径决定，和 standalone 那一侧不是同一条链。index.ts:276 写的是 const pluginDataDir = path.join(openclawStateDir, "memory-tdai");，其中 openclawStateDir 来自 resolveOpenClawStateDir()（src/utils/openclaw-state-dir.ts:27-34）：优先取 runtimeState.resolveStateDir()，否则取环境变量 OPENCLAW_STATE_DIR，再否则退回 ~/.openclaw。所以宿主模式下的数据目录取决于宿主返回什么，OpenClaw 本身不在这个仓库里，最终值我们核不出来。

还有一个到处都会碰到的细节：运行期的日志标签不是插件 id，而是 index.ts:55 写死的 const TAG = "[memory-tdai]";。SKILL-MIGRATION.md:165 专门为这件事加了一句说明，原文写”日志标签仍为 memory-tdai，这是正常的”。所以在日志里搜 memory-tencentdb 可能什么都搜不到，要搜 [memory-tdai]。

同一个仓里还有第二套插件

容易混的是，MemoryCore/openclaw-plugin/ 是另一个插件，15 个文件，入口 index.ts 289 行。它和上面那套的区别按文件核如下：

项	`MemoryCore/`（主插件）	`MemoryCore/openclaw-plugin/`
插件 id	`memory-tencentdb`（`openclaw.plugin.json:2`）	`memory-tencentdb-client`（`openclaw-plugin/openclaw.plugin.json:2`）
包名	`@tencentdb-agent-memory/memory-tencentdb-v2`（`package.json:2`）	同名（`openclaw-plugin/package.json:2`）
版本	`2.0.0-beta.1`	`1.0.0-beta.1`（`openclaw-plugin/package.json:3`）

两个 package.json 的 name 完全同名而版本不同，这两处的位置已经标在表里。

职责边界写在 openclaw-plugin/README.md:5：这一套是 Memory Gateway /v3/* 的客户端适配层，原文写它 does not run extraction, indexing, scene generation, or persona generation；README.md:13 那张表的 Not included 一栏写的是 Offload / Context Engine。换句话说，前面第二个注册入口那套东西，客户端插件这边是不带的。

它的配置 schema 在 openclaw-plugin/openclaw.plugin.json：server.{url,apiKey,instanceId,teamId,agentId,userId,rejectUnauthorized}，其中 teamId/agentId/userId 默认都是 default（:39-53），rejectUnauthorized 默认 true（:54-58）；recall.{maxResults:5, includePersona:true, includeSceneNav:true}（:61-80）；capture.enabled:true（:82-92）。

装它的脚本行为也写在 README 里（openclaw-plugin/README.md:74）：往 ~/.openclaw/openclaw.json 的 plugins.slots.memory 写 "memory-tencentdb-client"，并写入 server/recall/capture 三段。这里有一条版本硬门槛值得单独拎出来（README.md:107-108）：hooks.allowPromptInjection 与 hooks.allowConversationAccess 两个键仅在 OpenClaw >= 2026.4.24 时才写入，更早的版本会因为严格 schema 而 refuse to start。要装之前先确认宿主版本落在哪一侧。

一句话收束

把注册面摊开看，这个插件在宿主进程里的落点是四类：三处 api.registerTool（对应 tdai_memory_search / tdai_conversation_search / tdai_read_cos）、两处 api.on（before_prompt_build 与 agent_end）、一个 api.registerCli（memory-tdai 空间，目前只实到 seed）、一个 api.registerContextEngine("memory-tencentdb", ...)（对应默认关闭的 offload）。这四类之外的接入形态——HTTP Gateway 的那几十条路由、bin/ 下的独立命令、Hermes 那一侧的 Python 插件——是另外的话题，我们另有专门的篇目讲。

顺带说明一件本卡范围内核过的事：我们在 MemoryCore/ 全目录对 mcp 做了大小写不敏感检索，.ts/.json/.md/.yaml 全覆盖，命中 0 条。也就是说在这个目录范围内，我们没有找到任何 MCP server 或 MCP 工具注册的实现与文档。如果你是奔着”挂个 MCP 就能用”来的，这一层在 MemoryCore/ 里核不到。

延伸阅读

从头读起：TencentDB Agent Memory 是什么：团队级 Agent 记忆中枢怎么读
本专题共 40 篇，完整分组目录见专题页
TencentDB Agent Memory 的三份 SKILL 文档，与那个不存在的脚本
TencentDB Agent Memory 的测试现状：npm test 没有任何目标

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