如何用 v2-to-v3 迁移脚本把 TencentDB Agent Memory 旧数据升级到 v2.0.0+ 格式

如何用 v2-to-v3 迁移脚本把 TencentDB Agent Memory 旧数据升级到 v2.0.0 格式【免费下载链接】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如果你正在把 TencentDB Agent Memory 的 MemoryCore 从 v1.x 或 v0.x数据格式 v2升级到 v2.0.0数据格式 v3直接启动新版 Gateway 之前必须先做一件事运行官方迁移脚本v2-to-v3-migrate.py把存量数据升级成 v3 格式。v2 与 v3 的差异集中在两块数据库vectors.db需要新增租户隔离字段以及scene_blocks/、persona.md、.metadata/这些 L2/L3 文件要挪到profiles/下的 scoped 路径。脚本位于 MemoryCore/scripts/migrate-v2-to-v3/v2-to-v3-migrate.py说明文档见 中文 README 与 英文 README。适用前提Python 3.8。迁移脚本文档给出的前置条件就是这一条外加一个数据目录路径。数据目录路径默认为~/.memory-tencentdb/memory-tdai/该目录下需要包含vectors.db。全新安装不需要跑迁移。新装 v2.0.0 的 Gateway 会自动创建 v3 格式数据这个脚本只服务于有 v1.x/v0.x 存量数据的用户。文档明确要求迁移前务必备份整个数据目录防止意外数据丢失。脚本自身也会在迁移前备份vectors.db但整体备份仍是你自己的必做步骤。另外说明一点版本要求CONTRIBUTING_CN.md 要求修改sdk/memory-core/python或 v2→v3 迁移脚本的开发环境使用 Python ≥ 3.9这比运行时要求的 3.8 更严格——如果你只是运行脚本按迁移文档的 3.8 即可。迁移会改什么了解改动范围有助于你判断 dry-run 输出是否符合预期。1.vectors.db表结构升级表变更l1_records新增team_id、task_id、user_id、agent_id、version字段l0_conversations新增team_id、task_id、user_id、agent_id字段l1_fts/l0_fts重建 FTS5 索引增加租户隔离列memory_audit新增审计表skills新增技能表skill_fts新增技能全文索引表2. L2/L3 文件迁移复制不是移动源路径目标路径{data_dir}/scene_blocks/{data_dir}/profiles/team%3Adefault%7Cagent%3Adefault/scene_blocks/{data_dir}/persona.md{data_dir}/profiles/team%3Adefault%7Cagent%3Adefault/persona.md{data_dir}/.metadata/{data_dir}/profiles/team%3Adefault%7Cagent%3Adefault/.metadata/L2/L3 文件是复制而非移动源文件不会被删除目标位置已存在同名文件时直接跳过——这也是脚本幂等的来源之一。脚本不处理的内容来自脚本文件头部的说明skill_vecvec0 虚拟表由 v3 服务启动时按运行时 embedding dimensions 参数自动创建、metadata.db独立数据库由管控面创建维护、l1_vec/l0_vec/embedding_meta表结构无变更。执行步骤以下命令与 MemoryCore/README_CN.md「从旧版升级」一节一致在仓库的MemoryCore/目录下执行数据目录按你的实际位置替换~/.memory-tencentdb/memory-tdai为默认值# 1. 先 dry-run 检查不实际修改数据 python scripts/migrate-v2-to-v3/v2-to-v3-migrate.py ~/.memory-tencentdb/memory-tdai --dry-run # 2. 确认无误后执行迁移 python scripts/migrate-v2-to-v3/v2-to-v3-migrate.py ~/.memory-tencentdb/memory-tdai参数说明来自迁移脚本文档参数说明/path/to/memory-tdai数据目录路径必填目录下需包含vectors.db--dry-run仅检查不实际修改--db-only仅迁移vectors.db表结构跳过 L2/L3 文件--no-backup跳过自动备份默认会自动创建.bak文件--db-only是可选分支当你确认 L2/L3 文件已经在目标位置、只欠数据库升级时使用。--no-backup会关掉脚本默认的.bak备份只有在已经做过整目录备份的前提下才建议用。验证迁移结果dry-run 输出脚本以只读方式连接vectors.db逐张打印l1_records、l0_conversations、l1_fts、l0_fts、memory_audit、skills的列数和行数未出现的表会标记「不存在」不带--db-only时还会逐项检查scene_blocks、.metadata、persona.md的源端与目标端是否存在最后输出「DRY-RUN 完成未做任何修改」。这是判断存量数据形态是否符合迁移预期的检查点。迁移过程脚本先打印备份路径vectors.db.bak.{timestamp}执行 WAL checkpoint 后逐项打印字段添加、FTS 重建行数、新增表创建L2/L3 文件复制时打印「 复制目录/复制文件」或「~ 已存在跳过」。全部完成的标志是最后一行「迁移完成! 耗时: Xs」。脚本幂等可以重复执行已存在的字段和文件会跳过不会重复处理。如果你不确定上次迁移是否跑完直接再跑一次即可。失败时如何恢复脚本默认会在迁移前自动备份vectors.db生成.bak.{timestamp}文件L2/L3 文件复制不删除源文件因此用备份恢复即可。如果启动前找不到vectors.db脚本会直接报错退出「错误: 找不到 vectors.db」此时检查数据目录路径是否传对即可脚本不会对不存在的库做任何修改。边界与限制迁移脚本只改数据格式不替代版本升级流程本身文档要求的是先迁移、再启动新版 Gateway。迁移把存量数据的租户字段统一补齐为默认值team_id/user_id/agent_id为defaulttask_id为空version为 0存量记录不会获得真实的租户归属这一点在解读迁移后的隔离查询结果时需要心里有数。L2/L3 文件只复制到profiles/team%3Adefault%7Cagent%3Adefault/这一套默认 scoped 路径多团队/多 Agent 的旧文件布局不在本脚本的处理范围内文档未提供对应选项。迁移完成后按正常流程启动 v2.0.0 的 Gateway 即可新数据会直接以 v3 格式写入。【免费下载链接】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），仅供参考