openclaw-memory-tencentdb-setup

name	openclaw-memory-tencentdb-setup
description	用于在 OpenClaw 环境中安装、配置并验证 @tencentdb-agent-memory/memory-tencentdb 插件。当用户提到"安装记忆插件""配置 memory-tencentdb""开启长期记忆/召回"或出现相关报错时应触发。
version	1.0.0

目的

在不依赖外部托管记忆服务的前提下，为 OpenClaw 提供可持续的本地长期记忆能力（L0→L1→L2→L3），并完成从安装、配置到验收的一次性闭环。

适用场景

• 用户要求在 OpenClaw 中安装或启用 memory-tencentdb
• 用户需要配置召回、提取、画像、清理等参数
• 用户反馈"插件已装但无记忆 / 无召回 / 无向量检索"

不适用场景

• 用户只需要解释 memory 理念，不要求实际落地
• 用户要接入非 OpenClaw 宿主（先确认目标框架）

标准工作流

1) 环境预检

先确认基础版本满足要求：

• OpenClaw: >= 2026.3.13
• Node.js: >= 22.16.0

执行：

openclaw --version
node -v

若版本不满足，先升级再继续。

2) 安装插件

执行安装命令：

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

如已安装则执行更新：

openclaw plugins update memory-tencentdb

3) 写入最小配置

编辑 ~/.openclaw/openclaw.json，确保存在：

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

说明：该插件支持零配置启动；不补充其它字段也能运行基础能力。

4) 按需追加推荐配置（生产常用）

根据用户需求补充如下分组：

• capture: 对话捕获与保留策略
• extraction: L1 提取与去重
• pipeline: L1→L2→L3 调度
• recall: 召回数量、阈值、策略
• persona: 场景与画像触发参数
• embedding: 向量检索配置（远端 OpenAI 兼容）

推荐模板：

{
  "memory-tencentdb": {
    "capture": {
      "enabled": true,
      "excludeAgents": [],
      "l0l1RetentionDays": 90,
      "cleanTime": "03:00"
    },
    "extraction": {
      "enabled": true,
      "enableDedup": true,
      "maxMemoriesPerSession": 10,
      "model": "provider/model"
    },
    "pipeline": {
      "everyNConversations": 5,
      "enableWarmup": true,
      "l1IdleTimeoutSeconds": 600,
      "l2DelayAfterL1Seconds": 10,
      "l2MinIntervalSeconds": 900,
      "l2MaxIntervalSeconds": 3600,
      "sessionActiveWindowHours": 24
    },
    "recall": {
      "enabled": true,
      "maxResults": 5,
      "scoreThreshold": 0.3,
      "strategy": "hybrid"
    },
    "persona": {
      "triggerEveryN": 50,
      "maxScenes": 15,
      "backupCount": 3,
      "sceneBackupCount": 10,
      "model": "provider/model"
    },
    "embedding": {
      "enabled": true,
      "provider": "openai",
      "baseUrl": "https://api.openai.com/v1",
      "apiKey": "${EMBEDDING_API_KEY}",
      "model": "text-embedding-3-small",
      "dimensions": 1536,
      "conflictRecallTopK": 5
    }
  }
}

5) 关键配置规则（避免隐性失败）

• embedding.provider = "none" 时，向量能力会禁用，仅保留关键词路径。
• 若配置远端 provider（如 openai / deepseek），必须同时提供：
  • apiKey
  • baseUrl
  • model
  • dimensions
• 上述任一缺失时，插件会继续运行，但自动降级为非向量模式。
• l0l1RetentionDays：
  • 0 表示不清理
  • 非 0 时建议 >=3
  • 若设为 1~2，需显式开启 allowAggressiveCleanup

6) 重启并验证生效

执行：

openclaw gateway restart

检查项：

• Gateway 日志中出现 [memory-tdai] 前缀
• 数据目录已创建：~/.openclaw/state/memory-tdai/
• 至少包含：conversations/、records/、scene_blocks/、vectors.db

7) 功能冒烟测试

执行一次最小对话回路并验证：

1. 连续对话 2~3 轮，提供可记忆信息（偏好、约束、背景）。
2. 发起新一轮对话，观察是否出现召回上下文注入。
3. 在 Agent 中调用：
   • tdai_memory_search
   • tdai_conversation_search
4. 确认能检索到刚刚产生的内容。

故障排查速查

• 插件无日志：检查 openclaw.json 中 memory-tencentdb.enabled 是否为 true，并确认已重启 Gateway。
• 有记录无召回：检查 recall.enabled、scoreThreshold 是否过高。
• 无向量结果：检查 embedding 四元组（apiKey/baseUrl/model/dimensions）是否齐全。
• 清理过猛导致历史过少：检查 l0l1RetentionDays 与 allowAggressiveCleanup。
• 配置已改但行为不变：确认修改的是 ~/.openclaw/openclaw.json，并再次重启 Gateway。

安全与合规约束

• 将 apiKey 视为敏感信息；不在聊天、日志、截图中明文扩散。
• 优先使用环境变量注入密钥；配置示例中仅保留占位符。
• 仅修改 memory-tencentdb 对应配置段，避免覆盖用户其它插件配置。

完成定义（Definition of Done）

在结束任务前，必须同时满足：

• 插件安装/更新命令执行成功
• openclaw.json 已存在有效 memory-tencentdb 配置
• Gateway 已重启
• [memory-tdai] 日志可见
• 数据目录与关键文件已生成
• 至少 1 次检索工具调用成功返回结果

交付话术模板

可在完成后向用户输出：

• 已完成 memory-tencentdb 安装与配置，并重启 Gateway。
• 已验证日志与数据目录生效，记忆链路可用。
• 如需下一步优化，可继续调优 recall.scoreThreshold、pipeline.everyNConversations、persona.triggerEveryN 与 embedding 模型参数。