TencentDB-Agent-Memory 深度解析：架构、场景与部署指南（4K★）

为什么值得关注

现在多数 agent 记忆系统把所有对话切片平铺成向量，召回时像在一堆便利贴里找线索、缺宏观视角。TencentDB Agent Memory 提出「拒绝平铺、走向分层与符号化」：建 L0 对话→L1 结构化事实→L2 场景块→L3 用户画像的语义金字塔，平时靠高层 Persona 把握偏好、要细节时再检索底层 Atom；异构存储让低层海量事实进数据库、高层画像/场景/画布进可读 Markdown（低层留证据、高层留结构），且严格索引映射保证每条信息 100% 可溯源恢复、没有不可逆黑盒。再加上本地 SQLite + sqlite-vec 的零外部依赖存储、hybrid（RRF 融合）召回、可选短期记忆压缩，以及实测作为 OpenClaw 插件最高省 61.38% token、通过率相对 +51.52%、PersonaMem 48%→76%。腾讯官方背书 + 可量化收益 + 本地优先，是 agent 长期记忆这条线上设计较有想法的实现。

来源：README_CN 核心技术 / 效果亮点 benchmark

核心功能

4 层语义金字塔（L0→L1→L2→L3）

长期个性化记忆分层：L0 Conversation（原始对话）→ L1 Atom（结构化事实）→ L2 Scenario（场景块）→ L3 Persona（用户画像）。渐进式披露——平时用高层 Persona 把握用户偏好，需要考证细节时才下钻到底层 Atom，避免「扁平向量堆砌」。pipeline 每 N 轮对话触发 L1 提取，L2 有最小间隔，新 session 有 warm-up（1→2→4 轮翻倍触发）。

来源：README_CN '记忆分层' + 配置参数（pipeline.everyNConversations / warmup / l2MinInterval）

异构存储（低层证据 + 高层结构）

底层数据库 + 上层文件系统结合：海量事实/日志/轨迹存数据库或归档文件保证全量检索；高层画像/场景/画布/Skill 存业务可读的 Markdown 保证高信息密度、白盒可调。原则是「低层保留证据，高层保留结构」。

来源：README_CN '渐进式披露与异构存储'

100% 可溯源恢复（无不可逆黑盒）

压缩/抽象最大的风险是丢证据。靠严格索引映射，系统内没有任何摘要是不可逆黑盒——无论短期记忆卸载的报错日志还是长期记忆总结的用户偏好，都能沿「高层符号(Persona/画布) → 中层索引(Scenario/JSONL) → 底层原文(L0/refs)」完美溯源恢复。

来源：README_CN '每一条信息都 100% 可找回、可恢复'

符号化记忆（Mermaid 画布）

用最少符号表达最多语义——把记忆组织成 Mermaid 画布等符号化结构，提升信息密度与逻辑清晰度，让 agent 和开发者都能白盒查看与调整高层记忆。

来源：README_CN '符号化记忆' 节

本地 SQLite + sqlite-vec + hybrid 召回

默认本地 SQLite + sqlite-vec 后端，向量检索零外部 API；召回策略支持 keyword / embedding / hybrid（RRF 融合，推荐）；中文用 @node-rs/jieba 分词、tcvdb-text 文本处理、js-tiktoken 计 token。可选短期记忆压缩（offload，≥0.3.4）。注：记忆提取 pipeline 仍需一个 LLM（MODEL_API_KEY，默认腾讯 LKE / DeepSeek-V3.2，可指向任意 OpenAI 兼容接口），「零外部 API」主要指存储与向量检索。

来源：README_CN 配置参数（storeBackend/recall.strategy/offload）+ Hermes 配置 + package deps

OpenClaw 零配置插件 + Hermes 支持

作为 OpenClaw 插件零配置启用（openclaw.plugin.json）；通过 slots 字段注册 contextEngine 可启用短期记忆压缩路由。也支持 NousResearch 的 Hermes agent——一条 docker 命令启动带记忆的 Hermes（Gateway :8420、命名卷持久化）。hermes-plugin/ 目录承载这部分。

来源：README_CN OpenClaw / Hermes 接入 + hermes-plugin/ + openclaw.plugin.json

技术架构

项目是 TypeScript 库 + 插件，src/（122 文件）实现核心：4 层记忆 pipeline（L0→L1→L2→L3 的提取与抽象）、异构存储层（SQLite + sqlite-vec 存底层事实与向量、Markdown 文件系统存高层 Persona/Scenario/画布）、召回引擎（keyword/embedding/hybrid RRF）、短期记忆压缩（offload）。中文处理用 @node-rs/jieba + tcvdb-text，LLM 调用经 @ai-sdk/openai + ai SDK（可配任意 OpenAI 兼容 endpoint）。对外有两种接入：OpenClaw 插件（openclaw.plugin.json + slots/contextEngine 路由）和 Hermes（hermes-plugin/ + Docker，Gateway :8420 + 命名卷持久化）。数据流：对话进来 → 按 N 轮/idle/warm-up 触发 L1 事实提取 → L2 场景聚合 → L3 画像更新，同时严格维护索引映射保证任意高层符号可回溯到底层原文。设计判断：核心创新是「分层 + 符号化 + 可溯源」三点——用语义金字塔替代扁平向量、用低层 DB+高层 Markdown 的异构存储兼顾全量检索与白盒可调、用索引映射保证压缩不丢证据，这套设计明显比「一堆向量 + 相似度召回」更有结构感，也更适合需要解释和审计记忆的场景；代价是 pipeline 依赖 LLM 做提取（有成本和质量波动），且分层提取的准确性本身是新的质量变量。

来源：README_CN 核心技术 + tree（src/hermes-plugin）+ package deps

项目知识图谱

中心为项目本体，内环 = 核心功能模块，外环 = 关键技术依赖；按 deep.json 中的 core_features 与 tech_stack.key_deps 自动生成

技术栈

语言TypeScript框架OpenClaw 插件 + Hermes 插件（Docker）；4 层记忆 pipeline 引擎

关键依赖

sqlite-vec@ai-sdk/openai + ai@node-rs/jieba + @tencentdb-agent-me…js-tiktokenundici

基础设施 / 部署

本地优先：SQLite + sqlite-vec 存储、Markdown 文件存高层记忆；记忆提取 pipeline 需 LLM（MODEL_API_KEY，默认腾讯 LKE/DeepSeek-V3.2，支持任意 OpenAI 兼容）；OpenClaw 插件零配置 / Hermes 走 Docker（Gateway :8420 + 命名卷）；npm 包 @tencentdb-agent-memory/memory-tencentdb；NOASSERTION 协议；vitest + e2e 测试

来源：package.json + README_CN 配置/接入

快速上手

# OpenClaw（推荐，零配置） # 1.1 安装插件（默认本地 SQLite + sqlite-vec 后端） # 见 README OpenClaw 安装步骤 # 1.2 零配置启用即可 # 1.3（可选，≥0.3.4）启用短期记忆压缩：在插件配置 slots 字段注册 contextEngine # 让 OpenClaw 把上下文卸载请求路由到本插件 # Hermes（Docker，≥0.3.4） # 配置：MODEL_API_KEY（必填，大模型凭证）、MODEL_BASE_URL（默认腾讯 LKE）、 # MODEL_NAME（默认 DeepSeek-V3.2）、MODEL_PROVIDER=custom（OpenAI 兼容） docker run -d --name hermes-memory --restart unless-stopped \ -p 8420:8420 -e MODEL_API_KEY=... -e MODEL_BASE_URL=... \ -v hermes_data:/opt/data curl http://localhost:8420/health # 验证 Gateway # 关键配置：recall.strategy=hybrid（RRF，推荐）、 # pipeline.everyNConversations=5（每 5 轮提取 L1）、offload.enabled 控短期压缩

来源：README_CN 快速开始 / OpenClaw / Hermes / 配置参数原文

使用场景

1. 给 OpenClaw / Hermes agent 加本地长期记忆：零配置接入后 agent 能跨会话记住用户偏好、历史决策，且记忆是分层可解释的而非一堆向量；2. 省 token + 提准确率：用高层 Persona 替代把全部历史塞进上下文，实测最高省 61% token、PersonaMem 48%→76%；3. 需要可审计/可溯源记忆的场景：靠索引映射从画像回溯到原始对话，满足「为什么 agent 这么认为」的解释需求；4. 隐私/本地优先：存储与向量检索全本地 SQLite，数据不出机（提取 pipeline 可指向本地或自有 LLM endpoint）；5. 中文 agent 记忆：内置 jieba 分词与中文文本处理，对中文场景适配好。

来源：README_CN 效果亮点 / 核心技术 / 配置

优势与局限

优势

记忆设计有真想法：4 层语义金字塔（L0→L1→L2→L3）+ 渐进式披露替代扁平向量堆砌，平时用高层画像、要细节再下钻，比纯相似度召回更有结构和宏观视角
可溯源、白盒、不丢证据：严格索引映射让任意高层符号能回溯到底层原文，没有不可逆黑盒摘要，高层记忆存可读 Markdown 可人工调，对解释性和审计友好
本地优先存储：SQLite + sqlite-vec 向量检索零外部 API、数据留本机，hybrid（RRF）召回，对隐私和离线场景有利
有可量化收益：作为 OpenClaw 插件实测最高省 61.38% token、通过率相对 +51.52%、PersonaMem 准确率 48%→76%，不是空谈
腾讯官方 + 中文适配 + 易接入：jieba 中文分词、零配置 OpenClaw 插件 + 一条命令 Docker 跑带记忆的 Hermes，工程规范（vitest + e2e）

局限

「零外部 API」需厘清：存储与向量检索确实本地零依赖，但 4 层记忆的提取/抽象 pipeline 仍需一个 LLM（MODEL_API_KEY，默认腾讯 LKE/DeepSeek-V3.2），不是完全无模型——纯离线需自己接本地 LLM endpoint
可测试性 / 质量风险：分层提取（L1 事实抽取、L2 场景聚合、L3 画像）的准确性是新的质量变量，提取错会污染高层记忆；benchmark 是其在特定数据集（PersonaMem 等）上的结果，对你的场景是否同样需自测
可维护性 / 复杂度：4 层 pipeline + 异构存储（DB + Markdown）+ 多触发条件（everyN/idle/warmup/L2 间隔）+ offload，配置项多、调优面大，理解和运维成本高于简单向量记忆
稳定性风险：仍是 0.3.x 早期，几天一个版本，配置 schema 和 pipeline 行为可能演进；offload 等功能有版本门槛（≥0.3.4）
可扩展性 / 生态绑定：主要面向 OpenClaw 和 Hermes 两个 agent 的插件形态，接其它 agent 需自行适配；NOASSERTION 自定义协议，二次分发前需看清条款
性能 / 成本：每 N 轮触发 LLM 提取意味着持续的 LLM 调用成本，长会话/高频对话下的 token 与延迟开销未量化；分层抽象的实时性受触发间隔配置影响

来源：综合 README_CN + package.json + 配置说明

总结评价

如果你在给 agent 做长期记忆、又不满足于「一堆向量 + 相似度召回」，TencentDB Agent Memory 的分层 + 符号化 + 可溯源设计值得一看：L0→L1→L2→L3 语义金字塔、低层 DB 高层 Markdown 的异构存储、100% 可回溯，配本地 SQLite 存储和实测的 token/准确率收益。务实建议：1) 用 OpenClaw 的话零配置接入最省事，先体验分层记忆带来的 token 节省和画像准确率提升；2) 厘清「零外部 API」——存储和向量检索本地零依赖，但记忆提取仍需一个 LLM（默认腾讯 LKE/DeepSeek，可换 OpenAI 兼容或本地 endpoint），纯离线要自己接本地模型；3) 配置项多（recall 策略、提取触发间隔、offload），先用默认 hybrid + everyN=5 跑通再调；4) 分层提取质量是关键变量，提取错会污染高层画像，重要场景要抽查 L1/L3 的准确性，好在可溯源便于核对；5) 0.3.x 早期、几天一版，配置 schema 可能变，生产前锁版本；6) 目前主要服务 OpenClaw/Hermes，接其它 agent 需自己适配。

来源：综合分析

透明度声明
本页内容由 AI（大语言模型）基于以下公开材料自动生成：GitHub README、代码目录结构、依赖文件、Release 信息。分析时间: 2026-05-22 10:28. 质量评分: 100/100.

数据来源：README、GitHub API、依赖文件

TencentDB-Agent-Memory 是什么？