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

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 启用：

1
2
3
4
5


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

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

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

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

1
2
3


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

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

启用短期日志压缩（offload）

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

在插件配置中打开：

1
2
3
4
5
6
7
8
9


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

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

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 安装只需运行一次；OpenClaw 升级后，需要重新应用。

可追溯检索如何工作

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

1
2
3
4
5


完整工具日志 → 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 能否回到原始日志。这样得到的是可审计的本地记忆系统，而不是不可解释的自动摘要。