/hosted-recovery

name: hosted-recovery
description: Recover a previous MIRA instance's history into a fresh install — importing messages, memories, entities, and segment summaries from a database dump, a user export archive, or a renamed-aside old database on this machine (mira_service_old_<stamp> — what a breaking mira update or reinstall keeps behind), regenerating all embeddings in the new vector space, verifying, and then unfolding the restored history. Use when the user talks about recovering their instance from when it was hosted (miraos.org), importing a database dump/export archive of the previous context from Mira, taking a breaking release whose update was refused (their old database was kept aside), migrating an old Mira's history into a fresh install, or wanting their old Mira back. These are usually in SQL form sitting in ~/Downloads or a kept-aside database in Postgres. This skill contains the full runbook of running the whole flow autonomously, then self-deletes when done.

Hosted Recovery

What this is

The user had a previous MIRA instance, a durable entity — a hosted one from the decommissioned miraos.org deployment (its data is safely stored so users can request a takeout), or an install whose history lives in a database that was kept aside during a breaking update or reinstall. This fresh install is its successor. Somewhere there is an artifact holding that instance's history — messages, memories, entities, segment summaries — in one of three forms: a pg_dump SQL file or a user export archive (.tgz of JSON) in ~/Downloads, or a live `mira_service_old_<stamp>` database in this machine's Postgres, renamed aside automatically by the installer so nothing was ever deleted. This skill carries that history across the schema gap and then helps the restored Mira unfold it.

The schema mismatch is expected — that is what "breaking release" means here. Restoring the previous history after a fresh install is the default path, not a rescue operation. It is a founding act.

If the user has no artifact yet: hosted-user data was keyed by email address, and a database dump can be requested from taylor@rocketcitywindowcleaning.com. Ask the user which email their hosted account used before writing that request. A kept-aside database needs no request: it is already on this machine.

Golden rules

1. **Never reuse old embeddings.** Old vectors came from a different model in a different vector space; they are incomparable with the new ones. Regenerate every migrated text through the new embedding provider so old and new share one space. 2. **Remap exactly two ids.** Old user id and old continuum id become the fresh install's user id and continuum id. Every other UUID is preserved verbatim so cross-links survive. 3. **Never write to the live database except through the one-transaction ETL.** An unknown SQL file gets restored to a scratch database first; a kept-aside old database is inspected in place, read-only. ETL flows from the source into live, never the other way. 4. **Run the migration as one transaction.** The first run will probably crash on some NOT NULL column the old data doesn't populate. If nothing committed, the crash was free. Patch and re-run. 5. **Verify before you narrate.** Your first-pass account of the data will contain plausible errors. Check claims against actual rows before reporting them.

The workflow

**Phase 0 — Intake.** Find the artifact, in order of likelihood: a live `mira_service_old_<stamp>` database on this machine (`psql -lqt` lists it — what a breaking mira update or reinstall leaves behind), a SQL dump or .tgz export in ~/Downloads, or nothing yet (see the takeout note above). Confirm the fresh install is running: Postgres up with the mira_service database, vault answering at http://127.0.0.1:8200, app logs under the platform's log dir (macOS: /opt/mira/logs/mira-launchd.log). Do not touch the live DB yet.

**Phase 1 — Baseline.** Run a memory search and a conversation-history search and save the (nearly empty) results. Count rows per table. This is the before-picture and the rollback reference.

**Phase 2 — Safety dump.** Take the undo button first:

mkdir -p ~/mira_migration_$(date +%Y%m%d)
pg_dump -d mira_service -f ~/mira_migration_$(date +%Y%m%d)/pre_migration_mira_service.dump

Confirm nonzero size. If it's large, this isn't a fresh install; stop and ask the user.

**Phase 3 — Inspect the old data.** SQL-dump artifact: `createdb mira_old_scratch` then `psql -d mira_old_scratch -f ~/Downloads/<artifact>.sql`, and treat the scratch DB as the read-only source. Export archive: extract and read the JSON directly. A live `mira_service_old_<stamp>` database needs no restore — inspect it in place, read-only; the never-touch-live discipline still holds, because nothing writes to the live DB until Phase 4's one-transaction ETL. Answer before writing code: row counts and date ranges per table; schema diff old vs live (`\d <table>`); the two old ids and two new ids to remap. **The string-length trap:** a JSON-serialized embedding's character length (~9,500) is not its dimensionality (768). Parse the value before concluding anything about dims.

**Phase 4 — ETL script.** Write ~/mira_migration_<date>/migrate.py (Python, not hand-edited SQL). It must: connect with a maintenance/superuser role (the app's own role is RLS-restricted; migration only, never the app); run in one transaction; remap user and continuum ids only; skip billing, api_tokens, magic_links, persona_revisions, feedback-synthesis tracking, and bookkeeping tables; insert message content verbatim (never re-summarized; if the export holds the first message ever sent, it arrives character-for-character identical); import segment summaries as status collapsed; coalesce missing timestamps into NOT NULL columns (one real run crashed on last_tended_at; default it to now()). Feedback signals: import, but surface to the user that unsynthesized rows will feed futur