How to Migrate Data from v2 to v3 Using the Migration Tool in TencentDB Agent Memory

Use the v2-to-v3-migrate.py script in MemoryCore/scripts/migrate-v2-to-v3/ to upgrade your SQLite schema and relocate L2/L3 files before starting the v3 Gateway, ensuring automatic backups and idempotent execution.

The MemoryCore component of TencentDB Agent Memory introduced significant architectural changes in version 3, migrating from a flat data schema to a tenant-isolated structure with enhanced metadata tracking. To safely transition existing data from v2 without losing contextual memory or vector embeddings, you must execute the migration tool before launching the v3 Gateway. This guide explains how to migrate data from v2 to v3 using the official migration script with proper safety checks and command-line options.

Understanding v2 and v3 Data Format Differences

MemoryCore v2 stores data in a flat, single-tenant schema, while v3 introduces strict tenant isolation and expanded table structures. According to the TencentDB-Agent-Memory source code, the migration handles two primary transformation layers.

Schema Changes in vectors.db

The SQLite database undergoes substantial structural modifications during migration:

• v2 format: No tenant columns, simple L0/L1 tables for vector storage
• v3 format: New columns including team_id, task_id, user_id, agent_id, and version; rebuilt FTS5 full-text search indexes; addition of audit and skills tables for enhanced tracking

File Layout Migration

L2/L3 contextual files relocate from the data root into scoped profile directories:

• v2 location: Files stored directly under the data root (scene_blocks/, persona.md, .metadata/)
• v3 location: Assets moved to tenant-scoped folders (profiles/team%3Adefault%7Cagent%3Adefault/...) enabling multi-tenant isolation

Prerequisites and Safety Requirements

You must run the migration before starting the new v3 Gateway. If the Gateway initializes first, it creates a fresh v3 data store and ignores existing v2 data, effectively orphaning your historical memory.

The v2-to-v3-migrate.py script includes critical safety mechanisms:

• Automatic backups: Creates .bak.{timestamp} copies of vectors.db before modification
• Idempotent execution: Safe to re-run; the tool skips already-migrated items on subsequent executions
• Non-destructive: Original L2/L3 files remain untouched during the copy process

How to Use the v2-to-v3 Migration Tool

The migration tool resides at MemoryCore/scripts/migrate-v2-to-v3/v2-to-v3-migrate.py in the TencentDB-Agent-Memory repository. It accepts the path to your data directory and optional flags to control migration scope.

Command Syntax

python scripts/migrate-v2-to-v3/v2-to-v3-migrate.py <data_directory> [options]

Replace <data_directory> with your MemoryCore data path, typically ~/.memory-tencentdb/memory-tdai.

Available Migration Flags

Flag	Effect
--dry-run	Preview actions without modifying files or database schema
--db-only	Migrate only the SQLite schema (vectors.db); skip L2/L3 file relocation
--no-backup	Disable automatic .bak.{timestamp} backup creation (not recommended)

Step-by-Step Migration Examples

Always begin with a dry run to validate the expected changes before executing the actual migration.

Preview Changes with Dry Run

Inspect what would change without modifying any files:

python scripts/migrate-v2-to-v3/v2-to-v3-migrate.py ~/.memory-tencentdb/memory-tdai --dry-run

Execute Full Migration

Perform complete schema upgrades and copy L2/L3 files to the new profile hierarchy:

python scripts/migrate-v2-to-v3/v2-to-v3-migrate.py ~/.memory-tencentdb/memory-tdai

Database-Only Migration

Update the SQLite schema without moving L2/L3 assets (useful when file paths are managed separately):

python scripts/migrate-v2-to-v3/v2-to-v3-migrate.py ~/.memory-tencentdb/memory-tdai --db-only

Summary

• Migrate before Gateway startup: Running the tool after starting v3 creates data conflicts and loss
• Automatic safety: The script backs up vectors.db automatically and skips already-processed items
• Schema evolution: v3 adds tenant columns (team_id, user_id, agent_id, etc.) and new audit/skills tables to vectors.db
• File reorganization: L2/L3 files move from flat storage to scoped profiles/ directories
• Flexible execution: Use --dry-run to preview changes and --db-only for schema-only updates

Frequently Asked Questions

What happens if I start the v3 Gateway before migrating?

The Gateway initializes a fresh v3 data store that ignores existing v2 data. Your historical vectors and context remain in the v2 structure but become inaccessible to the new system, effectively requiring manual data recovery or re-migration after shutting down the Gateway.

Is the migration tool safe to run multiple times?

Yes. According to the implementation in v2-to-v3-migrate.py, the tool is idempotent. It detects already-migrated schema versions and copied files, skipping previously processed items without error or data duplication.

Can I migrate only the database without moving L2/L3 files?

Yes. Pass the --db-only flag to restrict the migration to SQLite schema updates only. This updates vectors.db with new columns and tables while leaving scene_blocks/, persona.md, and other L2/L3 assets in their original locations.

Where does the tool store backup files?

The migration script creates timestamped backups of vectors.db in the same directory as the original database, using the naming pattern .bak.{timestamp}. You can disable this behavior with --no-backup, though this is not recommended for production environments.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}