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

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的用户。读完本文你将掌握一套确认状态 → 备份配置 → 校验数据 → 卸载安装 → 还原配置 → 重启验证 → 冒烟测试 → 可回滚的完整迁移工作流理解新旧插件共用数据目录的底层原理并能在迁移失败时借助配套的诊断导出技能快速定位问题。迁移背景包名变更但数据目录不变的底层原理本次迁移涉及一对插件标识的替换维度旧插件新插件npm 包名tdai/memory-tdaitencentdb-agent-memory/memory-tencentdb插件 IDmemory-tdaimemory-tencentdb数据目录~/.openclaw/memory-tdai/~/.openclaw/memory-tdai/不变两条关键事实决定了迁移的低风险性新旧插件共用相同的数据目录~/.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-tdaimemory-tdai目录名在代码中属于硬编码约定。卸载旧插件会删除openclaw.json中该插件的配置段。这是迁移流程中唯一会造成配置丢失风险的环节因此备份配置是整个工作流的关键步骤。从仓库代码结构看本次迁移的另一个背景是OpenClaw 适配层插件已经演进为Memory Gateway v3 客户端模式见 openclaw-plugin插件 ID 为memory-tencentdb-client通过 npm SDKtencentdb-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, indent2, ensure_asciiFalse)) with open(/tmp/memory-tdai-config-backup.json, w) as f: json.dump(old_cfg, f, indent2, ensure_asciiFalse) 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_MODEserver \ TDAI_MEMORY_ENDPOINThttps://memory.example.com \ TDAI_MEMORY_API_KEYinstance-api-key \ TDAI_MEMORY_INSTANCE_IDinstance-id \ TDAI_MEMORY_TEAM_IDteam-... \ TDAI_MEMORY_AGENT_IDagent-... \ TDAI_MEMORY_USER_IDuser-... \ bash scripts/install-openclaw-plugin.sh该脚本会执行npm install拉取 SDK、npm run build、openclaw plugins install -l并写入~/.openclaw/openclaw.jsonplugins.slots.memory、plugins.entries、server/isolation、recall、capture以及按版本门控的hooks.*策略字段。6) 还原配置将步骤 2 备份的配置写回openclaw.json注意新插件的配置 key 是memory-tencentdbpython3 -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, indent2, ensure_asciiFalse)) 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, indent2, ensure_asciiFalse) print(\n✅ 配置已写入 memory-tencentdb) 如果备份丢失或用户需要手动恢复至少确保写入最小配置{ memory-tencentdb: { enabled: true } }注意备份配置中的apiKey等敏感字段会原样写回操作时不要让敏感信息出现在聊天或日志中。新插件配置的完整字段结构可参考 openclaw.plugin.json 中的configSchemaserver.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) 功能冒烟验证执行一次对话确认记忆链路正常发送一条包含个人信息的消息如偏好、习惯确认日志中有[before_prompt_build]和[agent_end]相关输出——前者对应召回注入后者对应对话捕获与 openclaw-plugin/index.ts 中注册的before_prompt_build/agent_end两个 hook 一一对应如有 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 的备份文件仍然存在若备份已清理见下文安全约束且确定迁移成功则无需回滚。故障排查速查表现象可能原因解决方案新插件无日志输出配置中enabled未设为true检查openclaw.json中memory-tencentdb.enabled安装新插件报错npm 源不可用检查网络 / npm registry 配置迁移后无历史记忆配置还原不完整对比/tmp/memory-tdai-config-backup.json与当前配置embedding 报错apiKey等配置丢失从备份中还原embedding配置段数据目录为空卸载时异常删除极少见检查~/.openclaw/memory-tdai/是否存在进阶借助诊断导出技能收集现场当上述排查不足以定位问题时仓库提供了配套的现场诊断导出 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。研发团队通常按以下线索排查排查方向查看文件关键信息插件是否加载logs/中搜索[memory-tdai]插件注册、配置解析日志记忆召回是否工作logs/中搜索[recall]搜索策略、耗时、命中数L1 提取是否触发logs/中搜索[pipeline]调度触发、L1/L2/L3 执行状态向量搜索是否可用openclaw-config-redacted.json的plugins.entriesembedding 配置是否正确数据量/磁盘占用env-info.txtdu 输出、文件数量checkpoint 状态memory-tdai/.metadata/recall_checkpoint.json进度、游标、计数器安全与合规约束备份文件/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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考