TencentDB Agent Memory 项目理解报告

仓库：Tencent/TencentDB-Agent-Memory · 当前克隆版本：0.3.4 · Node.js ≥ 22.16 · License: MIT

一句话：这是腾讯开源的 Agent 记忆插件/框架，核心目标是让长程 Agent 同时具备“短期上下文压缩”和“长期个性化记忆”，并通过 OpenClaw 插件与 Hermes Gateway 两条路径落地。

长期记忆 L0→L3短期 OffloadSQLite/sqlite-vecTCVDBOpenClawHermes

1. 项目定位

TencentDB Agent Memory 不是单纯的“向量库记忆插件”。它强调两件事：

符号化短期记忆：把长任务中大量工具输出、日志、错误栈卸载到外部文件，只在上下文保留轻量 Mermaid 任务画布；需要证据时通过 node_id 下钻回原文。
分层长期记忆：把对话逐层沉淀为 L0 Conversation → L1 Atom → L2 Scenario → L3 Persona，避免把所有碎片平铺进向量库。

它的价值主张是：减少用户重复解释 SOP、项目背景、偏好和工具习惯，同时避免不可追溯的黑盒摘要。

2. 核心架构

L0：原始对话

自动捕获会话轮次，保存原始证据。用于追溯与重新提取。

L1：原子记忆

由 LLM 从对话中抽取结构化事实，并做去重/冲突检测。

L2：场景块

把分散事实归纳成任务/项目/偏好等场景块，通常是可读 Markdown。

L3：用户画像

从场景中沉淀稳定 Persona，用于日常高层召回。

Offload：短期压缩

工具结果进入 refs，步骤摘要进入 jsonl，任务状态进入 Mermaid 画布。

检索层

支持关键词、向量、Hybrid/RRF；后端可用本地 SQLite + sqlite-vec 或 Tencent Cloud VectorDB。

3. 代码结构

路径	作用
`index.ts`	OpenClaw 插件入口；注册 hook、工具、CLI、offload。
`src/core/tdai-core.ts`	宿主无关核心；暴露 `handleBeforeRecall`、`handleTurnCommitted`、`searchMemories` 等。
`src/core/conversation`	L0 会话记录。
`src/core/record`	L1 提取、写入、去重、读取。
`src/core/scene` / `persona`	L2 场景与 L3 画像生成。
`src/core/store`	SQLite、TCVDB、BM25、embedding、检索融合。
`src/offload`	短期上下文卸载、Mermaid 生成、压缩与恢复。
`src/gateway`	独立 Gateway HTTP 服务，供 Hermes 插件调用。
`hermes-plugin/memory/memory_tencentdb`	Hermes 记忆 provider 插件，含客户端与 supervisor。
`scripts/`	安装、迁移、诊断、OpenClaw patch、offload 设置脚本。

4. 对外能力

自动捕获：在 Agent turn 完成后记录对话。
自动提取：后台把对话变成 L1 结构化记忆。
自动召回：下一轮 prompt 前检索相关记忆并注入上下文。
画像生成：按阈值从 L1/L2 生成 Persona。
可查工具：tdai_memory_search、tdai_conversation_search。
上下文 Offload：长任务中把大日志卸载成可追溯 Mermaid 画布。
运维工具：read-local-memory、SQLite→TCVDB 迁移、导出、诊断脚本。

5. 快速使用

OpenClaw

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

最小配置：

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

Hermes Docker

docker build -f Dockerfile.hermes -t hermes-memory .
docker run -d --name hermes-memory -p 8420:8420 \
  -e MODEL_API_KEY="***" \
  -v hermes_data:/opt/data hermes-memory

验证：curl http://localhost:8420/health

6. 配置重点

配置组	含义	默认/注意点
`storeBackend`	存储后端	默认 `sqlite`；也支持 `tcvdb`。
`recall`	召回策略、条数、阈值、超时	默认 hybrid、maxResults=5、timeout=5000ms。
`pipeline`	L1→L2→L3 调度	默认每 5 轮触发 L1，warmup 开启。
`embedding`	远端 embedding 配置	provider=none 时向量检索实际关闭；远端必须配 apiKey/baseUrl/model/dimensions。
`offload`	短期上下文压缩	默认关闭；长任务可开启。
`llm`	独立记忆提取模型	可让 L1/L2/L3 用廉价模型，不占主 Agent 模型。

7. 优点、局限与适用场景

优点

不是黑盒 summary，强调证据可追溯。
短期和长期记忆都覆盖。
宿主抽象清晰，OpenClaw/Hermes 均可接入。
默认 SQLite 开箱即用，TCVDB 可扩展。
配置、诊断、迁移脚本较完整。

局限/风险

版本较新，当前 0.3.4，仍处快速演进期。
强依赖 Node ≥22.16 与宿主 hook 机制。
OpenClaw offload 需 patch after-tool-call，升级宿主后可能要重跑。
Embedding 配错会静默降级到非向量路径。
对中文/英文 BM25、模型质量、召回阈值较敏感。

适用

长程编码/运维 Agent，需要跨回合保留背景。
用户偏好/SOP 重复出现的个人助手。
工具日志巨大、上下文容易爆的任务。
需要可审计、可下钻记忆链路的团队。

不适用

只做单轮问答。
宿主无法提供会话 hook。
无法接受本地持久化用户对话。
希望完全无 LLM 后台成本。

8. 我的判断

技术方向值得关注：它抓住了 Agent 记忆的两个关键矛盾：上下文不能无限塞、摘要不能丢证据。它用“分层 + 可下钻”的结构解决这个矛盾，比简单 mem0/向量库式记忆更偏工程化。

现阶段更像可用的早期工程框架：文档、脚本、Hermes/OpenClaw 适配都已具备，但版本仍新、宿主兼容逻辑较多，生产接入前应先小范围灰度。

如果用于 Hermes：重点看 hermes-plugin/memory/memory_tencentdb 与 src/gateway/server.ts，它通过独立 Gateway 承载 TDAI Core，再由 Hermes memory provider 调用。

本报告基于仓库 README_CN、package.json、openclaw.plugin.json、CHANGELOG、核心目录和入口文件静态检查生成。