编辑文档 - 腾讯开源的这个记忆插件，Hermes 用户终于能用上了

标题

工具栏

点击或拖拽上传图片

支持 PNG, JPG, GIF, WebP 格式

内容 (Markdown 格式)

# 腾讯开源的这个记忆插件，Hermes 用户终于能用上了

**作者：小创**

---

用了 Agent 框架最痛苦的事情是什么？每次新开一个 session，AI 完全不记得你上次做到哪了。CommonAgent 记忆方案换了一个又一个，要么配置复杂到令人发指，要么效果平平装完跟没装一样。

最近腾讯放出了一个叫 **TencentDB Agent Memory** 的东西，官宣数据说接入后 Token 消耗最高能降 **61%**，成功率提升 **51%**（数据来源：TencentDB-Agent-Memory 官方 README）。我研究了一下，发现它跟 Hermes Agent 的集成比想象中简单得多——腾讯官方已经把它做成了 Hermes 的内置 memory provider。

今天把这套方案完整跑了一遍，把安装方式、架构逻辑、配置细节全部梳理清楚。

---

## 一、它做了什么：四层记忆金字塔

这套东西的核心设计叫「四层渐进记忆」，不是简单地把对话往向量数据库里一塞就完事了。

**L0（原始对话）**：完整保留对话原文，以 Markdown 文件形式存在磁盘上，可直接打开查看。

**L1（原子记忆）**：从原始对话里提取关键事实片段，结构化存储，每次 L1 提取会同时做向量化和去重，避免重复记忆污染。

**L2（场景块）**：把同类原子记忆归并成场景块，以 Markdown 形式保存，人类可以直接读懂。

**L3（用户画像）**：在更宏观的层面归纳用户偏好、工作习惯、常用技术栈，存成 `persona.md`。

关键点在这里：**每上一层都有完整的下钻路径**。当你觉得 AI 回答有问题的时候，可以一路从 L3 persona → L2 场景 → L1 原子 → L0 原文，完整追溯到原始上下文，不是一个黑箱。

另一个重要设计是**符号记忆**。长任务里最费 Token 的是那些中间日志（搜索结果、代码片段、错误堆栈），这些东西被压缩成 Mermaid 图表留在上下文里，详细内容通过 `node_id` 索引到外部文件，按需读取。上下文只留几百个 token 的图表，实际 logs 可以是几十万 token。

---

## 二、架构是怎么跑的

Hermes 是个 Python Agent 框架，但这套记忆系统核心是 Node.js 写的。两边通过 HTTP 通信。

```
Hermes (Python)
  └─ memory_tencentdb Provider
       ├─ GatewaySupervisor  ─── 启动 + 健康检查 Node.js sidecar
       └─ MemoryTencentdbSdkClient ─── HTTP 调用 Gateway
            │
            ▼ 127.0.0.1:8420（默认）
       memory-tencentdb Gateway (Node.js)
          └─ 核心引擎
               ├─ L0 原始对话存储（SQLite + JSONL）
               ├─ L1 记忆提取（LLM + 向量去重）
               ├─ L2 场景块（Markdown）
               ├─ L3 用户画像（persona.md）
               └─ 存储后端：SQLite + sqlite-vec 或腾讯云向量数据库
```

数据存在哪？默认在 `~/.memory-tencentdb/memory-tdai/`，打开这个目录就能看到 L0/L1/L2/L3 各层的文件，调试起来非常方便。

---

## 三、安装方式（Hermes v0.3.4+）

### 第一步：确认 Hermes 版本

```bash
hermes --version
```

需要 **v0.3.4 或更高版本**。低于这个版本的先升级。

### 第二步：激活 memory provider

编辑 `~/.hermes/config.yaml`，加入：

```yaml
memory:
  provider: memory_tencentdb
```

注意这里用的是下划线 `memory_tencentdb`，不是中划线。这不是配置错误——这是 Hermes 的 provider 目录命名规范，目录名必须是下划线。

### 第三步：提供 LLM 凭证

记忆系统的 L1/L2/L3 提取需要调用 LLM，默认用 OpenAI 接口。设置环境变量：

```bash
export MEMORY_TENCENTDB_LLM_API_KEY="sk-xxx"
export MEMORY_TENCENTDB_LLM_BASE_URL="https://api.openai.com/v1"
export MEMORY_TENCENTDB_LLM_MODEL="gpt-4o"
```

如果你用腾讯云 LKE 的 DeepSeek，也可以：

```bash
export MEMORY_TENCENTDB_LLM_API_KEY="xxx"
export MEMORY_TENCENTDB_LLM_BASE_URL="https://api.lkeap.cloud.tencent.com/v1"
export MEMORY_TENCENTDB_LLM_MODEL="deepseek-v3.2"
export MEMORY_TENCENTDB_LLM_PROVIDER="custom"
```

### 第四步：启动 Gateway

Gateway 会由 Provider 自动启动（auto-discovery 模式），默认找 `src/gateway/server.ts` 这个路径。如果你的插件目录不在默认搜索路径里，需要手动指定：

```bash
export MEMORY_TENCENTDB_GATEWAY_CMD="node --import tsx /path/to/src/gateway/server.ts"
```

启动后，Provider 会自动等待 Gateway 的 `/health` 返回 ok，然后才正式接管记忆功能。

### 第五步：验证

```bash
curl http://localhost:8420/health
```

返回 `ok` 或 `degraded` 即可。

日志位置在 `~/.hermes/logs/memory_tencentdb/gateway.stderr.log`，启动出问题先看这个。

---

## 四、配置参数：从入门到进阶

插件设计者给了很合理的默认值，零配置也能跑起来。但如果想调优，分三个层级：

### Level 1：日常调优（覆盖 90% 使用场景）

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `storeBackend` | `sqlite` | 存储后端，暂时只支持 sqlite |
| `recall.strategy` | `hybrid` | 检索策略，推荐用 hybrid（RRF 融合） |
| `recall.maxResults` | `5` | 每次召回的记忆条数 |
| `pipeline.everyNConversations` | `5` | 每 N 轮对话触发一次 L1 提取 |
| `persona.triggerEveryN` | `50` | 每 N 条新记忆触发一次画像生成 |

### Level 2：长任务调优

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `pipeline.enableWarmup` | `true` | 新 session 从第 1 轮就开始触发 L1，后续翻倍（1→2→4→…） |
| `pipeline.l1IdleTimeoutSeconds` | `600` | 用户空闲多久后触发 L1 |
| `recall.timeoutMs` | `5000` | 召回超时时间，超时跳过不阻塞对话 |
| `capture.excludeAgents` | `[]` | 排除特定 agent 的 glob 模式（如 `bench-judge-*`） |
| `capture.l0l1RetentionDays` | `0` | L0/L1 本地文件保留天数，0 = 永不清理 |

### Level 3：完整参数

完整参数在项目根目录的 `openclaw.plugin.json` 里定义，包含了 embedding 服务配置、独立 LLM 运行模式、offload 后端等高级选项，适合自建 embedding 服务或接腾讯云向量数据库的用户。

---

## 五、踩坑记录

### 坑 1：版本不对，Provider 找不到

如果启动 Hermes 后日志里出现 `memory-tencentdb Gateway not available`，先确认 Hermes 版本是 **v0.3.4+**。低于这个版本没有 memory provider 机制。

另一个常见原因：Gateway 没有启动起来。看 `~/.hermes/logs/memory_tencentdb/gateway.stderr.log` 的具体报错信息。

### 坑 2：Provider 名字写错

配置里写 `memory-tencentdb` 会报错，必须写 `memory_tencentdb`（下划线）。原因：Hermes 的 provider 注册目录名是 `memory_tencentdb/`，系统按目录名查找 provider。

### 坑 3：LLM 凭证没配置，L1 提取卡住

Gateway 启动成功但 L1 提取没动静，很可能是 `MEMORY_TENCENTDB_LLM_API_KEY` 没设置。记系统需要 LLM 做记忆提取，没有凭证就卡在半路。

### 坑 4：中文分词问题

BM25 检索默认语言是 `zh`（jieba 分词），如果你做的是英文项目上下文，改成 `en` 效果更好。在 `bm25.language` 参数里设置。

---

## 六、和其他记忆方案的对比

| 方案 | 接入难度 | 长期记忆 | 短term压缩 | 白盒调试 | 数据存储 |
|------|---------|---------|-----------|---------|---------|
| **memory-tencentdb（本文）** | 低（内置 provider） | L0-L3 分层 | Mermaid 符号图 | ✅ 直接看文件 | SQLite + Markdown |
| mem0 | 中 | 平铺向量 | ❌ | 有限 | 云端 |
| retaindb | 中高 | 关系图谱 | ❌ | ❌ | 云端 |
| honcho | 中 | session 级 | ❌ | ✅ | 本地 |

如果你用 Hermes，想接入一套本地优先、分层、可调试的记忆系统，这套是目前最完整的方案。

---

## 写在最后

四层记忆架构加上符号压缩设计，这套方案的核心价值不在于「记住更多」，而在于「记住的都能追溯」。每次 AI 回答出问题，你都能找到完整的记忆链路，而不是对着一个黑箱向量相似度分数发呆。

对于跑长任务、长 session 的开发者来说，这种白盒调试能力比什么性能数字都实在。

**你在用 Hermes 吗？有没有遇到 session 断掉后 AI失忆的问题？评论区说说。**

---

## 评论区预置内容

自己改写比拿来主义靠谱
省了不少时间
max_turns 20 其实够用了
原来可以这样用

摘要

标签多个标签用逗号分隔

分类