TencentDB Agent Memory：给 Hermes 加上分层记忆

开源AIHermes

Agent 的记忆问题，常见表现是两种：长任务里工具日志不断膨胀，跨会话后又丢掉项目背景、操作习惯和输出要求。TencentDB Agent Memory 试图用同一套分层模型处理这两类压力，并提供了 OpenClaw 插件和 Hermes Gateway 适配。

TencentDB Agent Memory 的 L0-L3 分层架构

L0 到 L3：记忆先保留证据，再生成结构

这套系统把长期记忆组织成四层。L0 Conversation 保存原始对话，是最接近事实的记录；L1 Atomic Memory 从对话中提取事实、偏好、约束和状态；L2 Scene Block 按项目、主题或工作流整理上下文；L3 Persona 承载相对稳定的用户偏好、表达风格和长期目标。

四层的作用不同：日常回答优先使用 L3 Persona 或 L2 Scenario，快速得到服务方向；遇到具体日期、项目细节或冲突信息，再向 L1 Atom 和 L0 Conversation 查询。上层文件保留结构，底层数据库和原始文件保留事实，检索范围因此可以按问题逐步收窄。

项目把关键中间产物放在可读文件中。L2 场景块使用 Markdown，L3 画像使用 persona.md，原始工具输出进入 refs/*.md，步骤摘要写入 JSONL。每条摘要都可以通过 node_id 或 result_ref 找到底层记录，调试时能沿着 Persona、Scenario、Atom、Conversation 这条链路定位召回错误。

长任务里的符号化记忆

跨会话记忆解决的是长期经验，长任务还需要处理当前上下文的体积。TencentDB Agent Memory 的 Context Offload 会把完整工具日志卸载到外部文件，再把步骤关系浓缩到 Mermaid 任务画布。Agent 在上下文中读取轻量结构，遇到疑问时沿 node_id 下钻，重新读取对应的原文。

官方示意中的数据路径分为三层：顶层是 Persona 或 Mermaid Canvas，中层是 Scene Blocks 和 JSONL Summaries，底层是 L0 原始对话与 refs 原文。顶层适合快速掌握结构，中层负责定位，底层用于核对细节。

TencentDB Agent Memory 的可检索与可恢复下钻链路

这套设计影响两个工程指标。上下文中只注入高层结构，可以减少重复日志带来的 Token 消耗；原文仍然留在外部存储，摘要不会成为无法解释的黑盒。代价也很具体：系统需要维护摘要、索引、文件和 LLM 提取流程，部署者需要为这些产物安排持久化目录与备份策略。

Hermes 适配层做了什么

Hermes 侧的 memory_tencentdb provider 是一个 Python 客户端和进程管理器，重型处理位于 Node.js Gateway。两者默认通过 127.0.0.1:8420 通信。

Hermes 生命周期与 Gateway 接口的对应关系如下：

Hermes 调用Gateway 接口处理方式
prefetch(query)POST /recall同步返回记忆上下文，注入当前请求
sync_turn(user, assistant)POST /capture后台线程异步写入，最多 4 个并发任务
shutdown() 或会话结束POST /session/end刷新尚未完成的管线任务

provider 还包含三类运行时保护。连续 5 次 Gateway 请求失败后，circuit breaker 会暂停调用 60 秒；capture 有 4 个并发任务的上限，第 5 个任务最多等待 5 秒；supervisor 会在启动后轮询健康接口，最长等待 30 秒，并把 Gateway 标准错误输出写入日志目录。这样，记忆服务故障不会无限制地制造后台线程，也不会让每轮对话都同步等待提取完成。

已有 Hermes 的安装方式

项目发布的 npm 包版本为 0.3.6，要求 Node.js >=22.16.0。已有 Hermes 的安装路径可以拆成四步：下载插件包、安装 Gateway 依赖、把 provider 放进 Hermes 的 memory provider 目录、在配置中声明 provider。

bash
mkdir -p ~/.memory-tencentdb
TEMP_DIR=$(mktemp -d)
cd "$TEMP_DIR"
npm init -y --silent
npm install @tencentdb-agent-memory/memory-tencentdb@latest --omit=dev
cp -r node_modules/@tencentdb-agent-memory/memory-tencentdb \
  ~/.memory-tencentdb/tdai-memory-openclaw-plugin
rm -rf "$TEMP_DIR"

cd ~/.memory-tencentdb/tdai-memory-openclaw-plugin
npm install --omit=dev
npm install tsx

provider 目录名必须是 memory_tencentdb，中间使用下划线。项目文档给出的链接方式如下：

bash
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

然后在 ~/.hermes/config.yaml 中写入：

yaml
memory:
  provider: memory_tencentdb

Gateway 需要一个 OpenAI 兼容的 LLM 接口，用于 L1、L2 和 L3 的提取与归纳。最小环境变量配置是：

bash
TDAI_LLM_API_KEY="sk-your-api-key-here"
TDAI_LLM_BASE_URL="https://api.openai.com/v1"
TDAI_LLM_MODEL="gpt-4o"

也可以显式指定 Gateway 启动命令：

bash
MEMORY_TENCENTDB_GATEWAY_CMD="sh -c 'cd ~/.memory-tencentdb/tdai-memory-openclaw-plugin && exec npx tsx src/gateway/server.ts'"
MEMORY_TENCENTDB_GATEWAY_HOST="127.0.0.1"
MEMORY_TENCENTDB_GATEWAY_PORT="8420"

项目 provider 也支持自动发现 src/gateway/server.ts。默认数据目录位于 ~/.memory-tencentdb/memory-tdai，需要改变位置时使用 TDAI_DATA_DIR。手动运行 Gateway 的验证命令是：

bash
cd ~/.memory-tencentdb/tdai-memory-openclaw-plugin
node --import tsx src/gateway/server.ts
curl http://127.0.0.1:8420/health

健康接口返回 {"status":"ok"} 或 {"status":"degraded"} 时，provider 才能判断 sidecar 已经响应。

存储、检索与参数

零配置默认使用本地 SQLite + sqlite-vec。项目还提供腾讯云向量数据库 TCVDB 后端，切换时需要配置实例 URL、用户名、API Key 和数据库名。召回默认采用 hybrid 策略，把 BM25 关键词检索和向量检索通过 RRF 融合；recall.maxResults 默认是 5，整体召回超时为 5000 毫秒，超时后跳过注入，不阻塞对话。

常用调参可以先保持默认值：

  • pipeline.everyNConversations: 5，每 5 轮对话触发一次 L1 提取。
  • pipeline.enableWarmup: true，新会话按 1、2、4 轮逐步预热。
  • extraction.maxMemoriesPerSession: 20，限制一次提取产生的记忆数量。
  • persona.triggerEveryN: 50，每积累 50 条新记忆触发一次画像生成。
  • offload.enabled: false，短期上下文压缩需要单独打开。
  • recall.strategy: hybrid，兼顾关键词命中与语义相似度。

如果 embedding 服务使用 BGE-M3 这类固定维度模型，配置中应将 embedding.sendDimensions 设为 false。这个开关默认值为 true，适配支持 Matryoshka 维度截断的 OpenAI embedding 模型；固定维度服务收到自定义 dimensions 字段时会拒绝请求。

Benchmark 如何看

项目 README 给出了 OpenClaw 插件接入前后的连续长程任务结果：

记忆能力BenchmarkOpenClaw加插件后相对变化Token 前Token 后
短期记忆WideSearch33%50%+51.52%221.31M85.64M
短期记忆SWE-bench58.4%64.2%+9.93%3474.1M2375.4M
短期记忆AA-LCR44.0%47.5%+7.95%112.0M77.3M
长期记忆PersonaMem48%76%+59%无无

WideSearch 的成功率由 33% 提高到 50%，项目按相对变化计算为 51.52%；对应 Token 消耗由 221.31M 降至 85.64M，减少 61.38%。SWE-bench 的 Token 消耗减少 33.09%，成功率相对提高 9.93%。PersonaMem 只报告画像准确率，不提供 Token 对照。

这些评测针对连续长程 Session。项目 README 说明，SWE-bench 每个 Session 连续执行 50 个任务，用来模拟上下文持续累积的场景。这个条件与单轮问答差异很大，适合用来观察日志卸载、记忆抽取和召回策略在长链路中的协同效果。

Gateway 的安全边界

Gateway 默认绑定 loopback 地址，适合 Hermes 与 sidecar 在同一台机器运行。需要把 Gateway 放到网络环境时，应配置 TDAI_GATEWAY_API_KEY。启用后，除 GET /health 外的接口都要求 Authorization: Bearer <apiKey>，错误凭证返回 HTTP 401；GET /health 保持开放，方便健康检查。

跨域配置使用 TDAI_CORS_ORIGINS。空列表时 Gateway 不发送 CORS 允许头，浏览器会阻止跨域请求；* 只适合本地开发。Hermes provider 侧使用 MEMORY_TENCENTDB_GATEWAY_API_KEY，如果这个变量没有设置，provider 会回退读取 TDAI_GATEWAY_API_KEY。两端必须配置同一份密钥，插件不会替 Gateway 自动注入密钥。

存储安全同样需要单独处理。L0 原始对话、工具日志、L1 记忆和 L2/L3 Markdown 文件都可能包含项目细节与用户偏好，数据目录应使用合适的文件权限和备份策略。LLM 提取服务也会接触待整理的对话内容，选择云端或本地模型时，需要把这部分数据流纳入部署决策。

适用场景与限制

TencentDB Agent Memory 适合有连续工作流的 Agent：例如多轮代码维护、项目文档整理、需要反复遵循固定 SOP 的运维任务，以及希望跨会话保留用户偏好的个人助手。L0-L3 分层给了开发者明确的观察入口，Mermaid 画布则为长任务提供了轻量状态图。

它需要 Node.js Gateway、LLM 提取服务和持久化存储目录。没有稳定的 LLM 接口时，L1 至 L3 的自动提取无法完成；没有可靠的目录备份时，原始日志与摘要链路也缺少恢复保障。对于只做单轮问答、无需跨会话上下文的 Agent，启用完整记忆管线带来的维护成本未必合算，可以只使用基础对话能力。

项目仍把跨 Agent、跨框架和跨设备的记忆迁移、自动 Skill 生成、可视化调试面板列在 Roadmap 中。现阶段的强项集中在本地记忆分层、长任务上下文卸载、白盒文件产物和 OpenClaw/Hermes 接入。

参考资料