Module migrate 

Migration primitives: legacy memory → Brain (oxibrain).

The migration is resumable, non-destructive, and opt-in. It runs only when the user invokes oxicode migrate brain. The Oxi Foundation v1 host does not auto-migrate on startup; the migration is a one-time user action.

Checkpoint

~/.oxicode/migration/brain.json stores the last successfully migrated memory ID. On restart, the migration resumes from that point. The checkpoint file is a single JSON object:

{ "last_id": "m-1234", "migrated": 42, "skipped": 0, "failed": 0 }

The file is written atomically (temp + rename) so a crash mid-write cannot leave it in a partial state. A missing or unreadable checkpoint file is treated as “no checkpoint”.

Legacy store

The legacy durable memory under ~/.oxicode/memory/ is read through the LegacyMemoryReader fallible iterator. The read path is stateless — the legacy backend is not invoked, mutated, or deleted. The legacy store is left untouched until the user explicitly archives it via oxicode migrate brain --archive-legacy.

Archive

Archival moves ~/.oxicode/memory/ to ~/.oxicode/archive/memory/<timestamp>/. The archive directory inherits the original permissions. The legacy store cannot be re-enabled silently — restoring requires a separate explicit command (not yet implemented; future work).

Structs

Checkpoint

On-disk checkpoint. Atomic-write via temp + rename.

LegacyBatches

Iterator over batches of legacy items. The file is read once; subsequent calls drain pending until exhausted.

LegacyItem

A single legacy memory item to migrate.

LegacyMemoryReader

Read-only legacy memory reader. Walks the legacy store under ~/.oxicode/memory/items.jsonl. The read path is stateless and never mutates the legacy store.

Migration

Migration driver. Holds the checkpoint so each call can advance the on-disk state.

Enums

MigrationOutcome

Outcome of a single migration step.

Functions

archive_legacy_default

Move the legacy store to ~/.oxicode/archive/memory/<timestamp>/. Returns the destination path on success.

default_checkpoint_path

Default location for the migration checkpoint.

default_legacy_path

Default location of the legacy durable memory store.