TencentDB Agent Memory on KnightLi的博客

TencentDB Agent Memory 怎么接入 OpenClaw：本地长期记忆、日志压缩与可追溯检索

Wed, 15 Jul 2026 22:08:00 +0800

OpenClaw 的长任务一旦跨越多轮工具调用，通常会出现两个问题：上下文被日志塞满，或新会话又要重新解释项目约定。TencentDB Agent Memory 为 OpenClaw 提供本地长期记忆和短期日志压缩：默认使用 SQLite + sqlite-vec，将长期信息分层整理；启用 offload 后，把完整工具输出保存到外部文件，仅向上下文注入精简的符号化状态。项目官方仓库

本文只处理 OpenClaw 接入。关键目标不是“让 Agent 记住一切”，而是让它在需要时能找回事实，并让你能从高层摘要追溯到原始对话或工具日志。

安装前先确认两件事

当前 OpenClaw 已能正常启动和执行基本对话；先解决模型、权限或 Gateway 问题，再加记忆插件。
你清楚本机数据的备份位置和访问边界。记忆里可能包含项目上下文、任务记录和工具输出，不应把它当作临时无关缓存。

初次接入建议先只启用长期记忆，确认召回正确后再启用日志压缩。这样一旦出现错误，能明确判断是记忆抽取、检索还是 offload 配置造成的。

安装并启用插件

使用 OpenClaw 原生插件命令安装：

1
2

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

后续升级也应使用 OpenClaw 的插件更新命令，避免语义版本范围导致插件被禁用：

`1`	`openclaw plugins update @tencentdb-agent-memory/memory-tencentdb`

在 ~/.openclaw/openclaw.json 启用：

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

官方 README 说明，默认后端是本地 SQLite + sqlite-vec。启用后，插件会捕获对话、抽取记忆、聚合场景、生成 Persona，并在下一轮前做召回；它不需要为记忆功能额外调用外部 API。

用一组可验证事实测试长期记忆

不要仅问“你还记得我吗”。请做一个有答案、可复查的测试：

1
2
3

第 1 轮：告诉 Agent 当前项目的包管理器、测试命令和一条明确的输出约定。
第 2 轮：让它执行一个与这些约定相关的小任务。
新会话：询问测试命令和输出约定，并要求说明信息来源或不确定项。

通过标准不是它背出了更多内容，而是它能正确找回事实、不擅自补充不存在的信息。如果项目约定已经改变，应更新或清理旧记忆，而不是期待模型自动判断哪一条过期。

启用短期日志压缩（offload）

工具输出、搜索结果和错误栈通常是长任务 token 膨胀的主要来源。项目的 offload 功能会把完整日志移到外部文件，将压缩后的 Mermaid 状态图留在上下文中。官方要求 OpenClaw 与插件版本不低于 0.3.4。

在插件配置中打开：

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

然后注册 context engine 槽位，让 OpenClaw 将 context-offload 请求交给该插件：

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

最后运行项目提供的补丁，使 after-tool-call 消息可被卸载和恢复：

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

该补丁对每个 OpenClaw 安装只需运行一次；OpenClaw 升级后，需要重新应用。

可追溯检索如何工作

日志压缩不应该等于丢失细节。TencentDB Agent Memory 的短期链路是：

完整工具日志 → refs/*.md
              ↓
步骤摘要 → jsonl 索引
              ↓
Mermaid 状态图（带 node_id）→ 注入 Agent 上下文

当 Agent 或你需要核实某个结论时，可沿 node_id 从 Mermaid 状态图找到对应摘要和原始日志。长期记忆也遵循类似的下钻关系：Persona → Scenario → Atom → Conversation。因此，排查“为什么 Agent 记错了”时，应先回到原始证据，而不是只修改最终摘要。

启用后应该做的三项验收

长期召回：新会话中正确找回一条测试事实，并能承认不确定项。
日志回溯：执行一段多工具调用任务，确认压缩后仍能通过 node_id 找到原始输出。
失败保护：故意让一个工具调用失败，检查错误信息、原始日志和下一轮恢复是否仍可理解。

如果只看到上下文变短，却不能追溯原始信息，不应将 offload 用于重要生产任务。压缩的前提是可恢复，而不是减少 token 本身。

配置与数据的安全边界

默认本地存储并不意味着可以忽略安全。建议：

将记忆数据目录纳入加密备份与恢复演练。
不要在对话、工具日志或 Persona 中放入不应长期保存的密钥。
更新 OpenClaw 或插件后，先用测试会话确认记忆抽取、召回与 offload 没有退化。
定期检查旧 Persona、场景和项目约定，清除已过期或敏感的信息。

如需同时部署 Hermes、Docker Gateway 或 OpenAI 兼容本地模型，可阅读 TencentDB Agent Memory 本地部署总览。

常见问题

启用后还是忘记项目约定，先查哪里？

先确认插件已启用、Gateway 已重启、测试是否真的跨越新会话；再检查记忆抽取的触发时机与存储目录权限。不要用模糊描述测试，使用可验证的命令、路径或输出约定。

offload 后为什么看不到完整日志？

完整日志应被保存到 refs/*.md 等外部记录，不再全部注入上下文。通过 Mermaid 图中的 node_id 和摘要索引回溯；若文件不存在或无法读取，先排查路径、权限和补丁是否已正确应用。

是否必须启用 offload？

不是。短任务或调试初期可以只使用长期记忆。只有当工具输出确实造成上下文膨胀，并且你已验证回溯链路完整时，再开启 offload。

小结

接入 TencentDB Agent Memory 的安全顺序是：先安装并启用 OpenClaw 插件，用可验证事实测试长期召回，再按需打开 offload、注册 context engine、应用补丁，最后检查 node_id 能否回到原始日志。这样得到的是可审计的本地记忆系统，而不是不可解释的自动摘要。

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

Wed, 15 Jul 2026 22:00:00 +0800

本地 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 中启用插件：

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

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

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

按需打开短期日志压缩

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

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

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

再注册 context engine 槽位：

{
  "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。在仓库根目录执行：

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 网络方式配置宿主机网关。示意配置如下，具体模型名以你本机已拉取的模型为准：

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，却可能把一个关键条件、失败原因或用户限制丢掉。这个项目将高层信息与底层证据保持关联：

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 兼容端点。这样既能减少重复解释，也不会在压缩后失去定位问题的原始证据。