TencentDB-Agent-Memory

为AI Agent提供完全本地的长期记忆系统，通过四层渐进式管道实现符号短期记忆和分层长期记忆。亮点在于采用分层存储和符号化Mermaid画布，可降低token消耗达61%并提升任务成功率51%，支持与OpenClaw、Hermes等Agent框架无缝集成，完全本地部署无外部API依赖。腾讯云开源，MIT许可证。

README

Agent 记忆，人类创新。

亮点 · 概述 · 核心技术 · 功能特性 · 快速开始

English · 简体中文

✨ 亮点

腾讯云数据库 Agent 记忆 = 符号化短期记忆 + 分层长期记忆。

符号化短期记忆：将臃肿的工具日志卸载，压缩为紧凑的 Mermaid 符号，减少 token 消耗并提升任务成功率。

分层长期记忆：将零散的对话提炼为结构化的角色与场景，而非扁平化的向量堆积。

当与 OpenClaw 集成时，可降低 token 消耗高达 61.38%，通过率提升 51.52%（相对值），PersonaMem（角色记忆）准确率从 48% 提升至 76%。

记忆能力	基准测试	OpenClaw 成功率	集成插件后	相对变化	OpenClaw token 消耗	集成插件后 token 消耗	相对变化
短期记忆	WideSearch	33%	50%	+51.52%	221.31M	85.64M	−61.38%
短期记忆	SWE-bench	58.4%	64.2%	+9.93%	3474.1M	2375.4M	−33.09%
短期记忆	AA-LCR	44.0%	47.5%	+7.95%	112.0M	77.3M	−30.98%
长期记忆	PersonaMem	48%	76%	+59%	—	—	—

以上结果基于连续的长周期会话测量，而非单个回合。例如，SWE-bench 每个会话连续运行 50 个任务，以模拟真实场景中上下文累积的压力。

概述

记忆不是让 AI 囤积一切——而是免除人类反复重复的负担。

在实践中，我们不断向 Agent 重复解释相同的 SOP、项目背景、工具约定和输出格式。这些信息不应重复说明，也不应不加区分地全部塞入上下文。

腾讯云数据库 Agent 记忆帮助 Agent 学习你的工作流、保留任务上下文并复用过往经验。我们拒绝暴力的历史堆积，也拒绝不可逆的有损摘要。我们设计了一套分层记忆系统：符号化记忆应对任务内的信息过载，记忆分层应对跨会话的经验复用。

让 Agent 记住该记的，让人类专注于判断、创造和真正重要的工作。

核心技术：拒绝扁平存储，拥抱分层与符号化

我们的架构基于两大支柱：记忆分层与符号化记忆。两者共同确保 Agent 不仅“记得更多”，更能“推理得更好”。

1. 记忆分层：渐进披露与异构存储

传统记忆系统将数据切碎后倒入扁平向量存储中，召回退化为在离散碎片间的盲目搜索，缺乏宏观指引。

无论是长期知识、短期任务还是未来技能能力，记忆都不应扁平——其形成与召回都必须是层级化的。腾讯云数据库 Agent 记忆将分层作为统一的架构范式：

短期上下文分层。 底层归档原始工具输出（refs/*.md）；中间层提取步骤级摘要（jsonl）；顶层将状态压缩为轻量级 Mermaid 画布。Agent 在上下文中只需关注顶层结构，出错时通过 node_id 钻取到底层。
长期个性化分层。 替代扁平日志，我们构建语义金字塔：L0 对话（原始对话）→ L1 原子（原子事实）→ L2 场景（场景块）→ L3 角色（用户画像）。角色层承载日常偏好；系统在需要细节时才会钻取到原子层。
技能生成分层。 分层同样适用于动作。中间层从底层执行轨迹（对话）中提炼通用解决方案模式（场景），顶层则蒸馏出可复用的技能或标准 SOP（角色）。

TencentDB Agent 记忆 L0 到 L3 语义金字塔

异构存储与渐进披露。 该架构依托双层存储策略。底层（事实、日志、轨迹）持久化到数据库，实现稳健的全文本检索；顶层（角色、场景、画布）存储为人类可读的 Markdown 文件，实现高信息密度与白盒检查。底层保存证据；上层保存结构。

全程可追溯与无损恢复。 压缩往往牺牲可追溯性。腾讯云数据库 Agent 记忆避免不可逆压缩，维护一条从高层抽象到真实证据的确定性路径。无论是卸载的错误日志还是提炼的用户偏好，系统都保证完整的下钻路径：“顶层符号（角色/画布）→ 中层索引（场景/jsonl）→ 底层原始文本（L0 对话/refs）”。

2. 符号化记忆：最小符号承载最大语义（Mermaid 画布）

在长任务中，最大的 token 消耗者是冗长的中间日志（搜索结果、代码、错误追踪）。为此，我们结合上下文卸载与符号化记忆：

Mermaid 符号图。 用高密度的 Mermaid 语法编码任务状态转移——足够精确供 LLM 解析，足够简洁供人类阅读。
历史卸载。 完整工具日志卸载到外部文件；上下文中仅保留轻量级 Mermaid 任务地图。
node_id 追踪。 Agent 在符号图上推理；如需验证某个细节，通过 grep 查找该 node_id 即可瞬间检索完整原始文本——既降低 token 消耗，又保留完整可追溯性。

graph LR
    Log["冗长日志<br/>(数十万 token)"] -->|"1. 卸载全文"| FS[("外部文件系统<br/>(refs/*.md)")]
    Log -->|"2. 提取关系"| MMD["Mermaid 画布<br/>(含 node_id)"]
    
    MMD -->|"3. 轻量注入"| Agent(("Agent 上下文<br/>(几百 token)"))
    Agent -. "4. 通过 node_id 召回" .-> FS
    
    style Log fill:#f1f5f9,stroke:#94a3b8,stroke-dasharray: 5 5,color:#475569
    style FS fill:#f8fafc,stroke:#cbd5e1,stroke-width:2px,color:#334155
    style MMD fill:#eff6ff,stroke:#3b82f6,stroke-width:2px,color:#1e3a8a
    style Agent fill:#fffbeb,stroke:#f59e0b,stroke-width:2px,color:#92400e

快速开始

🎬 演示


OpenClaw × Agent Memory（Agent 记忆）	Hermes × Agent Memory（Agent 记忆）

1. OpenClaw

1.1 安装插件

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

请使用原生 OpenClaw 命令升级插件。此方法可避免因语义版本范围导致插件被禁用。
openclaw plugins update @tencentdb-agent-memory/memory-tencentdb

1.2 零配置启用

默认使用本地 SQLite + sqlite-vec 后端。

// ~/.openclaw/openclaw.json
{
  "memory-tencentdb": {
    "enabled": true
  }
}

启用后，TencentDB Agent Memory（腾讯云数据库 Agent 记忆）将自动处理对话捕获、记忆提取、场景聚合、角色生成以及下一轮对话前的召回。

1.3 启用短期压缩（可选，要求版本 ≥ 0.3.4）

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

第1步 — 在插件配置中注册槽位

添加 slots 字段，使 OpenClaw 将上下文卸载请求路由到此插件：

{
  "plugins": {
    "slots": {
      "contextEngine": "memory-tencentdb"
    }
  }
}

第2步 — 应用运行时补丁

为获得最佳效果，运行以下补丁脚本。它会 hook after-tool-call 消息，使其能被正确卸载和恢复：

bash scripts/openclaw-after-tool-call-messages.patch.sh

💡 该补丁仅需在每次 OpenClaw 安装后应用一次。升级 OpenClaw 后，请重新运行脚本以重新应用。

2. Hermes

除 OpenClaw 外，此插件也支持 Hermes Agent。根据部署场景选择安装路径：

你的需求	使用
一行命令全新启动带记忆功能的 Hermes	2.A Docker（如下）
为现有 Hermes 安装添加记忆功能	2.B 挂接到现有 Hermes（下一节）

2.A Docker（全新部署，要求版本 ≥ 0.3.4）

Docker 镜像捆绑了 hermes-agent 和 memory_tencentdb 提供器（provider）。Gateway 监听 :8420 端口：

# ============ 配置参数 ============
# MODEL_API_KEY    LLM API 密钥（必填）—— 替换为你自己的凭证
# MODEL_BASE_URL   LLM 端点，默认指向腾讯云 LKE（大模型知识引擎）
# MODEL_NAME       模型名称，默认为 DeepSeek-V3.2
# MODEL_PROVIDER   提供器类型："custom" 适用于任何兼容 OpenAI 的端点

MODEL_API_KEY="your-api-key"
MODEL_BASE_URL="https://api.lkeap.cloud.tencent.com/v1"
MODEL_NAME="deepseek-v3.2"
MODEL_PROVIDER="custom"

# ============ docker run 标志 ============
# -d                          以后台（分离）模式运行容器
# --name hermes-memory        容器名称，用于后续 docker exec / logs / stop
# --restart unless-stopped    崩溃或主机重启时自动重启
# -p 8420:8420                主机端口 ↔ 容器端口（Hermes Gateway）
# -e MODEL_*                  将上述配置参数作为环境变量注入
# -v hermes_data:/opt/data    将记忆数据持久化到命名卷（重启后保留）

# 进入 Docker 构建目录（已克隆仓库并位于仓库根目录）
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="your-api-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

# 验证 Gateway
curl http://localhost:8420/health

# 进入 Hermes 交互式 shell
docker exec -it hermes-memory hermes

镜像默认搭载腾讯云 DeepSeek-V3.2。若使用此模型，可省略 MODEL_BASE_URL / MODEL_NAME / MODEL_PROVIDER，仅传入 MODEL_API_KEY 即可。

2.B 挂接到现有 Hermes（无需 Docker）

如果你已在主机上安装了 hermes-agent，只想添加记忆能力，无需 Docker 镜像。

1. 下载插件包到统一目录：

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"

2. 安装 Gateway 依赖：

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

3. 链接到 Hermes 插件目录：

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（下划线）——Hermes 以此作为提供器键名。memory-tencentdb（连字符）仅作为配置层别名，不能用作目录名。

4. 在 ~/.hermes/config.yaml 中声明提供器：

memory:
  provider: memory_tencentdb

5. 配置 Gateway 环境变量

编辑 ~/.hermes/.env 并添加：

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"

根据需要添加 LLM 凭证（Gateway 实际读取 TDAI_LLM_* 变量）：

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

或者使用 Gateway 配置文件 ~/.memory-tencentdb/memory-tdai/tdai-gateway.json：

{
  "llm": {
    "baseUrl": "https://your-api-endpoint/v1",
    "apiKey": "your-api-key",
    "model": "your-model-name"
  }
}

6. 启动 Gateway（选择一种方法）：

自动发现（推荐，零配置）：不要手动启动 Gateway——直接开始与 Hermes 对话。提供器会在首次对话时自动发现 ~/.memory-tencentdb/tdai-memory-openclaw-plugin/src/gateway/server.ts 并通过 Popen() 启动它。首次对话可能会有轻微延迟。

手动运行：提前启动独立 Gateway 进程：

cd ~/.memory-tencentdb/tdai-memory-openclaw-plugin
npx tsx src/gateway/server.ts

7. 验证：

curl http://127.0.0.1:8420/health
# 应返回 {"status":"ok"} 或 {"status":"degraded"}

完整的提供器参考（环境变量、故障排除、LLM 工具模式、监督器行为）请参见 hermes-plugin/memory/memory_tencentdb/README.md。在调整监督器/熔断器默认值前请务必阅读。

🔒 Gateway 安全（可选）

Hermes Gateway 监听 :8420 端口，暴露捕获/搜索/召回 HTTP 端点。两个可选的开关可将其从“开放的 localhost sidecar”转变为“经过身份验证的网络服务”。两者默认关闭，因此现有部署无需修改即可继续工作。

字段	环境变量	默认值	描述
`server.apiKey`	`TDAI_GATEWAY_API_KEY`	（未设置）	设置后，除 `GET /health` 外的所有路由均需提供 `Authorization: Bearer <apiKey>`；缺失或错误的 token 将返回 HTTP 401。比较采用常量时间。
`server.corsOrigins`	`TDAI_CORS_ORIGINS`（逗号分隔）	`[]`	CORS 白名单。空列表不会发出 `Access-Control-Allow-` 头——浏览器将阻止所有跨域请求。仅本地开发时使用 `[""]`。

当 apiKey 未设置时，Gateway 会在启动时打印 WARN 警告。如果绑定到非回环地址（如 0.0.0.0）且未设置 apiKey，则会发出更显眼的二次警告。

客户端使用 Bearer token 调用受保护路由：

curl -H "Authorization: Bearer $TDAI_GATEWAY_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"query":"...","session_key":"..."}' \
     http://127.0.0.1:8420/recall

GET /health 保持开放无需 token，以便编排器探针（docker healthcheck、kubectl liveness）正常工作。

Hermes 插件端

Hermes 的 memory_tencentdb 插件是 Gateway 的客户端。若要其与启用身份验证的 Gateway 通信，请设置：

export MEMORY_TENCENTDB_GATEWAY_API_KEY="<与 gateway 相同的密钥>"

之后，插件会向发送给 Gateway 的每个请求附加 Authorization: Bearer <key> 头。若变量未设置，插件不发送身份验证头——这与 Gateway 的旧版默认行为匹配，对于未启用 TDAI_GATEWAY_API_KEY 的 Gateway 来说没问题。

重要：插件仅处理客户端部分。Gateway 是否实际执行 Bearer 检查由 Gateway 端决定（TDAI_GATEWAY_API_KEY / server.apiKey）。请在两端配置相同的密钥——插件不会跨端传播密钥，因为 Gateway 可能由 Docker、systemd 或其他任何方式启动，不受插件控制。

如果 MEMORY_TENCENTDB_GATEWAY_API_KEY 未设置，插件还会回退读取 TDAI_GATEWAY_API_KEY——当两个进程共享同一个 env 文件且运维者只想设置一个变量名时很方便。Gateway 从不读取 MEMORY_TENCENTDB_GATEWAY_API_KEY；该名称仅用于插件端。

🔧 可配置参数

每个字段都有合理的默认值——零配置即可运行。 当你需要调优时，根据深入程度逐层展开即可。

🟢 第一级 · 日常调优（覆盖 90% 的使用场景）

字段	默认值	描述
`timezone`	`"system"`	面向用户/LLM 的时间戳时区：`"system"`（跟随进程时区）/ IANA 名称（如 `Asia/Shanghai`）/ 偏移字符串（如 `+08:00`）
`storeBackend`	`"sqlite"`	存储后端：`sqlite`
`recall.strategy`	`"hybrid"`	召回策略：`keyword`（关键词）/ `embedding`（嵌入）/ `hybrid`（混合，RRF 融合，推荐）
`recall.maxResults`	`5`	每次召回返回的项目数
`recall.maxCharsPerMemory`	`0`	每次召回的单条 L1 记忆注入的最大字符数；`0` 表示不限制
`recall.maxTotalRecallChars`	`0`	自动召回的 L1 记忆总字符预算；`0` 表示不限制
`pipeline.everyNConversations`	`5`	每 N 轮对话触发一次 L1 记忆提取
`extraction.maxMemoriesPerSession`	`20`	每次 L1 提取的最大记忆数量
`persona.triggerEveryN`	`50`	每新增 N 条记忆生成一次用户画像
`offload.enabled`	`false`	是否启用短期压缩

🟡 第二级 · 高级调优（长任务 / 长会话）

字段	默认值	描述
`pipeline.enableWarmup`	`true`	预热：新会话从第1轮开始触发，每次翻倍直到 N（1→2→4→…）
`pipeline.l1IdleTimeoutSeconds`	`600`	用户空闲超过此秒数后触发 L1
`pipeline.l2MinIntervalSeconds`	`900`	同一会话中两次 L2 处理的最小间隔（秒）
`recall.timeoutMs`	`5000`	召回超时；超时后跳过注入，不阻塞对话
`extraction.enableDedup`	`true`	L1 向量去重/冲突检测
`capture.excludeAgents`	`[]`	用于排除特定 Agent 的 glob 模式（如 `bench-judge-*`）
`capture.l0l1RetentionDays`	`0`	L0/L1 文件的本地保留天数；`0` = 从不清理
`offload.mildOffloadRatio`	`0.5`	轻度压缩触发比率（相对于上下文窗口）
`offload.aggressiveCompressRatio`	`0.85`	激进压缩触发比率
`offload.mmdMaxTokenRatio`	`0.2`	MMD 注入的 token 预算比率
`bm25.language`	`"zh"`	分词器语言：`zh`（jieba）/ `en`

🔴 第三级 · 完整参数参考（运维 / 自定义模型 / 远程嵌入）

所有字段、类型和约束请参见 openclaw.plugin.json。

embedding.* — 远程嵌入服务（兼容 OpenAI 的 API）
- embedding.sendDimensions（默认 true）：是否在请求体中包含 dimensions 字段。OpenAI 的 text-embedding-3-* 模型依赖它实现 Matryoshka 截断，但某些自托管/开源模型（如 BGE-M3）不支持自定义维度，会返回 HTTP 400 does not support matryoshka representation。对于此类后端，请将其设置为 false，例如：
```
{
  "embedding": {
    "enabled": true,
    "provider": "openai",
    "baseUrl": "http://your-host:your-port/v1",
    "apiKey": "<KEY>",
    "model": "bge-m3",
    "dimensions": 1024,
    "sendDimensions": false
  }
}
```
llm.* — 独立 LLM 模式（绕过 OpenClaw 的内置模型，使用指定的 API 执行 L1/L2/L3）
offload.backendUrl / backendApiKey — 将 L1/L1.5/L2/L4 流程卸载到后端服务
report.* — 指标上报

🤔 功能特性

1. 宏观画像 + 微观事实：统一的下钻机制

压缩的最大风险是以丢失证据为代价节省 token。因此，腾讯云数据库 Agent 记忆不会将历史压缩为不可逆的摘要——它保留了从高层抽象回到真实证据的清晰路径。

问题类型	优先查看	下钻到
日常偏好、语气、长期目标	L3 角色 / L2 场景	需要具体事实时下钻到 L1 原子 / L0 对话
具体事实、日期、项目细节	L1 原子 / L0 对话	扩大时间范围，或结果稀疏时回退到语义召回
继续执行长运行任务	活跃的 Mermaid 任务画布	摘要缺少细节时检查 JSONL，再到 `refs/*.md` 获取原始文本
恢复历史任务	元数据任务条目	打开 Mermaid 画布 → 定位 `node_id` → 追踪 `result_ref`

上层承载判断与方向；下层承载证据与精确性。短期压缩与长期记忆形成单一闭环：可折叠可展开，抽象却可审计。

2. 白盒可调试性：记忆不再是黑盒

大多数记忆系统在此方面不足：召回错误时，你只能看到一系列向量得分，无法追溯出错原因。腾讯云数据库 Agent 记忆将关键中间产物保存为可读文件：

L2 场景块是纯 Markdown——打开即可检查。
L3 角色存在于 persona.md 中，并可追溯到生成它的场景。
短期任务画布是 Mermaid——人类和 Agent 都可阅读。
原始负载、摘要和节点通过 result_ref 和 node_id 链接。

调试不再是探查不透明的数据库——而是沿着“角色 → 场景 → 原子 → 对话”链进行确定性遍历，直至根因浮出水面。

所有这些分层记忆产物都位于 ~/.openclaw/memory-tdai/ 目录下——欢迎打开目录亲自检查每一层。

3. 生产级工程：绝非演示品

能力	描述
OpenClaw 插件	安装后自动捕获、提取和召回记忆
Hermes Gateway 适配器	`TdaiCore + HostAdapter`，与宿主框架解耦
本地后端	`SQLite + sqlite-vec`，开箱即用
混合检索	BM25 + 向量 + RRF——同时支持关键词和语义召回
Agent 工具	`tdai_memory_search` / `tdai_conversation_search`

文档

文档	内容
`scripts/README.memory-tencentdb-ctl.md`	运维管理工具
`CHANGELOG.md`	发布说明与版本历史
`openclaw.plugin.json`	OpenClaw 插件清单与配置模式

社区与贡献

我们欢迎各种形式的贡献——错误报告、功能建议、文档修复、基准复现、生态集成，或提交 Pull Request。Agent 记忆远未成为已解决问题，我们期待与你共同探索。

🐞 发现 bug 或有疑问？ 在 GitHub Issues 提交 issue——我们会在 24 小时内响应。
💡 有想法想分享？ 在 GitHub Discussions 发起话题。
🛠️ 想贡献代码？ 请先阅读 CONTRIBUTING.md。
💬 想与我们交流？ 加入我们的 Discord 社区，直接与早期开发者对话。

路线图

长期个性化记忆（L0 → L3）
短期上下文压缩（Context Offload + Mermaid 画布）
本地 SQLite 后端与腾讯云向量数据库（TCVDB）后端
OpenClaw 插件与 Hermes Gateway 集成
可迁移记忆：跨 Agent / 跨框架 / 跨设备的导入、导出与热迁移
自动技能生成
可视化调试与记忆可观测性仪表板

如果腾讯云数据库 Agent 记忆对你有帮助，请给项目点个 ⭐ 支持我们。
如有任何建议，欢迎提交 issue 开始讨论。

开源项目TencentCloud2026-07-08原文

打开互动版