TencentDB Agent Memory

TencentDB Agent Memory 快速入门：给 Agent 装一层可以回查的记忆

这是什么？适合谁？

TencentDB Agent Memory 是腾讯云（GitHub 组织 TencentCloud）开源的 Agent 记忆中枢。它不是又一个聊天机器人，而是接在 Agent 与模型之间的一层记忆插件：把工具日志压成符号、把对话蒸馏成人物画像与场景，再在下一轮对话开始前把相关记忆注入上下文。

官方把设计拆成两条主线（依据 README）：

• 符号化短期记忆：把冗长的工具输出与日志压缩成 Mermaid 画布，模型只读顶层结构，需要细节时再按 node_id 下钻。
• 分层长期记忆：L0 原始对话 → L1 原子事实 → L2 场景 → 人物画像（persona），而不是把所有片段塞进一个扁平向量库。

它发布在 npm 上（@tencentdb-agent-memory/memory-tencentdb），当前 README 给出两条宿主路线：OpenClaw 插件与 Hermes（Docker 或接入既有安装）。默认存储后端是本机 SQLite + sqlite-vec，也就是默认不需要单独的向量数据库服务。

适合谁：正在跑 OpenClaw 或 Hermes 这类长期会话 Agent、被「上下文越聊越贵、越聊越忘」折磨的开发者；需要跨会话保留项目约定、输出格式、SOP 的团队；愿意自己管理数据目录与模型 Key 的自托管用户。

不适合谁：只做一次性问答的场景（引入记忆层只会多一次抽取成本）；不愿升级 Node、不想配插件目录的环境；希望开箱即得云端托管服务、完全不想碰本机文件的用户——这类需求应该去看托管型产品，而不是自己装插件。

核验日期：2026-10-28。功能与参数依据官方文档站与仓库 README，本文未在本机安装运行。

准备工作

• Node.js ≥ 22.16（README 顶部徽章与包要求；低版本会直接卡在安装或运行阶段）。
• 一个宿主：OpenClaw ≥ 2026.3.13，或已安装的 Hermes Agent。
• 一个可用的模型调用凭据：记忆抽取（L1）、场景聚合（L2）、人物画像（L3）都要跑 LLM。README 的 Docker 路线默认指向腾讯云 LKE（https://api.lkeap.cloud.tencent.com/v1，默认模型 deepseek-v3.2），也可以换成任何 OpenAI 兼容端点。
• 一块用于持久化的磁盘目录：Docker 路线用命名卷 hermes_data:/opt/data；手工路线统一放在 ~/.memory-tencentdb。
• 时间预算：装插件与首轮跑通按小时计；真正让记忆「长出来」需要连续多轮会话，官方基准里的效果也是在长时连续会话下测的。

使用前提要讲清楚：README 里的基准数字（token 下降 61.38%、WideSearch 通过率 33%→50%、SWE-bench 58.4%→64.2%、PersonaMem 48%→76%）是项目方自己发布的测量结果，条件是「连续长时会话」——例如 SWE-bench 每个 session 连跑 50 个任务来模拟上下文累积。这些数字说明方向，不代表你自己仓库里的账单会等比例下降。

安装与启用

路线一：OpenClaw 插件（最短路径）

openclaw plugins install @tencentdb-agent-memory/memory-tencentdb
openclaw gateway restart

然后在 ~/.openclaw/openclaw.json 里打开开关（README 说明默认零配置即可用）：

{
  "memory-tencentdb": {
    "enabled": true
  }
}

启用后，会话捕获、记忆抽取、场景聚合、人物画像生成以及「下一轮之前的召回」都由插件接管，不需要自己写调用代码。

升级请用宿主自己的命令 openclaw plugins update @tencentdb-agent-memory/memory-tencentdb。README 明确提醒：用语义化版本范围去升级会让插件被禁用，这一点和普通 npm 依赖的习惯不同。

路线二：Hermes + Docker（从零起一套带记忆的网关）

README 的 Docker 路线要求版本 ≥ 0.3.4，镜像里已经把 hermes-agent 与 memory_tencentdb 一起打包，网关监听 :8420：

cd docker/opensource
docker build -f Dockerfile.hermes -t hermes-memory .
docker run -d \
  --name hermes-memory \
  --restart unless-stopped \
  -p 8420:8420 \
  -e MODEL_API_KEY="你的 Key" \
  -e MODEL_BASE_URL="https://api.lkeap.cloud.tencent.com/v1" \
  -e MODEL_NAME="deepseek-v3.2" \
  -e MODEL_PROVIDER="custom" \
  -v hermes_data:/opt/data \
  hermes-memory
curl http://localhost:8420/health

如果就用默认的 DeepSeek-V3.2，可以只传 MODEL_API_KEY，其余三个变量省略。-v hermes_data:/opt/data 这一行不是可选项：去掉它，容器一重启记忆就没了。

路线三：接入既有的 Hermes（不装 Docker）

README 的 2.B 节给出的思路是把 npm 包安装到一个统一目录（~/.memory-tencentdb），再把包目录放进 Hermes 的插件位置。安装时用 npm install @tencentdb-agent-memory/memory-tencentdb@latest --omit=dev，然后按文档把它复制到插件目录。这条路线适合本机已经有一套 Hermes、不想为记忆能力再起一个容器的人。

三条路线都指向同一个判据：装完之后 memory_tencentdb 这个 provider 必须真的被宿主加载。只在 package.json 里看到依赖，不等于宿主已经启用它。

首个任务：让 Agent 记住一条项目约定，再在新会话里回查

准备一条足够具体、容易被复述错的信息，例如：

本项目所有对外文档的日期格式统一写成 2026-10-28 这种形式，不要写 10/28/2026。
所有命令示例一律给出可复制的一行，不要把参数拆成多行。

按顺序做四步：

1. 在已启用记忆的宿主里，把上面这段当作正常对话说一遍，不要用斜杠命令跳过正常消息通道——记忆捕获走的是会话消息。
2. 继续正常聊几轮，触发 L1 抽取。默认 pipeline.everyNConversations = 5，也就是每 5 轮触发一次抽取；如果等不及，可以先做一次空闲等待，pipeline.l1IdleTimeoutSeconds 默认为 600 秒。
3. 用 recall 配置的默认策略（hybrid，关键词与向量 RRF 融合，每次返回 5 条）观察是否能召回这条约定。
4. 开一个新会话再问一句与日期格式相关的问题，看回答是否自动带上这条约定。

成功判据有三条，缺一条都不算跑通：

• 新会话的回答体现了这条约定，而不是重新问你一遍；
• 能在数据目录里找到对应的 L0/L1 记录（默认在本地 SQLite 与 L1 文件目录内）；
• 需要细节时能从顶层摘要下钻到底层证据，而不是只能看到一段不可追溯的总结。

如果第 4 步失败，先别改配置乱试：确认模型 Key 是否可用（抽取调用失败时记忆压根没写进去）、确认采样轮数是否达到触发阈值、再确认召回没有超时被跳过（recall.timeoutMs 默认 5000 毫秒，超时是「跳过注入而不阻塞对话」，所以表现就是「什么都没发生」）。

初级用法

先用默认参数跑通，再逐层调。README 明确写了「每个字段都有默认值，零配置即可运行」，这句话的正确用法是：先接受默认值，确认记忆能写进去、能召回，之后才动 Level 1 的那几个开关。

日常最常改的四个参数：

• recall.maxResults（默认 5）：每次召回几条。条数越多上下文越贵，先别急着加。
• pipeline.everyNConversations（默认 5）：多少轮抽取一次。调小更「记得住」，也更费模型调用。
• persona.triggerEveryN（默认 50）：每新增多少条记忆重算一次人物画像。
• offload.enabled（默认 false）：短期压缩开关，按需打开，见下一节。

判断要不要开短期压缩看两个信号：长任务里工具输出把上下文顶满；或者模型开始「忘记」几步之前刚做过的事。只看 token 账单就开压缩是错的顺序——压缩的价值是可回查地省 token，不是单纯省。

还有一个容易被忽略的日常动作：capture.excludeAgents 可以用 glob 排除特定 Agent（例如评测用的 bench-judge-*）。评测流量混进长期记忆，会让人物画像被无关样本污染。

高级玩法

1. 打开符号化短期压缩（offload）

短期压缩需要版本 ≥ 0.3.4，并且要在两处配置：先在插件配置里打开 offload.enabled，再把 contextEngine 这个 slot 指给插件。

{
  "memory-tencentdb": {
    "enabled": true,
    "config": { "offload": { "enabled": true } }
  },
  "plugins": {
    "slots": { "contextEngine": "memory-tencentdb" }
  }
}

OpenClaw 路线还需要跑一次仓库里的补丁脚本 bash scripts/openclaw-after-tool-call-messages.patch.sh，它把 after-tool-call 消息挂上，让工具输出能被卸载与恢复。README 说明补丁每次安装只需打一次，但升级 OpenClaw 之后要重跑——这是这套方案里最容易漏的一步。

压缩的两个触发比例是 offload.mildOffloadRatio（默认 0.5）与 offload.aggressiveCompressRatio（默认 0.85），注入给模型的 Mermaid 画布有独立的 token 预算比例 offload.mmdMaxTokenRatio（默认 0.2）。调这三个值之前先跑一段真实长任务，看你到底是「温和压缩太早」还是「激进压缩太晚」。

2. 分层召回：先看画像，再下钻事实

长期记忆的价值在层级，不在条数。推荐的工作方式是：先读人物画像与场景摘要建立宏观判断，发现对不上再按 node_id 下钻到原子事实，最后落到 L0 原始对话。

这条链路正好对应 README 讲的「保留从高层抽象回到地面证据的清晰路径」。如果你的用法是「召回 5 条就直接塞进 prompt、从不回查」，那等于只用了向量库的检索能力，把分层设计浪费掉了。

3. 换掉默认模型与向量后端

两层都可以换：

• LLM 层：Docker 路线换 MODEL_BASE_URL / MODEL_NAME / MODEL_PROVIDER；或者用 llm.* 配置走独立模型，绕开宿主内置模型，专门跑 L1/L2/L3。
• 向量层：embedding.* 支持 OpenAI 兼容的远程 embedding 服务。自建 bge-m3 这类模型时，必须把 embedding.sendDimensions 设为 false——README 写得很直白：部分自托管模型不支持 Matryoshka 表示，带上 dimensions 字段会直接返回 HTTP 400 does not support matryoshka representation。

中文场景还可以显式确认 bm25.language（默认 zh，用 jieba 分词）。做英文语料为主的团队应该改成 en，否则关键词召回那一路会被中文分词器拖累。

五个小技巧

1. 先用默认参数跑通「写入 → 召回」闭环，再动 everyNConversations 与 recall.maxResults。
2. 用 Docker 时把 -v hermes_data:/opt/data 固定写进启动脚本，别靠「上次那条命令我还记得」。
3. 每升级一次 OpenClaw，就重跑一次 openclaw-after-tool-call-messages.patch.sh 并验证压缩仍然生效。
4. 评测、压测、临时脚本这类 Agent 流量用 capture.excludeAgents 排除，别污染长期画像。
5. 先把 recall.timeoutMs 的默认 5 秒理解成「超时就静默跳过」，排查「记忆没生效」时优先看这一项。

常见踩坑

以下为基于官方文档与 README 限制整理的排障思路，不是本站亲历记录。

坑 1：Node 版本不够，装完就报错

症状：plugins install 或宿主启动时直接失败。原因：README 的徽章要求 Node ≥ 22.16，低版本缺新 API。解决：升级 Node 后重装插件，不要试图改包内代码绕过版本要求。

坑 2：升级 OpenClaw 之后压缩「悄悄失效」

症状：短期压缩开着，但工具输出又开始原样堆进上下文。原因：after-tool-call 的运行时补丁被宿主升级覆盖。解决：重跑 scripts/openclaw-after-tool-call-messages.patch.sh；README 明确说明升级后需要重新应用。

坑 3：只打开了 offload，却没注册 contextEngine slot

症状：offload.enabled 为 true，压缩就是不触发。原因：宿主需要 plugins.slots.contextEngine 指向 memory-tencentdb 才会把上下文卸载请求路由过来。解决：补上 slot 配置并重启网关，两处缺一不可。

坑 4：自建 embedding 一直报 400

症状：接 bge-m3 等自托管模型时请求被拒，报 does not support matryoshka representation。原因：请求体里带了 dimensions 字段。解决：把 embedding.sendDimensions 设为 false；OpenAI 的 text-embedding-3-* 才依赖这个字段做维度截断。

坑 5：把官方基准当成自己环境的预期值

症状：上线后账单没降 61%，或评测通过率没动。原因：官方数字来自长时连续会话的特定设置（例如 SWE-bench 每个 session 连跑 50 个任务），与日常零散对话不是一回事。解决：先用自己的一批真实长任务做前后对照，再决定是否继续加压缩比例。

坑 6：容器重建后记忆消失

症状：docker rm 重建容器后，之前的对话与画像全没了。原因：没有挂持久化卷。解决：确保 -v hermes_data:/opt/data，并把数据目录纳入你自己的备份策略；capture.l0l1RetentionDays 为 0 表示永不清理，别误以为它在做归档。

常见问题 FAQ

Q1：这套东西要钱吗？

A：插件本身是 MIT 开源，代码免费（LICENSE）。真正的成本在模型调用：L1/L2/L3 抽取与召回都要跑 LLM，用腾讯云 LKE 或你自己的 OpenAI 兼容端点按各自计费。官方的价值主张是「省 token」，但省下来的和抽取花出去的要在你的场景里实测对比。

Q2：默认会把对话传到云端吗？

A：默认存储是本机 SQLite + sqlite-vec，记忆数据落在本地。但记忆抽取要调用模型，这一步默认指向腾讯云 LKE 端点；如果你配置了远程 embedding.* 或 offload.backendUrl，数据还会流向那些服务。要全本地，就把 MODEL_BASE_URL、embedding.baseUrl、llm.* 全部指向自建端点。

Q3：和 Mem0、Zep 这类记忆层有什么不同？

A：取向不同。Mem0 走的是「提取事实 + 检索」的通用记忆层路线，生态与接入方式多；Zep 强调时序知识图谱（Graphiti）。TencentDB Agent Memory 的特点是分层 + 符号化：短期把日志压成 Mermaid 画布并按 node_id 下钻，长期用 L0→L1→L2→画像的语义金字塔。选哪个取决于你要的是「通用记忆 API」还是「长任务上下文治理」。

Q4：支持哪些宿主？

A：README 当前给出 OpenClaw（≥2026.3.13）与 Hermes 两条主线，Hermes 又分 Docker 与接入既有安装两种方式。别的框架需要自己写适配；不要假设「兼容 OpenAI 接口」就等于兼容任意 Agent 框架。

Q5：中文场景需要额外配置吗？

A：关键词召回那一路用 BM25，bm25.language 默认 zh 并走 jieba 分词，中文项目开箱即用；纯英文语料建议显式改成 en。语义召回那一路取决于你选的 embedding 模型对中文的支持。

Q6：记忆会不会越攒越大、越来越慢？

A：会，除非你管理它。capture.l0l1RetentionDays 默认 0（永不清理），pipeline.enableWarmup 会让新会话从第 1 轮就开始触发、之后 1→2→4 递增。长跑的部署要自己定留存策略，并把 L0/L1 目录纳入备份与清理计划。

Q7：能不能只给自己团队用、不暴露到公网？

A：可以，这也是默认形态：本机 SQLite、插件在宿主进程内运行。若要给多人共用，README 另有 Gateway Security 一节（可选），需要自己处理鉴权与网络边界，不要把 8420 直接开到公网。

成本、权限与安全边界

许可：MIT（LICENSE），商用不受限，但模型、embedding 服务与基础设施的钱另算。

记忆层天然会保存个人信息：对话原文（L0）、原子事实（L1）、场景与人物画像（L3）都可能包含客户资料、内部约定、凭据片段。三条底线建议写进部署文档：数据目录的访问权限按最小化配置；capture.excludeAgents 排除不该被记录的自动化流量；对外共享环境时先确认 report.*（指标上报）的开关状态。

另外要注意「压缩不等于脱敏」。符号化短期记忆保留了从摘要回查原始工具输出的路径，这意味着原始内容仍然在磁盘上。如果某类日志本来就不该留存，应该在写入前排除，而不是指望压缩把它「洗掉」。

进阶学习建议

想把这套东西用深，按三条线走，每条都有明确的官方入口：

• 参数线：把仓库里的 openclaw.plugin.json 当作唯一参数事实源，README 只列到 Level 2。重点读 embedding.*（远程向量）、llm.*（独立模型模式）、offload.backendUrl（把 L1/L1.5/L2/L4 流程卸载到后端服务）这三组。
• 基准线：按 README 的方法复现你自己的长会话基准——固定任务集、连续多轮、记录 token 与通过率，再和不开插件的结果对照。SWE-bench 那组数字之所以用 50 连跑，就是为了制造上下文累积压力；如果你只用单轮对话测，量不出任何差别。
• 回查线：练习从 Mermaid 画布的 node_id 下钻到 refs/*.md 与 jsonl 中间层。这条链路是它区别于「扁平向量记忆」的核心，也是排查「Agent 记错了」时唯一能落到证据的路径。

免责声明

本文基于官方文档和公开资料整理，AI辅助生成，MagicNetWorld 尚未完成独立实测。 文中安装命令、配置片段与基准数字均为文档示例或项目方自述，未在本站环境执行；不同宿主版本、模型与数据规模下的实际表现需要自行验证。

参考链接

• 官方文档站
• GitHub 仓库与 README
• npm 包 @tencentdb-agent-memory/memory-tencentdb
• MIT 许可文本
• 全量参数清单 openclaw.plugin.json