# Migration Strategy: Schema v1 → v2

This guide explains how session-buddy migrates legacy `conversations` and `reflections` tables to the enhanced Memori-inspired schema v2.

## Overview

- Parallel schema: v1 tables continue to exist alongside v2 during rollout
- Auto-detect version on startup (tools or hooks may call migration utilities)
- Backup before migration and rollback support
- Preserve ONNX embeddings and metadata

## Versioning

- `schema_meta(schema_version)` tracks the active schema version
- `schema_migrations` logs migration attempts (pending/success/failed)

## What Changes

- New tables: `conversations_v2`, `reflections_v2`, `memory_entities`, `memory_relationships`, `memory_promotions`, `memory_access_log`
- Categorization, tiering, access tracking, and indexing for performance

## Commands (Python API)

- `needs_migration()` → bool
- `migrate_v1_to_v2(dry_run: bool = False)` → MigrationResult
- `get_migration_status()` → dict
- `create_backup()` / `restore_backup(path)`

## Rollout

1. Run with feature flags OFF (default)
1. Migrate data while v1 continues to work
1. Enable `use_schema_v2` once validated
1. Gradually enable LLM extraction and conscious agent

## Safety

- Migration is idempotent and best-effort
- Stats and errors recorded in `schema_migrations`
- Rollback by restoring the DB backup
