TencentDB Agent Memory 本地部署教程：长期记忆、日志压缩与可追溯召回

本地 Agent 经常遇到两类相反的问题：会话一长，工具日志和上下文迅速挤满 token；会话一断，又要重新解释项目约定、偏好和已完成的工作。TencentDB Agent Memory 尝试把这两件事拆开处理：短期任务把冗长日志卸载并压缩，长期记忆把对话逐层整理为可召回的信息，同时保留回到原始证据的路径。项目官方仓库

它并不是把全部聊天记录塞回提示词，而是使用“原始记录 → 原子事实 → 场景 → Persona”的长期记忆层次；短期侧则把工具输出保留在文件中，以 Mermaid 任务图和 node_id 提供精简上下文与回溯入口。适合本地 Agent、OpenClaw、Hermes 及希望接入 OpenAI 兼容模型端点的场景。

部署前先决定：你要解决哪一类记忆问题

先把目标写清楚，配置会简单很多：

目标	优先启用的能力	先验证什么
跨会话记住项目约定和用户偏好	长期记忆与召回	是否能在下一轮正确找回历史事实
长任务中工具日志太长	短期 offload 与符号记忆	原始日志是否可通过 `node_id` 回溯
本地运行且不想依赖外部记忆 API	SQLite + sqlite-vec 默认后端	数据目录、备份和权限是否可控
用 Ollama 或其他本地模型	OpenAI 兼容 Gateway 配置	容器/宿主机能否访问模型端点

不要一开始就打开全部功能。建议先完成长期记忆的写入与召回，再开启工具日志压缩；这样出现遗漏时，才容易判断是模型、检索、压缩还是网络路径的问题。

方案一：给 OpenClaw 加上本地长期记忆

官方 README 提供的 OpenClaw 路径最短。插件默认使用本地 SQLite + sqlite-vec，不需要外部记忆 API：

1
2


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

在 ~/.openclaw/openclaw.json 中启用插件：

1
2
3
4
5


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

启用后，插件会负责捕获对话、抽取记忆、聚合场景、生成 Persona，并在下一轮前执行召回。此时先做一个小验证：连续完成几轮有明确事实的对话，重开会话后询问其中一个细节，确认 Agent 返回的是已保存事实，而不是自行猜测。

如果你还没有准备好本地模型服务，可先从 Codex 本地大模型接入 Ollama 的排错顺序检查服务、模型名称和运行环境是否对齐。

按需打开短期日志压缩

长任务中最容易膨胀的是搜索结果、命令输出和错误日志。TencentDB Agent Memory 的 offload 会把完整工具日志写到外部文件，只将带 node_id 的精简 Mermaid 状态图放进上下文；需要细节时，Agent 可以再沿 node_id 找回原始文本。

OpenClaw 的官方示例要求版本不低于 0.3.4。先开启 offload：

1
2
3
4
5
6
7
8
9


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

再注册 context engine 槽位：

1
2
3
4
5
6
7


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

最后执行项目提供的补丁，使 after-tool-call 消息能够被正确卸载和恢复：

1

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

OpenClaw 升级后需要重新应用这个补丁。上线前用一次包含多轮工具调用的任务验证两件事：上下文是否变短，以及失败时能否从 Mermaid 图的 node_id 回到对应原始日志。只有同时满足，压缩才没有牺牲排障能力。

方案二：用 Docker 启动 Hermes Memory Gateway

如果你使用 Hermes，官方 Docker 镜像会将 hermes-agent 与 memory_tencentdb provider 一起构建，Gateway 默认监听 8420。在仓库根目录执行：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


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

启动后先检查健康状态：

1

curl http://localhost:8420/health

返回 {"status":"ok"} 或 {"status":"degraded"} 说明 Gateway 已启动；degraded 时不要直接投入长期任务，应先检查模型连接、存储卷与日志。

与 Ollama 对接时的正确边界

项目的 MODEL_PROVIDER="custom" 用于 OpenAI 兼容端点。Ollama 提供兼容接口时，可以作为该 Gateway 的模型来源；但“记忆存储在本地”与“模型也完全本地”是两件不同的事，分别验证。

在 Docker 中连接宿主机 Ollama 前，先确认端点可达。Windows/macOS Docker Desktop 通常可使用 host.docker.internal；Linux 则需要按 Docker 网络方式配置宿主机网关。示意配置如下，具体模型名以你本机已拉取的模型为准：

1
2
3
4


MODEL_API_KEY="ollama"
MODEL_BASE_URL="http://host.docker.internal:11434/v1"
MODEL_NAME="qwen3"
MODEL_PROVIDER="custom"

先在相同网络位置测试 /v1/models 或完成一个最小聊天请求，再启动长期记忆任务。若容器里把 localhost 写成模型地址，实际指向的是容器自身，而不是运行 Ollama 的宿主机，这是最常见的连接错误。

有关 OpenAI 兼容本地 API、Ollama、LM Studio 和 vLLM 的端点检查，可继续阅读本地大模型 API 给 Codex 使用教程。

可追溯性为什么比“自动总结”更重要

不可逆总结看似节省 token，却可能把一个关键条件、失败原因或用户限制丢掉。这个项目将高层信息与底层证据保持关联：

1
2
3
4
5


Persona / Mermaid canvas
        ↓
Scenario / jsonl 索引
        ↓
原始对话与工具日志（L0 / refs/*.md）

排查时不要只看最终摘要。若 Agent 记错了偏好或误判任务状态，应沿这条链路回到原始日志，判断是抽取错误、召回排序错误，还是原始输入本来就不完整。把原始资料、记忆索引和配置文件一起纳入备份，才能在迁移或升级时保留这种可验证性。

基础安全与运维检查

Hermes Gateway 暴露 capture、search、recall 等 HTTP 接口。官方默认按本地 sidecar 使用；如果要绑定非回环地址或让其他机器访问，必须加认证和来源限制。

1
2
3


export TDAI_GATEWAY_API_KEY="replace-with-a-long-random-secret"
export TDAI_CORS_ORIGINS="https://your-console.example"
export MEMORY_TENCENTDB_GATEWAY_API_KEY="$TDAI_GATEWAY_API_KEY"

然后确认 Gateway 与插件两侧使用同一个密钥。不要把 8420 端口直接暴露到公网，也不要把 API key、记忆数据库或 refs/*.md 一并提交进 Git。

建议把下面几项纳入日常检查：

为 SQLite 数据、挂载卷和记忆目录建立定期备份与恢复演练。
记录插件、OpenClaw/Hermes、模型和 Docker 镜像版本，升级后先在测试会话验证召回。
限制单次召回数量和注入字符预算，避免“记忆越多，上下文越重”。
定期抽查高层 Persona 是否包含过期或敏感信息，并按自己的数据规则清理。

常见问题

插件启用了，为什么 Agent 还是记不住？

先确认是跨会话问题，而不是当前对话未完成。再检查插件是否已启用、记忆抽取触发频率、存储目录是否可写，以及下一轮召回是否因超时被跳过。不要只用一句模糊问题测试，最好用可验证的项目约定或事实。

开启 offload 后，是否再也看不到原始日志？

不是。offload 的目标是把完整日志移出主上下文，而不是删除它。应通过 node_id、索引和 refs/*.md 回溯原始记录；若无法回溯，应停止将其用于重要任务并先修复存储路径或权限。

Ollama 接不上 Gateway，最先检查什么？

先区分宿主机和容器网络。容器中的 localhost 不等于宿主机；再确认 Ollama 服务、模型名称、OpenAI 兼容 URL、端口和防火墙。用最小接口请求连通后，再排查记忆插件本身。

小结

TencentDB Agent Memory 适合需要长期运行、又希望保持本地可控和可追溯的 Agent 工作流。先用默认 SQLite 后端跑通长期记忆，再按需开启日志 offload；本地模型接入则单独验证网络与 OpenAI 兼容端点。这样既能减少重复解释，也不会在压缩后失去定位问题的原始证据。