TencentDB Agent Memory v2 → v3 数据迁移指南：SQLite 表结构升级与 L2/L3 文件迁移实战

TencentDB Agent Memory v2 → v3 数据迁移指南SQLite 表结构升级与 L2/L3 文件迁移实战【免费下载链接】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 MemoryMemoryCore从 v1.x / v0.x 升级到 v2.0.0数据格式 v3时必备的数据迁移工具v2-to-v3-migrate.py讲解其使用场景、命令行参数、迁移范围与底层实现原理。读完本文你将掌握如何安全地将存量vectors.db表结构升级到带租户隔离字段的 v3 格式并把 L2/L3 文件迁移到profiles/作用域目录同时理解脚本的幂等、备份与 dry-run 设计能够在升级前完成一次无风险演练。迁移工具概述在 MemoryCore 的仓库中迁移脚本位于 MemoryCore/scripts/migrate-v2-to-v3/v2-to-v3-migrate.py配套的中英文说明文档为 MemoryCore/scripts/migrate-v2-to-v3/README.md 与 MemoryCore/scripts/migrate-v2-to-v3/README_CN.md。它是一段独立的 Python 3 脚本只依赖 Python 标准库argparse、os、shutil、sqlite3、sys、time、datetime无需安装第三方包针对数据面 SQLite 数据库vectors.db与本地 L2/L3 Markdown 文件做一次性格式升级。什么时候需要运行迁移当从 MemoryCore v1.x 或 v0.x 升级到 v2.0.0即数据格式 v3时数据库表结构和文件布局发生了变化必须先运行迁移脚本将存量数据升级到 v3 格式再启动新版 Gateway。迁移影响的存量数据有两类vectors.db新增team_id、task_id、user_id、agent_id、version等租户隔离字段scene_blocks/、persona.md、.metadata/L2/L3 文件需要迁移到profiles/子目录下的 scoped 路径。⚠️迁移前请务必备份整个数据目录避免意外数据丢失。脚本默认会自动为vectors.db生成.bak.{timestamp}备份见下文安全机制但整个数据目录的完整备份仍然是升级流程的第一道保险。前置条件Python 3.8数据目录路径默认数据目录为~/.memory-tencentdb/memory-tdai/目录下需包含vectors.db。命令行用法与参数详解脚本的核心用法分为三步先 dry-run 检查、确认后执行迁移、按需选择仅迁移数据库。# 1. 先 dry-run 检查不实际修改数据 python v2-to-v3-migrate.py /path/to/memory-tdai --dry-run # 2. 确认无误后执行迁移 python v2-to-v3-migrate.py /path/to/memory-tdai # 3. 仅迁移数据库跳过 L2/L3 文件 python v2-to-v3-migrate.py /path/to/memory-tdai --db-only参数说明参数说明/path/to/memory-tdai数据目录路径必填目录下需包含vectors.db--dry-run仅检查不实际修改数据库只读连接--db-only仅迁移vectors.db表结构跳过 L2/L3 文件--no-backup跳过自动备份默认会自动创建.bak文件从源码看这些参数在main()中通过argparse解析v2-to-v3-migrate.py 第 364-391 行。其中/path/to/memory-tdai是位置参数data_dir脚本会调用os.path.abspath归一化路径再拼接出db_path os.path.join(data_dir, vectors.db)如果找不到vectors.db脚本会打印错误并以退出码 1 终止——这保证了误传目录不会静默执行。Hermes 与 OpenClaw 场景示例# Hermes 场景 python scripts/migrate-v2-to-v3/v2-to-v3-migrate.py ~/.memory-tencentdb/memory-tdai --dry-run python scripts/migrate-v2-to-v3/v2-to-v3-migrate.py ~/.memory-tencentdb/memory-tdai # OpenClaw 场景 python scripts/migrate-v2-to-v3/v2-to-v3-migrate.py ~/.memory-tencentdb/memory-tdai --dry-run python scripts/migrate-v2-to-v3/v2-to-v3-migrate.py ~/.memory-tencentdb/memory-tdai迁移内容之一数据库表结构升级迁移脚本对vectors.db的表结构变更可归纳为四类操作为存量表补列、重建 FTS5 索引、创建新表、补齐存量数据默认值。表变更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新增技能全文索引表存量表的租户隔离列补齐migrate_l1_records()与migrate_l0_conversations()v2-to-v3-migrate.py 第 180-256 行首先用幂等的safe_alter()函数执行ALTER TABLE ADD COLUMN再对存量行执行默认值补齐# 默认值常量 DEFAULT_TEAM_ID default DEFAULT_USER_ID default DEFAULT_AGENT_ID default DEFAULT_TASK_ID DEFAULT_VERSION 0列定义与默认值的关键点team_id TEXT DEFAULT 、task_id TEXT DEFAULT 允许空串之后统一回填为default/ 空串user_id、agent_id为TEXT NOT NULL DEFAULT defaultversion INTEGER NOT NULL DEFAULT 0存量数据补齐逻辑UPDATE ... SET team_id ? WHERE team_id OR team_id IS NULL同时将空的session_id回填为default。这与新版运行时 MemoryCore/src/core/store/sqlite.ts 第 609-662 行 中l1_records/l0_conversations的建表 DDL 完全对齐——v3 格式下两张表都带team_id、task_id、user_id、agent_idL1 另有version且运行时的在线迁移逻辑try/catch 包裹的ALTER TABLE 空值回填与迁移脚本一致这也解释了为什么脚本是幂等的。脚本还会为两张表各创建一批新索引例如 L1 的idx_l1_task_updated、idx_l1_team_agent_updated、idx_l1_user_agent_sessionL0 的idx_l0_task、idx_l0_team_agent、idx_l0_user_agent_session等以支撑租户隔离场景下的按team_id/agent_id/user_id过滤查询。FTS5 全文索引重建为什么必须 DROP 重建l1_fts/l0_fts是 FTS5 虚拟表SQLite 的 FTS5 不支持ALTER TABLE ADD COLUMN因此脚本采取删除旧表 → 按新版 DDL 重建 → 从数据表全量回填索引的策略。核心实现在rebuild_fts()v2-to-v3-migrate.py 第 259-293 行-- 新版 L1 FTS DDL节选含租户隔离列均标记 UNINDEXED 不参与 BM25 排序 CREATE VIRTUAL TABLE IF NOT EXISTS l1_fts USING fts5( content, content_original UNINDEXED, record_id UNINDEXED, type UNINDEXED, priority UNINDEXED, scene_name UNINDEXED, session_key UNINDEXED, session_id UNINDEXED, team_id UNINDEXED, task_id UNINDEXED, user_id UNINDEXED, agent_id UNINDEXED, version UNINDEXED, timestamp_str UNINDEXED, timestamp_start UNINDEXED, timestamp_end UNINDEXED, metadata_json UNINDEXED );l0_fts的新版 DDL 同样携带team_id、task_id、user_id、agent_id等隔离列v2-to-v3-migrate.py 第 146-161 行。重建时脚本先通过PRAGMA table_info检查旧表列集合如果旧表已包含所有新列则跳过重建幂等否则 DROP 后按新 DDL 创建再用INSERT INTO {fts_table}(...) SELECT {source_exprs} FROM {data_table}全量回填索引并打印重建后的行数便于核对。值得说明的是新版运行时在 MemoryCore/src/core/store/sqlite.ts 第 986-1000 行 附近也有 FTS5 表的 v1→v2 在线迁移逻辑v1 表将原始文本存入content列v2 改用 jieba 分词后的文本 content_original存原文与迁移脚本的分工是脚本负责 v2→v3 的离线升级运行时负责首次启动时的兜底兼容。新增表memory_audit、skills、skill_ftscreate_new_tables()v2-to-v3-migrate.py 第 296-313 行创建三张 v3 新增的空表memory_audit修改审计表记录 L1/L2/L3 记录的 update/delete 事件。DDL 含layer TEXT CHECK (layer IN (L1,L2,L3))、action TEXT CHECK (action IN (update,delete))、version、updated_at_ms、request_id等字段并配套三个索引按 record 查、按隔离维度查、按时间查。与运行时 MemoryCore/src/core/store/sqlite.ts 第 961-984 行 的memory_audit定义一致skills技能主表采用单表多行多版本的快照模型UNIQUE(skill_id, version)is_head标记当前生效版本含name、description、content、content_hash、manifest_json、storage_dir、status等字段并带租户隔离列team_id、owner_agent_id、user_id、task_id及对应索引部分索引定义可在 MemoryCore/src/core/skill/skill-store-ddl.ts 第 21-65 行 对照skill_fts技能全文索引表FTS5 虚拟表对name、description、content建索引skill_id、team_id、owner_agent_id、task_id、user_id标记为 UNINDEXED分词器为unicode61 remove_diacritics 1见 MemoryCore/src/core/skill/skill-store-ddl.ts 第 71-83 行。迁移内容之二L2/L3 文件迁移与 profiles 路径编码L2/L3 文件的迁移发生在数据库迁移完成之后除非指定--db-only实现在migrate_l2_l3_files()v2-to-v3-migrate.py 第 316-361 行源路径目标路径{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/目标目录名的编码含义目标目录profiles/team%3Adefault%7Cagent%3Adefault/并非随意命名。从 MemoryCore/src/core/profile/profile-sync.ts 第 20-28 行 可以确认作用域scope的构造规则export function buildProfileIsolationScope(ctx?: ProfileIsolation): string { const teamId ctx.teamId || ctx.userId || default; const agentId ctx.agentId || default; // L2/L3 are teamagent-level memories. // L0/L1 keep user/session/task-level isolation, but profiles intentionally // ignore userId/sessionId/taskId ... return team:${teamId}|agent:${agentId}; }即作用域字符串为team:default|agent:default经 URL 编码:→%3A|→%7C后成为目录名team%3Adefault%7Cagent%3Adefault。运行时侧MemoryCore/src/core/hooks/auto-recall.ts 第 166-174 行 在召回 L2/L3 时同样使用encodeURIComponent(profileScope)构造profiles/{scope}/的 scoped 路径并将存储适配器限定在该前缀下避免跨作用域读取 profile 文件。迁移脚本把旧的全局文件放进 default 作用域目录正好与新版的读取路径对齐。复制而非移动源文件永不删除脚本对scene_blocks/、.metadata/目录采用shutil.copytree对persona.md采用shutil.copy2源文件始终保留目标已存在时直接跳过幂等。这意味着迁移是加量不改量的操作即使后续出现问题旧布局的数据也完好无损。脚本执行流程与安全机制结合 v2-to-v3-migrate.py 第 364-495 行 的main()一次完整迁移的内部流程为校验输入解析参数确认data_dir/vectors.db存在dry-run 分支若指定--dry-run以只读模式file:{db_path}?modero打开数据库逐个打印l1_records、l0_conversations、l1_fts、l0_fts、memory_audit、skills的列数与行数及列名并检查 L2/L3 文件的源/目标存在状态不做任何修改自动备份未指定--no-backup时将vectors.db复制为vectors.db.bak.{UTC 时间戳}时间戳格式为%Y%m%d_%H%M%SWAL checkpoint先以普通连接执行PRAGMA wal_checkpoint(TRUNCATE);把 WAL 日志合并回主库文件确保备份与后续操作基于完整一致的数据执行迁移以PRAGMA journal_mode WAL打开连接依次执行migrate_l1_records→migrate_l0_conversations→rebuild_fts(l1_fts)→rebuild_fts(l0_fts)→create_new_tables最后统一commit()文件迁移未指定--db-only时执行migrate_l2_l3_files输出耗时打印迁移完成! 耗时: {elapsed:.2f}s。三层安全兜底dry-run 只读演练、.bak.{timestamp}自动备份、L2/L3 复制而非移动。此外safe_alter()通过捕获duplicate column name错误实现幂等加列rebuild_fts()通过列集合子集判断跳过重建因此脚本可以重复执行。脚本不处理的边界范围脚本头部注释明确列出了三块不处理的数据理解这些边界能避免误判迁移结果skill_vecvec0 虚拟表其创建依赖运行时 embedding dimensions 参数由 v3 服务启动时自动创建仅当dimensions 0时创建。其 DDL 模板见 MemoryCore/src/core/skill/skill-store-ddl.ts 第 92-97 行__DIM__在 init 时替换为实际维度metadata.db独立数据库由管控面创建和维护不属于数据面迁移范围l1_vec/l0_vec/embedding_meta表结构在 v3 中无变更无需处理。常见问题FAQQ: 迁移失败了怎么办脚本默认会在迁移前自动备份vectors.db生成vectors.db.bak.{timestamp}文件L2/L3 文件采用复制而非移动源文件不会被删除。如果迁移失败直接用备份文件恢复即可。Q: 可以重复执行吗可以。脚本是幂等的——已存在的字段和文件会跳过不会重复处理safe_alter()忽略duplicate column name错误rebuild_fts()在旧表已含全部新列时跳过重建文件复制在目标已存在时跳过。Q: 全新安装需要跑迁移吗不需要。迁移脚本仅用于从旧版v1.x升级到新版v2.0.0的存量用户。全新安装的新版 Gateway 会自动创建 v3 格式的数据——运行时在 MemoryCore/src/core/store/sqlite.ts 的initSchema()中会直接以 v3 结构建表并携带与迁移脚本一致的在线补列逻辑作为兜底。建议的升级操作顺序完整备份整个数据目录~/.memory-tencentdb/memory-tdai/先执行--dry-run核对脚本输出的各表列数、行数与文件状态是否符合预期确认无误后正式执行迁移观察日志中迁移完成与耗时输出校验vectors.db.bak.{timestamp}备份文件已生成、L2/L3 文件已出现在profiles/team%3Adefault%7Cagent%3Adefault/下再启动新版 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），仅供参考