TencentDB-Agent-Memory 本地部署指南

一、插件概述

tencentdb-agent-memory 是腾讯云数据库团队开源的记忆插件，为 OpenClaw 提供对话记忆能力。采用本地 SQLite + sqlite-vec 后端，零外部依赖、零配置即可运行。

二、安装步骤

Step 1：安装插件

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

预期输出：

下载并提取完成
安装到 ~/.openclaw/extensions/memory-tencentdb
依赖包已安装
插件已注册 (memory-tdai)
配置文件已更新（备份到 openclaw.json.bak）

Step 2：重启 Gateway 生效

openclaw gateway restart

等待 10~30 秒，确认 Gateway 状态恢复「运行中/健康」。

三、本地配置（零依赖模式）

安装完成后，配置文件 ~/.openclaw/openclaw.json 会自动生成基础配置：

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

推荐完整配置（优化召回质量）

{
  "memory-tencentdb": {
    "enabled": true,
    
    // 记忆提取配置
    "extraction": {
      "enabled": true,
      "enableDedup": true,              // 防重复记忆
      "maxMemoriesPerSession": 30,      // 单次对话最多存 30 条
      "model": ""                        // 留空复用 OpenClaw 默认模型
    },
    
    // 管线节奏
    "pipeline": {
      "everyNConversations": 3,         // 每 3 轮对话触发提炼
      "enableWarmup": true,             // 新对话从第 1 轮开始
      "l1IdleTimeoutSeconds": 60,       // 停嘴 60 秒后触发提炼
      "l2DelayAfterL1Seconds": 120      // L1 完后 2 分钟归纳场景块
    },
    
    // 召回配置（影响"能不能想起"）
    "recall": {
      "enabled": true,
      "strategy": "hybrid",             // keyword + embedding 融合
      "maxResults": 8,                  // 每次注入最多 8 条记忆
      "scoreThreshold": 0.25,           // 阈值略调低，避免"啥都想不起来"
      "timeoutMs": 5000
    },
    
    // Embedding：本地用 BM25，资源充裕可配远端
    "embedding": {
      "enabled": true,
      "provider": "none"                // 默认用 SQLite 内置 BM25
      // 如需远端 Embedding，替换为：
      // "provider": "openai",
      // "baseUrl": "https://your-embedding-endpoint/v1",
      // "apiKey": "sk-xxx",
      // "model": "text-embedding-3-small",
      // "dimensions": 1536
    },
    
    // 自动清理旧日志
    "clean": {
      "enabled": true,
      "keepDays": 30,                   // L0 原始日志保留 30 天
      "cleanTime": "03:00"
    }
  }
}

修改后重启生效：

openclaw gateway restart

四、关键补丁（工具调用支持）

执行 patch 脚本确保工具调用结果能被正确记录：

cd ~/.openclaw/extensions/memory-tencentdb
bash scripts/openclaw-after-tool-call-messages.patch.sh
openclaw gateway restart

如果脚本不存在（版本差异）可跳过，基础对话内容仍会正常记录。

五、上下文保护配置

在 openclaw.json 中添加以下配置，防止长对话中近期决策被压缩覆盖：

{
  "agents": {
    "defaults": {
      "memoryFlush": {
        "enabled": true,
        "reserveTokensFloor": 40000,
        "softThresholdTokens": 4000
      },
      "contextPruning": {
        "mode": "cache-ttl"
      }
    }
  }
}

六、验证安装

检查插件状态

# 查看插件列表
openclaw plugins list
# 应显示 memory-tencentdb ✓ enabled

# 查看 Gateway 状态
openclaw gateway status
# 应显示 Gateway 健康

功能验证

1. 训练阶段：

   你：我叫阿杰，最讨厌回复里带emoji，我写代码只用FastAPI
   （等待确认"已记下"）
   

2. 测试阶段（新对话或重启后）：

   你：我叫什么？我用啥框架？我讨厌什么？
   

   若能准确回答 → 记忆管线正常工作。

七、问题排查

八、进阶优化（可选）

Soul File 配置（让 Agent 更懂你）

在 ~/.openclaw/workspace/ 下创建以下文件：

SOUL.md（身份和原则）：

## 身份
你叫小龙虾，是我的个人 AI 助手。
气质：干脆利落、不废话、有执行力。

## 原则
1. 不知道就说不知道，不编造
2. 删除/发送/花钱类操作必须先确认
3. 先给结果，再给过程
4. 用户告知偏好时，回复确认"已记下"
5. 用中文思考，回复口语化

USER.md（用户偏好）：

## 基本信息
- 名字：[你的名字]
- 职业：[你的职业]
- 常用技术栈：[技术栈]

## 偏好
- 回复风格：分点 > 段落，要可执行
- 代码风格：[偏好的风格]

总结：本地部署只需执行安装命令，插件默认使用 SQLite 后端即可工作。通过调整 recall 和 pipeline 配置可优化记忆召回质量，配合 Soul File 配置能让 Agent 更贴合个人需求。