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

> Easily migrate data from v2 to v3 using the TencentDB Agent Memory migration tool. Upgrade your SQLite schema and relocate files with this Python script for a seamless transition.

- Repository: [Tencent Cloud/TencentDB-Agent-Memory](https://github.com/TencentCloud/TencentDB-Agent-Memory)
- Tags: migration-guide
- Published: 2026-08-26

---

**Use the [`v2-to-v3-migrate.py`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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

```bash
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:

```bash
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:

```bash
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):

```bash
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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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.