企业官网建设流程全解析

TencentDB-Agent-Memory 插件包名迁移实战：从 @tdai/memory-tdai 平滑升级到 @tencentdb-agent-memory/memory-tencentdb

【免费下载链接】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

本文是一份基于 MemoryCore 仓库 SKILL-MIGRATION.md 整理的存量用户迁移指南，面向已安装旧版 OpenClaw 记忆插件@tdai/memory-tdai、需要升级到新包名@tencentdb-agent-memory/memory-tencentdb的用户。读完本文，你将掌握一套"确认状态 → 备份配置 → 校验数据 → 卸载安装 → 还原配置 → 重启验证 → 冒烟测试 → 可回滚"的完整迁移工作流，理解新旧插件共用数据目录的底层原理，并能在迁移失败时借助配套的诊断导出技能快速定位问题。

迁移背景：包名变更但数据目录不变的底层原理

本次迁移涉及一对插件标识的替换：

两条关键事实决定了迁移的低风险性：

1. 新旧插件共用相同的数据目录~/.openclaw/memory-tdai/。卸载旧插件不会删除数据目录，因此 L0 对话、L1 记忆、L2 场景块、L3 画像以及向量库等已有记忆数据不受影响。这一点在源码中得到了印证：数据目录的默认路径在 Gateway 侧解析，见 src/gateway/config.ts，其中默认值为~/.memory-tencentdb/memory-tdai（可通过TDAI_DATA_DIR环境变量或data.baseDir配置覆盖，父目录可通过MEMORY_TENCENTDB_ROOT覆盖），且兼容旧路径~/memory-tdai；memory-tdai目录名在代码中属于硬编码约定。
2. 卸载旧插件会删除openclaw.json中该插件的配置段。这是迁移流程中唯一会造成"配置丢失"风险的环节，因此备份配置是整个工作流的关键步骤。

从仓库代码结构看，本次迁移的另一个背景是：OpenClaw 适配层插件已经演进为Memory Gateway v3 客户端模式（见 openclaw-plugin，插件 ID 为memory-tencentdb-client，通过 npm SDK@tencentdb-agent-memory/memory-sdk-ts-v2连接远端 Gateway，自身不包含数据处理逻辑），而数据目录解析仍然保留memory-tdai命名。也就是说，无论是旧包还是新包，记忆数据的落盘位置从未改变，迁移的核心工作其实是"换入口、保数据、还原配置"。

适用场景与不适用场景

适用场景：

• 用户已安装@tdai/memory-tdai，需要迁移到新包名；
• 用户执行openclaw plugins install @tdai/memory-tdai报 404 / not found（旧包已从源下线）；
• 用户被告知旧包已废弃，需要迁移。

不适用场景：

• 用户从未安装过记忆插件：应使用全新安装流程（在仓库中对应openclaw-memory-tencentdb-setupskill，或直接使用 install-openclaw-plugin.sh）；
• 用户使用的是其他记忆插件（如openclaw-mem0），不在本次迁移范围内。

标准迁移工作流（8 步）

1) 确认当前状态

先确认旧插件是否确实已安装：

openclaw plugins list | grep -i memory

预期看到memory-tdai或@tdai/memory-tdai处于 loaded 状态。如果未看到旧插件，则跳过迁移流程，直接走全新安装路径。

2) 备份现有配置（关键步骤）

由于卸载旧插件会删除openclaw.json中的配置段，必须先备份。执行以下命令提取旧插件配置：

cat ~/.openclaw/openclaw.json | python3 -c " import sys, json cfg = json.load(sys.stdin) plugins = cfg.get('plugins', {}).get('entries', {}) old_cfg = plugins.get('memory-tdai', {}) if old_cfg: print(json.dumps(old_cfg, indent=2, ensure_ascii=False)) with open('/tmp/memory-tdai-config-backup.json', 'w') as f: json.dump(old_cfg, f, indent=2, ensure_ascii=False) print('\n✅ 配置已备份到 /tmp/memory-tdai-config-backup.json') else: print('⚠️ 未找到 memory-tdai 配置段（可能使用默认配置）') "

特别关注以下配置是否存在（如有则必须记录）：

• embedding配置（provider、baseUrl、apiKey、model、dimensions、proxyUrl）——决定向量检索是否可用；
• extraction.model——L1 记忆提取使用的模型；
• persona.model——L3 画像合成使用的模型；
• capture.excludeAgents——需要排除捕获的 agent 列表；
• capture.l0l1RetentionDays——L0/L1 数据保留天数。

这些字段在仓库中均有对应实现可查：excludeAgents与l0l1RetentionDays在 src/config.ts 及 src/utils/session-filter.ts 中被消费；embedding配置由 Gateway 侧的存储后端（SQLite + sqlite-vec 或腾讯云向量数据库）使用。配置缺失是迁移后"无历史记忆""embedding 报错"的最常见根因。

3) 确认数据目录存在

ls -la ~/.openclaw/memory-tdai/

预期看到：conversations/、records/、scene_blocks/、vectors.db、persona.md等文件。记录当前数据量作为迁移后验证依据：

echo "=== 迁移前数据统计 ===" wc -l ~/.openclaw/memory-tdai/conversations/*.jsonl 2>/dev/null || echo "无对话数据" wc -l ~/.openclaw/memory-tdai/records/*.jsonl 2>/dev/null || echo "无记录数据" ls ~/.openclaw/memory-tdai/scene_blocks/*.md 2>/dev/null | wc -l | xargs -I{} echo "场景块: {} 个" wc -c ~/.openclaw/memory-tdai/persona.md 2>/dev/null || echo "无 persona"

数据目录的完整结构（与 SKILL-DIAGNOSTIC-EXPORT.md 中描述的四层记忆数据布局一致）：

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

4) 卸载旧插件

openclaw plugins uninstall memory-tdai

执行后确认两件事：

• openclaw.json中memory-tdai配置段已被删除（预期行为）；
• ~/.openclaw/memory-tdai/数据目录仍然存在（不会被删除）。

# 验证数据目录仍在 ls ~/.openclaw/memory-tdai/ && echo "✅ 数据目录完好" || echo "❌ 数据目录丢失！"

5) 安装新插件

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

需要说明的是，仓库当前 openclaw-plugin 目录中的实现是v3 客户端模式（插件 ID 为memory-tencentdb-client），它通过 npm SDK 连接远端 Memory Gateway，不包含本地数据处理逻辑；其清单定义见 openclaw.plugin.json，入口实现见 index.ts。若需要自动化完成"构建 + 链接 + 写配置"全套动作，可直接使用 install-openclaw-plugin.sh：

# 本地 Gateway（默认） bash scripts/install-openclaw-plugin.sh # 远端 Gateway（严格校验模式） MEMORY_INSTALL_MODE=server \ TDAI_MEMORY_ENDPOINT="https://memory.example.com" \ TDAI_MEMORY_API_KEY="<instance-api-key>" \ TDAI_MEMORY_INSTANCE_ID="<instance-id>" \ TDAI_MEMORY_TEAM_ID="team-..." \ TDAI_MEMORY_AGENT_ID="agent-..." \ TDAI_MEMORY_USER_ID="user-..." \ bash scripts/install-openclaw-plugin.sh

该脚本会执行npm install（拉取 SDK）、npm run build、openclaw plugins install -l，并写入~/.openclaw/openclaw.json（plugins.slots.memory、plugins.entries、server/isolation、recall、capture以及按版本门控的hooks.*策略字段）。

6) 还原配置

将步骤 2 备份的配置写回openclaw.json，注意新插件的配置 key 是memory-tencentdb：

python3 -c " import json, os # 读取备份配置 backup_path = '/tmp/memory-tdai-config-backup.json' if os.path.exists(backup_path): with open(backup_path) as f: old_cfg = json.load(f) print('📋 备份配置内容：') print(json.dumps(old_cfg, indent=2, ensure_ascii=False)) else: old_cfg = {'enabled': True} print('⚠️ 未找到备份，使用最小配置') # 读取当前 openclaw.json config_path = os.path.expanduser('~/.openclaw/openclaw.json') with open(config_path) as f: cfg = json.load(f) # 写入新插件配置 cfg.setdefault('plugins', {}).setdefault('entries', {})['memory-tencentdb'] = old_cfg with open(config_path, 'w') as f: json.dump(cfg, f, indent=2, ensure_ascii=False) print('\n✅ 配置已写入 memory-tencentdb') "

如果备份丢失或用户需要手动恢复，至少确保写入最小配置：

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

注意：备份配置中的apiKey等敏感字段会原样写回，操作时不要让敏感信息出现在聊天或日志中。新插件配置的完整字段结构可参考 openclaw.plugin.json 中的configSchema（server.url/apiKey/instanceId/teamId/agentId/userId/rejectUnauthorized、recall.maxResults/includePersona/includeSceneNav、capture.enabled）。

7) 重启 Gateway 并验证

openclaw gateway restart

检查项：

• Gateway 日志中出现[memory-tdai]前缀（注：日志标签仍为 memory-tdai，这是正常的——日志标签沿用历史命名，与插件 ID 无关，可在 src/core/report/reporter.ts 等上报代码中看到plugin: "memory-tdai"的硬编码）；
• 数据目录内容未变化。

echo "=== 迁移后验证 ===" # 确认新插件已加载 openclaw plugins list | grep -i memory # 确认数据量与迁移前一致 wc -l ~/.openclaw/memory-tdai/conversations/*.jsonl 2>/dev/null wc -l ~/.openclaw/memory-tdai/records/*.jsonl 2>/dev/null

将迁移后的行数与步骤 3 记录的迁移前数据量对比，应完全一致。

8) 功能冒烟验证

执行一次对话确认记忆链路正常：

1. 发送一条包含个人信息的消息（如偏好、习惯）；
2. 确认日志中有[before_prompt_build]和[agent_end]相关输出——前者对应召回注入，后者对应对话捕获，与 openclaw-plugin/index.ts 中注册的before_prompt_build/agent_end两个 hook 一一对应；
3. 如有 embedding 配置，确认向量检索正常（日志无 embedding 报错）。

回滚方案

如迁移后出现问题，可快速回滚：

# 1. 卸载新插件 openclaw plugins uninstall memory-tencentdb # 2. 重新安装旧插件（如 npm 源仍可用） openclaw plugins install @tdai/memory-tdai # 3. 手动还原配置（从备份） # 将 /tmp/memory-tdai-config-backup.json 内容写回 openclaw.json 的 memory-tdai 段 # 4. 重启 openclaw gateway restart

回滚的前提是步骤 2 的备份文件仍然存在；若备份已清理（见下文安全约束），且确定迁移成功，则无需回滚。

故障排查速查表

进阶：借助诊断导出技能收集现场

当上述排查不足以定位问题时，仓库提供了配套的现场诊断导出 skill SKILL-DIAGNOSTIC-EXPORT.md，可一键打包 OpenClaw 日志、记忆插件数据（L0~L3）、脱敏后的配置为本地压缩包：

# 确认环境（工作目录探测：环境变量 > ~/.openclaw > ~/.clawdbot） OPENCLAW_DIR="${OPENCLAW_STATE_DIR:-$HOME/.openclaw}" [ -d "$OPENCLAW_DIR" ] || OPENCLAW_DIR="$HOME/.clawdbot" # 执行导出（默认输出到 ~/Downloads/openclaw-diagnostic-<timestamp>.tar.gz） bash scripts/export-diagnostic.sh # 或指定输出目录 bash scripts/export-diagnostic.sh /tmp

导出包包含env-info.txt（系统与目录信息）、logs/（最近 3 天、每文件最多 5000 行的网关与滚动日志）、memory-tdai/（全量记忆数据，包含用户对话原文，隐私风险高）、openclaw-config-redacted.json（已自动脱敏：apiKey/token/password/secret/credential字段替换为***REDACTED(Nchars)***，models/secrets/channels/env整体替换为***REDACTED_SECTION***，而plugins完整配置保留原样供排查）、plugins-info.txt。研发团队通常按以下线索排查：

安全与合规约束

• 备份文件/tmp/memory-tdai-config-backup.json可能包含apiKey，迁移完成后建议删除：rm /tmp/memory-tdai-config-backup.json；
• 不在聊天、日志中明文展示apiKey；
• 仅修改memory-tencentdb配置段，不影响用户其它插件。

完成定义（Definition of Done）

迁移完成需同时满足以下全部条件：

• 旧插件@tdai/memory-tdai已卸载；
• 新插件@tencentdb-agent-memory/memory-tencentdb已安装并加载；
• openclaw.json中存在完整的memory-tencentdb配置（含用户自定义的 embedding 等配置）；
• Gateway 已重启；
• 日志中出现[memory-tdai]前缀；
• 数据目录完好，数据量与迁移前一致；
• 至少 1 次对话验证记忆链路正常；
• 已清理备份文件中的敏感信息。

交付话术模板

已完成记忆插件迁移：

• 旧插件@tdai/memory-tdai→ 新插件@tencentdb-agent-memory/memory-tencentdb
• 已有记忆数据完整保留（对话/记录/场景块/向量库均未受影响）
• 配置已从旧插件完整还原（含 embedding / extraction / persona 等自定义配置）
• Gateway 已重启，记忆链路验证正常

迁移后的一致性与长期维护

完成迁移后，还应了解以下与本次变更相关的仓库事实，避免后续踩坑：

• 数据目录命名是历史约定：memory-tdai目录名在 Gateway 源码与日志标签中硬编码（如 src/gateway/config.ts 的默认路径解析、src/core/report/reporter.ts 的上报 ScopeName），因此迁移前后目录路径保持不变属于预期设计，不应手动重命名目录；
• Hermes 侧的插件别名兼容：Hermes 记忆提供方memory_tencentdb在 plugin.yaml 中保留了tdai与memory-tencentdb两个 legacy alias，使旧配置值memory.provider: tdai仍能解析到新提供方；相关的 Python 侧提供方说明见 hermes-plugin/memory/memory_tencentdb/README.md；
• 版本演进方向：如果用户的目标是接入 Memory Gateway v3 体系（含 team/agent/user 隔离），OpenClaw 侧应使用 v3 客户端插件（memory-tencentdb-client，见 openclaw-plugin/README.md），本地数据目录将不再承担核心存储职责，而是由远端 Gateway 统一管理。

总结

本次迁移的本质是"换包名、保数据、还原配置"三步：新旧插件共用~/.openclaw/memory-tdai/数据目录是数据零丢失的基石，备份openclaw.json配置段是防止配置丢失的关键动作，迁移前后数据量对比与冒烟对话验证则是质量闸门。严格按照本文的 8 步工作流执行，并在遇到异常时借助 SKILL-DIAGNOSTIC-EXPORT.md 导出现场数据，即可在存量用户场景下完成低风险、可验证、可回滚的插件包名迁移。

【免费下载链接】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