企业官网建设流程全解析

基于 OpenClaw 与 TencentDB Agent Memory 的四层长期记忆插件安装配置实战指南

【免费下载链接】TencentDB-Agent-MemoryTencentDB Agent Memory is a team-level memory hub for AI Agents — turning conversations, docs, and code into four reusable memory assets (Chat Memory, Skill, LLM-Wiki, Code-Graph) that are governed, shared, and equipped across agents and frameworks.项目地址: https://gitcode.com/GitHub_Trending/te/TencentDB-Agent-Memory

本指南以 SKILL.md 为核心，完整讲解如何在 OpenClaw 中安装、配置、验证并排查@tencentdb-agent-memory/memory-tencentdb记忆插件，实现 L0→L1→L2→L3 的可持续本地长期记忆闭环（对话捕获、事实提取、场景归纳、用户画像）。读完本文，你将掌握从零到一的插件落地流程、全量生产配置模板、向量检索与 BM25 混合召回的原理，以及一整套可复现的验收与故障排查方法。

图为 memory-tencentdb 四层记忆模型的层级关系：L0 原始对话全量留存 → L1 原子记忆（事实/偏好/约束/状态）→ L2 场景块（按项目/主题聚类）→ L3 用户画像（稳定偏好与服务方式）。

一、插件是什么：OpenClaw 侧的本地长期记忆能力

memory-tencentdb是一个面向 OpenClaw 的长期记忆插件，目标是在不依赖外部托管记忆服务的前提下，为 Agent 提供可持续的本地记忆能力。它的核心是四层记忆流水线：

数据目录结构（OpenClaw 场景下默认位于~/.openclaw/state/memory-tdai/，Hermes 场景下默认位于~/.memory-tencentdb/memory-tdai/）：

memory-tdai/ ├── conversations/ — L0 原始对话（每日 JSONL 分片） ├── records/ — L1 结构化记忆（每日 JSONL 分片） ├── scene_blocks/ — L2 场景 Markdown 文件 ├── persona.md — L3 用户画像 ├── vectors.db — SQLite 数据库（向量 + 全文索引） ├── .metadata/ — checkpoint、scene_index.json └── .backup/ — 滚动备份

从源码结构看，该插件的命名与历史沿革如下：hermes-plugin/memory/memory_tencentdb/plugin.yaml 中声明了插件 ID 为memory_tencentdb，同时保留了tdai与memory-tencentdb两个别名，使旧配置中memory.provider: tdai仍能继续解析到本插件。SKILL 文档中提到的数据目录名memory-tdai是代码中硬编码的实际数据目录路径，与插件 ID 无关。

适用场景

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

不适用场景

• 用户只需要解释 memory 理念，不要求实际落地
• 用户要接入非 OpenClaw 宿主（此时应先确认目标框架，例如 Hermes，可参考 hermes-plugin/memory/memory_tencentdb/README.md）

二、标准工作流：从环境预检到冒烟测试

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

仓库还提供了封装安装脚本 scripts/install-openclaw-plugin.sh，它会自动完成：npm install（从 npm registry 拉取@tencentdb-agent-memory/memory-sdk-ts-v2SDK）、npm run build构建插件、openclaw plugins install -l本地挂载，以及写入~/.openclaw/openclaw.json（设置plugins.slots.memory、启用插件、写入 server/isolation/recall/capture 配置，并在检测到 OpenClaw>= 2026.4.24时写入 hooks 权限字段）。本地模式一行即可：

# 本地 Gateway（默认） bash MemoryCore/scripts/install-openclaw-plugin.sh

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 } } }

各分组参数详解（结合仓库配置与源码）

capture组：对话捕获与保留策略

extraction组：L1 提取与去重

在 tdai-gateway.standalone.yaml 中可以看到该分组的独立 Gateway 形态配置：maxMemoriesPerSession: 20、enableDedup: true，这说明同一批引擎参数既可通过 OpenClaw 插件配置下发，也可通过 standalone Gateway 的 YAML 配置生效。

pipeline组：L1→L2→L3 调度

recall组：召回参数

standalone 配置中还补充了timeoutMs: 5000（召回超时上限）与bm25: { enabled: true, language: "zh" }（BM25 关键词检索，中文分词），可见混合召回中向量路径与 BM25 关键词路径是相互补充的：向量负责语义相似，BM25 负责关键词精确命中。

persona组：场景与画像触发参数

embedding组：向量检索配置

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

• embedding.provider = "none"时，向量能力会禁用，仅保留关键词路径（BM25）。
• 若配置远端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-plugin/README_CN.md 可知，这两个工具分别走 v3 SDK 的searchAtomic()（L1 结构化记忆搜索）与searchConversation()（L0 原始对话搜索），而 src/hooks/recall.ts 中的performRecall()会在构建 prompt 前并行发起L1 搜索、L3 画像读取与 L2 场景列表三个请求（Promise.allSettled），任一请求失败都不会阻断整体注入，随后由 src/format.ts 的formatRecallResult()格式化为带标签的简洁记忆上下文注入 prompt。

三、故障排查速查

需要进一步定位问题时，可以借助仓库中配套的诊断导出技能 SKILL-DIAGNOSTIC-EXPORT.md：它会把 OpenClaw 日志、记忆插件 L0~L3 数据、脱敏后的配置打包成本地压缩包，供研发团队排查。导出脚本对应仓库的scripts/export-diagnostic.sh（默认输出~/Downloads/openclaw-diagnostic-<timestamp>.tar.gz，可传参指定输出目录），脚本对openclaw.json会执行脱敏——字段名匹配apiKey/token/password/secret/credential的值替换为***REDACTED(Nchars)***，顶层models、secrets、channels、env块整体替换为***REDACTED_SECTION***，而plugins完整配置保留原样（插件配置正是排查重点）。

导出后研发团队通常关注以下日志标签与文件：

四、安全与合规约束

• 将apiKey视为敏感信息；不在聊天、日志、截图中明文扩散。
• 优先使用环境变量注入密钥；配置示例中仅保留占位符（如${EMBEDDING_API_KEY}）。
• 仅修改memory-tencentdb对应配置段，避免覆盖用户其它插件配置。
• 导出诊断数据时：配置文件已自动脱敏，但记忆数据（memory-tdai/）包含用户对话原文，需确认可以分享后再发送；压缩包存放在本地，不会自动上传，需手动发送给研发团队。

五、完成定义（Definition of Done）

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

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

六、交付话术模板

可在完成后向用户输出：

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

七、延伸：多框架接入与 Gateway 侧配置

SKILL 文档聚焦 OpenClaw 宿主，但同一套四层记忆引擎也通过 hermes-plugin/memory/memory_tencentdb/README.md 提供 Hermes（Python）侧的接入适配：Hermes 侧实现是一个"薄 HTTP 客户端 + 进程监管器"（MemoryTencentdbSdkClient+GatewaySupervisor），真正的捕获、提取、存储、召回、流水线调度全部运行在 Node.js Gateway 侧车进程中。

从 client.py 的源码可以看到 v3 数据面接口的完整映射：POST /v3/conversation/add（L0 写入）、POST /v3/conversation/search（L0 搜索）、POST /v3/atomic/search（L1 搜索）、POST /v3/scenario/ls/POST /v3/scenario/read（L2 场景）、POST /v3/core/read（L3 画像），所有接口都携带team_id / agent_id / user_id三元组做租户隔离，并通过x-tdai-service-id请求头标识服务实例；v1 的/recall、/capture等接口保留为向后兼容的废弃路径。

supervisor.py 中的GatewaySupervisor则展示了健壮性设计：启动时先探测/health（ok/degraded均视为可用），不可用则在单飞锁（线程锁 +fcntl跨进程锁）保护下以Popen启动侧车并轮询健康状态最长 30 秒；子进程 stdout/stderr 重定向到日志文件而非 PIPE，避免管道缓冲区（约 64KB）写满导致子进程阻塞；崩溃后通过is_process_alive() or is_running()双检查触发重新拉起；退出时以killpg发送SIGTERM到整个进程组，确保pnpm -> tsx -> node链路不会遗留孤儿监听进程。Hermes 侧还内置了熔断器（连续 5 次 Gateway 失败暂停调用 60 秒）与捕获背压（最多 4 个在途sync_turn线程）。

Gateway 侧（含存储后端、embedding、流水线节奏、召回策略）的配置在独立配置文件中管理，standalone 形态参考 tdai-gateway.standalone.yaml：支持sqlite（本地 SQLite + sqlite-vec，零外部依赖，默认）与tcvdb（腾讯云向量数据库，需填写 url/username/apiKey/database/embeddingModel/timeout）两种存储后端；LLM 通过llm.baseUrl、llm.apiKey（环境变量TDAI_LLM_API_KEY注入）、llm.model配置；deployMode: standalone且stateBackend: "local"意味着进程内状态管理、无需 Redis 等外部依赖，适合本地开发与单 Agent 单机部署。

结语

从环境预检、插件安装、最小配置到生产级参数模板，再到重启验证、冒烟测试与故障排查，memory-tencentdb为 OpenClaw 提供了一条完整、可验收的长期记忆落地路径。理解capture/extraction/pipeline/recall/persona/embedding六组参数各自的职责边界，尤其是 embedding 四元组齐全性与l0l1RetentionDays的清理语义，是避免"装了但没记忆"这类隐性失败的关键；配合仓库中的安装脚本、诊断导出技能与 Gateway 独立配置模板，即可在不同部署形态间平滑迁移。

【免费下载链接】TencentDB-Agent-MemoryTencentDB Agent Memory is a team-level memory hub for AI Agents — turning conversations, docs, and code into four reusable memory assets (Chat Memory, Skill, LLM-Wiki, Code-Graph) that are governed, shared, and equipped across agents and frameworks.项目地址: https://gitcode.com/GitHub_Trending/te/TencentDB-Agent-Memory