TencentDB Agent Memory：从扁平向量堆到可追溯的分层记忆

先讲结论：Agent 的记忆，重点不是存得更多

当 AI Agent 从单轮问答走向长任务，记忆很快会变成效能瓶颈。搜寻结果、工具输出、错误堆叠、使用者偏好与过去对话全部留在上下文里，模型看似「知道更多」，实际上却要付出更高的 token 成本，还可能在大量互不相关的片段中迷失。

TencentCloud 开源的 TencentDB Agent Memory 提供了一个值得注意的解法：不要把所有内容扁平化后丢进向量资料库，而是把记忆拆成不同层级，让 Agent 先读取高密度的结构，再在需要时沿着识别码回查原始证据。

这个专案目前定位为 AI Agent 的团队记忆中枢，将对话、文件与程式码整理成可重用的记忆资产；它同时提供 OpenClaw 外挂，也支援 Hermes Agent。对正在建构多步骤 Agent、工具呼叫流程或长期个人助理的人来说，它的价值不在「再做一个聊天机器人」，而在于处理 Agent 工作流中最容易被低估的状态管理问题。

本文的效能数字与架构描述以专案 README 和官方文件为来源。README 中的 benchmark 是专案作者公布的结果，应视为专案报告，不等同于在你的资料集与模型上的保证。

为什么传统记忆方案会失控？

最直觉的做法是把每一段对话切成 chunk，产生 embedding，再放进向量资料库。使用者下次提问时，系统以相似度找回几段文字。这个流程对 FAQ 或短内容搜寻很实用，但对长时间运作的 Agent 有三个结构性问题。

第一，向量相似不等于工作关系。一段「上次部署失败」的错误记录，和一段「偏好使用 Docker」的使用者设定，可能都包含相似的技术词，却在任务中扮演完全不同的角色。只靠相似度，系统很难理解哪些是事实、哪些是场景、哪些是可重用的操作模式。

第二，上下文没有成本意识。工具输出可能有几十万个 token，但真正需要模型注意的往往只是「哪个步骤成功、哪个节点失败、下一步该怎么走」。把完整日志直接注入上下文，既浪费 token，也增加模型忽略关键资讯的机率。

第三，摘要常常不可逆。如果只把历史浓缩成一段摘要，之后发现摘要漏掉一个参数或错误原因，就很难知道它是怎么推导出来的，更不用说回到原始工具输出重新验证。

TencentDB Agent Memory 的设计，正是针对这三个问题：用分层取代扁平存储，用符号化取代冗长日志，并保留从高层结构回到原始证据的路径。

两条主轴：记忆分层与符号化记忆

1. 短期记忆：把工具日志移出上下文

在长任务中，短期记忆处理的是「目前这个任务发生了什么」。专案采用三层方式：

• 底层：把完整工具输出与原始文字写到外部档案，例如 refs/*.md，保存查证所需的细节。
• 中层：将每一步抽取成 jsonl 等结构化摘要，记录步骤、结果与关联。
• 顶层：用 Mermaid 图把任务状态浓缩成高密度的符号画布，只把这个轻量结构放进 Agent 上下文。

模型平常只需要读顶层图，就能掌握任务的主要节点；如果它需要核对一个错误讯息或某个工具回传值，再依照 node_id 去找回底层原文。这是「progressive disclosure」的实作：先给刚好足够的资讯，细节在需要时展开。

概念上可以想成下面的资料流：

graph LR
    A[完整工具输出] -->|保存原文| B[refs/*.md]
    A -->|抽取关系| C[Mermaid 符号画布]
    C -->|轻量注入| D[Agent 上下文]
    D -.->|依 node_id 回查| B

这个策略与单纯摘要最大的不同，是「压缩上下文」和「保存证据」同时成立。Agent 不必每一轮都携带完整日志，但系统也没有把原文丢掉。

2. 长期记忆：从对话逐层抽象成 Persona

跨工作阶段的记忆，处理的是「这个人、这个团队或这个专案长期有什么规律」。TencentDB Agent Memory 把长期个人化记忆设计成语意金字塔：

• L0 Conversation：原始对话。
• L1 Atom：从对话抽取出的原子事实，例如偏好、限制或已确认的决策。
• L2 Scenario：把多个事实组合成可理解的情境区块。
• L3 Persona：形成较稳定的使用者或团队轮廓。

上下层不是互相取代，而是各自负责不同的取用成本。Agent 平常可以先读 Persona 或 Scenario；当某个细节影响决策时，才往下钻取到 Atom 与 Conversation。这让「记得使用者偏好」不必等于「每次都重新载入所有历史对话」。

同样的分层概念也延伸到 Skill 生成：从底层执行纪录找出重复出现的解法，再逐步整理成 Scenario，最后沉淀成可重用的 Skill 或 SOP。对企业 Agent 来说，这比单纯保存聊天纪录更接近真正的知识运营。

可追溯性：为什么 `node_id` 很重要？

记忆系统最怕两件事：模型把错误摘要当真，以及工程师无法回答「这个结论从哪里来」。专案的做法是为高层符号保留回溯链：

Persona / Mermaid Canvas
        ↓
Scenario / jsonl index
        ↓
Atom / refs
        ↓
原始对话、工具输出与错误堆叠

在短期记忆中，Mermaid 画布上的节点带有 node_id。Agent 可以用图理解状态转移，程式则可以用同一个 ID 搜寻原始档案。这种设计把「模型可读的摘要」和「工程师可验证的证据」接在一起。

它不会自动消除幻觉，也不会保证每个抽取结果正确；但至少让错误调查有可操作的入口。当 Agent 说「部署在第三步失败，原因是权限不足」时，系统应该能带你回到对应的工具输出，而不是只能相信一段无来源的摘要。

实作方式：先用本地 SQLite 跑起来

目前官方 README 提供 OpenClaw 与 Hermes 两条整合路径。最容易验证概念的方式，是先在本机用 SQLite 加 sqlite-vec，不要一开始就把问题复杂化成远端资料库部署。

OpenClaw：外挂安装与零配置启用

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

接着在 OpenClaw 设定中启用外挂：

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

预设后端是本地 SQLite + sqlite-vec。启用后，外挂会在对话流程中处理对话撷取、记忆抽取、场景聚合、Persona 生成与下一轮回忆。若要测试短期上下文压缩，再加入 offload 设定，并把 contextEngine slot 指向 memory-tencentdb。

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

README 也提醒，较新的 OpenClaw 版本可能需要执行一次 after-tool-call-messages.patch.sh，让工具呼叫后的讯息能正确被 offload 与回收。这一步应该依你目前安装的版本与官方文件确认，不要盲目套用补丁。

Hermes：接到既有安装

如果你已经有 Hermes Agent，可以不使用专用 Docker 映像，直接安装外挂并把 provider 接到 Hermes 的 memory 设定。官方流程的核心步骤如下：

mkdir -p ~/.memory-tencentdb
cd ~/.memory-tencentdb
npm init -y --silent
npm install @tencentdb-agent-memory/memory-tencentdb@latest --omit=dev

接着把外挂放到统一目录，并连结到 Hermes 的 provider 目录：

rm -rf ~/.hermes/hermes-agent/plugins/memory/memory_tencentdb
ln -sf ~/.memory-tencentdb/tdai-memory-openclaw-plugin/hermes-plugin/memory/memory_tencentdb \\
  ~/.hermes/hermes-agent/plugins/memory/memory_tencentdb

这里有一个容易踩到的命名细节：资料夹必须叫 memory_tencentdb，使用底线；设定层可以使用 memory-tencentdb 这个别名，但 provider 目录不能改成连字号。

在 Hermes 设定中指定 provider：

memory:
  provider: memory_tencentdb

Gateway 需要一组启动命令与模型设定。请把 API key 放在环境变数或受控的 .env 档中，不要把凭证写进文章、Issue 或 shell history：

MEMORY_TENCENTDB_GATEWAY_HOST="127.0.0.1"
MEMORY_TENCENTDB_GATEWAY_PORT="8420"
TDAI_LLM_BASE_URL="https://your-openai-compatible-endpoint/v1"
TDAI_LLM_MODEL="your-model"
TDAI_LLM_API_KEY="your-api-key"

Gateway 可以手动启动，也可以让 provider 在第一次对话时自动侦测并启动。完成后先用 health endpoint 验证：

curl http://127.0.0.1:8420/health

预期会得到 status 为 ok 或 degraded 的 JSON。若是既有 Hermes 安装，建议先保留原本的 memory provider 设定档，逐步比较启用前后的上下文长度、延迟与错误率。

Docker：适合隔离测试或全新部署

如果你要从零建立一个带记忆的 Hermes，官方也提供 Docker 路径，Gateway 预设监听 8420，资料放在 named volume。这种方式的好处是依赖隔离、重建容易；代价是需要处理模型 API、volume 备份与网路暴露。

docker build -f Dockerfile.hermes -t hermes-memory .
docker run -d \\
  --name hermes-memory \\
  --restart unless-stopped \\
  -p 8420:8420 \\
  -e MODEL_API_KEY="your-api-key" \\
  -v hermes_data:/opt/data \\
  hermes-memory
curl http://localhost:8420/health

这段范例中的 key 只是占位符。正式部署时应改用 secret manager、受限权限的环境档或平台提供的 secret 注入，不要把真正的金钥提交到 Git。

专案报告的 benchmark，应该怎么读？

README 公布了与 OpenClaw 整合后的几组结果：在 WideSearch 上，成功率由 33% 提升到 50%，token 使用量由 221.31M 降到 85.64M；在 SWE-bench 上，成功率由 58.4% 到 64.2%，token 使用量由 3474.1M 降到 2375.4M；PersonaMem 则由 48% 到 76%。

这些数字很吸引人，但正确的解读方式是「专案作者在特定环境下量测到的改善」，而不是「安装后一定减少 61.38% token」。实际结果会受到模型版本、上下文策略、工具数量、任务长度、资料分布与抽取成本影响。

如果要在自己的环境验证，建议固定以下变数：

1. 相同模型与 temperature。

1. 相同任务集合与工具可用性。

1. 相同的最大上下文与重试策略。

1. 分别记录总 token、每轮延迟、工具成功率与最终任务完成率。

1. 对记忆抽取错误做人工抽样，不只看成本下降。

尤其要注意，记忆系统本身也会消耗模型呼叫与储存空间。真正有价值的指标不是单独的 token 数，而是「完成同一批任务所需的总成本，以及结果是否更可重现」。

适合哪些场景？

适合：

• 需要连续执行多个工具步骤的研究、开发与自动化 Agent。
• 会反复使用相同 SOP、专案背景与团队规范的工作流。
• 想让不同 Agent 或不同工作阶段共享可治理记忆的团队。
• 需要在节省上下文成本的同时，保留错误调查与证据回溯能力的系统。
• 已经使用 OpenClaw 或 Hermes，想以 provider／plugin 方式增强记忆，而不是重写整个 Agent。

不一定适合：

• 只有几轮对话、没有跨工作阶段状态的简单 chatbot。
• 只想做一次性的语意搜寻，且不需要场景、Persona 或工具链回溯。
• 目前还没有能力监控资料保留、权限与模型抽取品质的团队。

另外，任何保存使用者偏好、对话与工具输出的系统，都必须先定义资料边界。哪些内容可以长期保存？谁能查询？如何删除？如何处理敏感资讯？分层架构解决的是检索与成本问题，不会自动替你完成治理。

实务评估清单

如果你要把它放进既有 Agent，建议按照下面顺序试：

第一步：只启用长期记忆

先用本地 SQLite，建立几个可重现的对话情境，例如「使用者偏好的输出格式」、「专案部署规则」与「常见错误修复」。确认下一个工作阶段真的能正确召回，再考虑短期 offload。

第二步：加入短期压缩

挑一个工具输出很长的任务，量测上下文大小与最终成功率。检查 Agent 是否能从 Mermaid 画布找到正确 node_id，并且能在需要时回到 refs 读到完整原文。

第三步：测试失败与降级

刻意让 Gateway 暂时不可用，观察主 Agent 是报错、跳过记忆，还是卡住整个任务。记忆通常是辅助能力，不能让一个资料库或 Gateway 故障拖垮核心对话。

第四步：再决定是否集中式部署

单机验证通过后，才评估团队共享、备份、权限与高可用。把原始证据与高层 Markdown 资产分开备份，并为资料删除与保留期限建立明确流程。

结语：好的 Agent 记忆，应该同时「省」与「能查」

TencentDB Agent Memory 最值得看的地方，不是它宣称支援多少平台，而是它把 Agent 记忆重新定义成一个可分层、可压缩、可回溯的系统。短期记忆用符号化画布降低上下文负担，长期记忆用 Conversation → Atom → Scenario → Persona 建立抽象层，底层则保留能回查的原始证据。

这种设计也提醒我们：Agent 的「记得」不应该等于把全部历史塞回 prompt。真正可用的记忆，应该知道什么需要常驻、什么可以延后载入、什么必须保留原文，以及如何让人类在结果可疑时重新检查来源。

如果你正在做多步骤 Agent、长期工作流或团队级 AI 助理，这个专案很适合拿来当作记忆层的参考实作。最务实的起点不是直接相信 benchmark，而是用一个可重现的小型任务集，量测启用前后的 token、延迟、成功率与可追溯性，再决定它是否符合你的生产需求。

延伸阅读与来源

• TencentDB Agent Memory GitHub
• 官方 README：架构与 benchmark
• Hermes Agent
• OpenClaw