编辑文档 - 我拆了 TencentDB Agent Memory 的架构，发现它和 OpenCode、Hermes 可以这样组合

标题

工具栏

点击或拖拽上传图片

支持 PNG, JPG, GIF, WebP 格式

内容 (Markdown 格式)

# 我拆了 TencentDB Agent Memory

**作者：小创** 的架构，发现它和 OpenCode、Hermes 可以这样组合

---

上下文爆炸，是所有长程 Agent 的噩梦。

跑了 50 个任务之后，Token 消耗轻轻松松破千万，Agent 开始出现「失忆」症状——前面刚记住的偏好，后面完全不认识了。传统的解法是把历史全部塞进向量数据库，但扁平的向量堆砌召回效果差，而且「压缩即丢失」，调试起来跟开盲盒一样。

腾讯开源的 **TencentDB Agent Memory** 给出了一条不同的路：**分层记忆 + 符号化压缩**，Token 消耗降低 61%，通过率相对提升 51%。今天小创把它的架构拆透，聊一聊和 OpenCode、Hermes 组合落地的可能性。

---

## 一、核心设计：拒绝平铺，走向分层与符号化

Agent Memory 的设计哲学围绕两个关键词：**记忆分层** 和 **符号化记忆**。

### 1. 记忆分层：L0 → L3 语义金字塔

传统记忆系统把数据切片后平铺成向量，召回时就像在一堆毫无关联的便利贴里找线索。Agent Memory 认为——**不管是长期知识、短期任务还是未来经验，记忆都不应该平铺，生成和召回都必须有层次**。

它的分层结构长这样：

| 层级 | 名称 | 内容 | 用途 |
|------|------|------|------|
| **L0** | Conversation | 原始对话记录 | 需要考证细节时回溯 |
| **L1** | Atom | 结构化事实片段 | 需要精确事实时召回 |
| **L2** | Scenario | 场景块（Markdown） | 高密度理解用户当前场景 |
| **L3** | Persona | 用户画像 | 把握长期偏好和习惯 |

> 关键是：每一条信息都可以**完整溯源**。L3 的 Persona 可以追到对应的 L2 Scenario → L1 Atom → L0 Conversation。不存在「不可逆的压缩」。

### 2. 符号化记忆：Mermaid 画布降 Token

长程任务中最消耗 Token 的，是繁杂的过程日志（搜索结果、代码、报错）。Agent Memory 提出了**符号化记忆**：

1. 完整工具日志被**卸载**到外部文件系统（`refs/*.md`）
2. 上下文仅保留轻量级的 **Mermaid 任务地图**（带 `node_id`）
3. Agent 看着 Mermaid 推理，如需核对细节，直接用 `node_id` 找回完整原文

降 Token 效果是实打实的：

| Benchmark | 原通过率 | 加插件后 | 变化 | 原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% | - | - | - |

> 超长 Session 评测是把多个任务拼接到同一个 Session 中连续执行，SWE-bench 每个 Session 连续执行 50 个任务，模拟真实长程 Agent 的上下文累积压力。

---

## 二、它能干什么？和 OpenCode/Hermes 组合的落地场景

### 场景 1：OpenCode + Agent Memory = 记住你的项目习惯

OpenCode 是一个代码智能体，每次新项目都要重新解释：
- 项目结构是怎样的
- 输出格式偏好（PR 规范、commit message 风格）
- 常用的技术栈和工具

接入 Agent Memory 后，这些信息会被**逐轮沉淀**，最终形成一个 L3 Persona。下次开新项目，Agent 直接从记忆里读你的偏好，不需要重新解释。

```bash
# OpenClaw 接入方式
openclaw plugins install @tencentdb-agent-memory/memory-tencentdb
openclaw gateway restart
```

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

零配置，开箱即用。默认用本地 `SQLite + sqlite-vec` 后端。

---

### 场景 2：Hermes + Agent Memory = 有记忆的长程任务执行

Hermes 本身是一个多功能的 AI Agent 网关，接入 Agent Memory 后能解决长程任务的「失忆」问题。

比如：跑一个需要 50 步的代码重构任务，中途断了。传统 Agent 需要从头开始；有 Agent Memory 之后，Agent 可以从上次中断的地方继续，并且理解「之前为什么这样做」。

```bash
# Hermes Docker 模式
docker build -f Dockerfile.hermes -t hermes-memory .

docker run -d \
  --name hermes-memory \
  --restart unless-stopped \
  -p 8420:8420 \
  -e MODEL_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
```

> 镜像内置腾讯云 DeepSeek-V3.2 默认值，使用该模型时 `MODEL_BASE_URL` / `MODEL_NAME` / `MODEL_PROVIDER` 都可以省略。

---

### 场景 3：三层记忆联动 = 让 Agent 从「工具」变成「助手」

| 记忆层级 | 在 OpenCode/Hermes 中的作用 |
|----------|---------------------------|
| **L3 Persona** | 理解「你是谁，你习惯怎么工作」 |
| **L2 Scenario** | 理解「当前在做什么项目，用什么技术栈」 |
| **L1 Atom** | 召回具体的技术细节和历史决策 |
| **Mermaid 画布** | 长任务中实时跟踪进度，中断后可恢复 |

**本质区别**：没有 Agent Memory 的 Agent，每次对话都是「陌生人」；有了之后，每次对话是「认识你的助手」。

---

## 三、部署需要什么机器配置？

这个问题官方文档没有给具体的配置表，但小创根据架构做了推算，先说结论：

### 最小化部署（单节点，尝鲜体验）

| 组件 | 配置 | 说明 |
|------|------|------|
| **Gateway（Node 服务）** | 1核 / 1GB | 无状态 HTTP sidecar，很轻 |
| **SQLite 本地存储** | 5-10GB SSD | L0-L3 语义文件 + sqlite-vec 向量 |
| **Node 版本** | >= 22.16 | 硬性要求 |
| **内存余量** | 建议 2GB+ | LLM 调用时 Embedding 模型会吃内存 |

### 生产级部署（多用户、多 Agent）

| 组件 | 配置 | 说明 |
|------|------|------|
| **Gateway** | 2-4核 / 2-4GB | 并发多个 Agent 请求时需要 |
| **向量数据库（可选）** | 腾讯云 VDB | 如用远程向量库，本地压力更小 |
| **Embedding 服务** | 独立调用 | OpenAI 兼容 API，或腾讯云 bge-large-zh |
| **LLM 服务** | 独立调用 | 可以是 OpenAI / DeepSeek / 腾讯云等 |
| **存储** | 50GB+ SSD | 长程会话日志会积累，建议定期归档 |

### 关键依赖

1. **Node >= 22.16** - 这是硬性要求，低版本跑不起来
2. **Python3** - 运维脚本依赖（`memory-tencentdb-ctl.sh`）
3. **npx** - 用于启动 Gateway
4. **LLM API Key** - 你需要有 OpenAI / DeepSeek 或其他兼容 API 的访问权限
5. **Embedding API** - 可选（默认用 BM25 召回），如启用需要 OpenAI 兼容的 embedding 服务

### 网络要求

- Gateway 默认监听 `127.0.0.1:8420`，仅本地访问
- 如用腾讯云 VDB，需要能访问 `http://xxx-vdb.tencentclb.com:8100`
- 如用远程 LLM/Embedding，需要能访问对应 API 端点

---

## 四、架构亮点：白盒可调试

这是小创觉得 Agent Memory 最有价值的设计细节之一——**记忆不是黑盒向量**。

传统的记忆系统：召回错了，只能看到一串向量分数，不知道哪里出了问题。

Agent Memory 的调试路径：

```
L3 Persona.md → L2 Scenario.md → L1 Atom/*.jsonl → L0 refs/*.md
```

所有中间产物都是可读文件：
- L2 Scenario 是 Markdown，直接打开检查
- L3 Persona 存放在 `persona.md`，可以追溯到对应的 Scenario
- 短期任务画布是 Mermaid，人能看，Agent 也能读
- 原文、摘要、`node_id` 之间有 `result_ref` 关联

> 这些分层记忆产物都存放在 `~/.openclaw/memory-tdai/` 下，可以直接打开目录逐层查看。

这对开发者来说意味着：出了问题不用靠「直觉」猜，直接翻文件定位。

---

## 五、和 OpenCode / Hermes 的本质区别

很多人会问：既然 OpenCode 和 Hermes 本身已经有 Agent 能力，Agent Memory 的价值在哪里？

| 对比维度 | OpenCode / Hermes | Agent Memory |
|----------|-------------------|--------------|
| **定位** | Agent 执行框架 | 记忆与上下文管理层 |
| **解决的问题** | 「怎么做」 | 「记得什么、怎么记、怎么召回」 |
| **上下文处理** | 长程对话时 Token 持续膨胀 | 分层卸载 + 符号压缩 |
| **记忆能力** | 无（每次都是新对话） | L0-L3 分层 + 可溯源 |
| **适用场景** | 单次任务执行 | 长程、多会话、项目级协作 |

> 简单说：**OpenCode/Hermes 决定 Agent 做什么，Agent Memory 决定 Agent 记住什么**。两者是互补关系，不是替代关系。

---

## 六、落地建议

### 入门（OpenClaw 插件模式）

如果你是 OpenClaw 用户，直接装插件，零配置体验：

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

默认 SQLite 后端，不需要额外基础设施。

### 进阶（Hermes 集成模式）

如果你用 Hermes，希望记忆跨 session 持久化：

```bash
# 构建带记忆的 Hermes 镜像
docker build -f Dockerfile.hermes -t hermes-memory .

# 启动，记得挂载数据卷
docker run -d \
  --name hermes-memory \
  --restart unless-stopped \
  -p 8420:8420 \
  -e MODEL_API_KEY="你的KEY" \
  -v hermes_data:/opt/data \
  hermes-memory

# 启用 hermes memory provider
memory-tencentdb-ctl --hermes enable-hermes-memory
```

### 生产环境（按需开启向量库）

如果用户量上去，SQLite 向量召回性能不够，可以切换到腾讯云 VDB：

```bash
memory-tencentdb-ctl config vdb \
  --url "http://xxx-vdb.tencentclb.com:8100" \
  --api-key "YOUR-VDB-API-KEY" \
  --database "openclaw_memory" \
  --embedding-model "bge-large-zh" \
  --restart
```

---

## 写在最后

TencentDB Agent Memory 解决的不是「Agent 怎么干活」的问题，而是「Agent 怎么记住干活的方式」的问题。

这对长程任务、多会话协作、项目级上下文管理来说，是本质性的提升。结合 OpenCode 的代码执行能力和 Hermes 的多场景调度能力，三者组合能形成一个**有记忆、能进化、懂你习惯**的智能体系统。

现在还处于早期阶段（Roadmap 还有 Skill 自动生成、可视化调试面板），但核心架构已经跑通。如果你也在做 Agent 相关的事情，值得关注。

**你在用 Agent Memory 吗？或者对多 Agent 协作有什么想法？评论区聊聊。**

---

## 评论区预置内容

分层记忆这个设计思路很清晰
自己改写比拿来主义靠谱
省了不少时间
原来可以这样用

摘要

标签多个标签用逗号分隔

分类