10分钟给Agent加装本地记忆：OpenClaw实战

每次开启新的 Agent 对话，你是否都要把项目背景、团队规范、接口地址重新交代一遍？Agent 记不住你上周确认的偏好，也放不下昨天跑通的调试日志。反复输入相同的上下文不仅快速消耗 Token 额度，更严重影响开发效率。

问题的核心不在模型能力，而在于多数 Agent 框架的默认记忆机制过于扁平。今天带你实操一套近期活跃的开源方案——TencentDB-Agent-Memory。安装后，你的 OpenClaw Agent 将自动掌握跨对话的长期记忆能力，同时支持将冗长的长任务日志压缩为轻量级 Mermaid 流程图。官方实测上下文 Token 消耗可降低 61%，且全程基于本地运行，零外部 API 依赖。

环境准备

动手前请确认两项基础条件：

1. Node.js 版本不低于 22.16。项目底层依赖较新的运行时特性，旧版本无法兼容编译。
2. 已部署 OpenClaw 框架并验证基础对话功能正常。本文以 OpenClaw 为宿主环境构建记忆链路。

环境就绪后，直接跟随以下步骤接入。

步骤一：一键安装插件

打开终端运行原生安装指令：

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

项目维护方明确建议使用该指令完成安装与升级，切勿直接使用 npm 操作，避免语义版本冲突导致插件被意外禁用。重启 gateway 是为了让新加载的模块正式进入运行时进程。安装过程仅占用数十 MB 磁盘空间，完成后 OpenClaw 将自动挂载 memory-tencentdb 服务。

步骤二：零配置启动长期记忆

打开 OpenClaw 配置文件（通常位于 ~/.openclaw/openclaw.json），追加如下配置块：

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

保存配置后无需任何额外操作。插件默认内置 SQLite + sqlite-vec 作为本地存储后端，这意味着你不需要独立部署向量数据库，也不用申请任何云厂商 API Key。所有记忆数据将安全落地至本地文件系统。

启用后，Agent 会在后台自动运转记忆流水线：捕获原始对话记录（L0），按固定轮次提取原子事实与偏好（L1），逐步聚合为场景模块（L2），并定期生成用户画像（L3）。再次开启对话时，系统会按当前话题精准召回相关记忆并动态注入上下文。

步骤三：开启短期上下文压缩

处理长链路任务（如代码搜索、调试循环）时，工具执行日志极易撑爆上下文窗口。开启压缩功能可将冗余日志卸载至磁盘，仅在对话中保留轻量级任务结构图。

更新配置文件，追加 config 与路由声明：

{
  "memory-tencentdb": {
    "enabled": true,
    "config": {
      "offload": {
        "enabled": true
      }
    }
  },
  "plugins": {
    "slots": {
      "contextEngine": "memory-tencentdb"
    }
  }
}

配置生效后，执行运行时补丁脚本挂载消息钩子：

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

该补丁仅需在每次 OpenClaw 初始化安装时执行一次。升级宿主框架后需重新运行。它的核心作用是拦截工具调用产生的长日志，确保其能正确触发卸载与按需恢复逻辑。

验证与白盒调试

配置完成，需要通过实际对话确认流水线是否生效。

测试场景：首轮对话输入项目约定，等待系统完成 L1 提取后开启新会话进行验证。
首轮输入：“后端部署在 dev.example.com，API 前缀 /api/v2，统一返回格式 {"code": 0, "data": {}}，缩进使用 2 空格。”
次轮输入（新建会话后）：“帮我核对一下之前提到的接口地址和响应格式。”

若 Agent 准确复述了部署地址与规范，说明记忆召回已正常工作。此时可直接浏览 ~/.openclaw/memory-tdai/ 目录。内部按层级存放着原始对话、提取的原子记忆、场景聚合块与 persona 文件，全量为可读 Markdown 格式，支持白盒审查与精准溯源。

理解这套分层架构对后续调优至关重要：

• 短期任务：Mermaid 画布（概要）→ JSONL（步骤摘要）→ refs/*.md（原始日志），按需下钻读取。
• 长期记忆：L0 → L1 → L2 → L3，从碎片信息逐步抽象为结构化画像。
  Agent 仅在需要细节时通过 node_id 加载对应节点，兼顾了上下文效率与可审计性。

常见问题排查

插件升级后失效：务必使用 openclaw plugins update @tencentdb-agent-memory/memory-tencentdb 更新。npm update 可能破坏版本约束导致模块停用。
补丁脚本报权限错误：执行前添加 chmod +x 赋予可执行权限。
召回准确率不足：默认采用 BM25 + 向量的混合检索策略。若匹配出现偏差，可将 retrieval.strategy 切换为 keyword 进行纯关键词匹配。长文档场景可适当调大 recall.maxResults 阈值。
接入远程向量库：支持切换至腾讯云向量数据库。同步配置 llm.* 字段即可将提取流水线交由远程模型处理，满足不同规模的存储需求。

接下来可以探索的方向

本次实战完成了从安装、零配置启用到上下文压缩的全流程。核心目标已达成：让 Agent 记住该记的，开发者专注核心逻辑。后续可尝试调节 pipeline.everyNConversations 控制提取频率，观察 memory-tdai 目录内文件随对话推进的演变过程，或针对特定业务场景定制召回策略。遇到边界情况可在仓库提交 Issue，社区活跃度高，反馈响应迅速。