Backup Mirror (encrypted off-machine snapshot)
An encrypted full snapshot of your Omniscio state — the whole database, your config and every attachment — written to a folder you choose, so the install can be reconstructed on a different machine after a hard-drive failure.
On this page
What it is
Encrypted full snapshot of your Omniscio state — the entire database, your config, and every attachment — written to a folder you choose. Point it at a cloud-sync target (Dropbox / OneDrive / iCloud / Google Drive Desktop) and your Omniscio install can be reconstructed on a different machine after a hard-drive failure.
Unlike Setup Backup to Gmail, which mails only your configuration (projects, snippets, settings — no chats), Backup Mirror writes a full snapshot: every session, every conversation message, every attachment, every account record, every cron job. The archive is a single .amcmirror file: an AES-256-GCM-encrypted archive holding manifest.json + mission-control.db + config.json + attachments/. It is written and read as a memory-bounded stream — a framed container, compressed as a whole and then sealed inside a chunked AES-256-GCM envelope — so it works for a workspace of any size, and a database-heavy workspace makes a much smaller file than the data it holds (earlier versions assembled the whole bundle in one buffer and failed above ~2 GiB with ERR_FS_FILE_TOO_LARGE; archives from those versions, and mirrors written before compression was added, still restore — the header tells them apart). Point at the file from another Omniscio install with the same passphrase and you get your entire workspace back — sessions resumable, attachments intact, settings preserved.
The point is disaster recovery + machine migration. Setup Backup answers "I want to put my project list and snippets on a fresh laptop." Backup Mirror answers "my SSD died — give me back my whole Omniscio, conversations and all." Both can coexist; they target different failure modes.
Where to find it
How to use it
- Open Settings → Backup & Restore → Backup Mirror (search for "mirror" in the settings search bar).
- Pick a folder. Omniscio detects your cloud-sync folders (Dropbox / OneDrive / iCloud Drive / Google Drive) and offers each as a one-click chip — click one and Omniscio creates an
AMC-mirrorsubfolder inside it and fills the path for you. Prefer to choose it yourself? Browse… opens the OS folder picker pointed at your most likely cloud folder. A bare local folder works too if you'd rather rsync / robocopy the archives yourself. (Detection is best-effort — if nothing shows up, just Browse.) - Set a passphrase. Click Generate strong passphrase and Omniscio makes a strong, typeable one (real words, so you can re-type it on the new machine) — then copy it with one click — or type your own into Encryption passphrase. Either way, save it in your password manager and tick I've saved this passphrase. That tick is a reminder, not a lock: it disables the Sync now / Mirror now buttons until you check it, but the Enable toggle and the automatic writes do not wait for it — so a scheduled archive can be written under a passphrase you have not confirmed saving. Because without the passphrase the archives are unrecoverable (no recovery code, no key escrow, no per-machine override), save it before you switch the mirror on, not after.
- Set Keep last (the control's own label; default 5, accepted range 1–50 — the Settings dropdown offers 3, 5, 10, 15 and 20). Omniscio keeps the newest N
.amcmirrorfiles in the folder and prunes older ones on every write. There is also an optional maximum age (backupMirrorRetentionMaxAgeDays, unset by default): set it and archives older than that number of days are pruned as well, which bounds how far back the mirror can reach even when few archives are written. Five archives cover roughly 15 to 30 hours of history on a computer in daily use, not days (an archive is written about every 3 hours, and only when something changed). Raise the count if damage could go unnoticed for longer than that. - Toggle Enable backup mirror on. From now on, every time Omniscio writes its routine local backup, it ALSO writes a mirror archive to your chosen folder — and, the first time you enable it, Automatic sync defaults to When I open & close AMC so it's genuinely set-and-forget (change it any time; a returning user who set it back to Off is never overridden). The Settings panel surfaces
Last mirror: …andLast error: …so you can spot a broken sync. - Click Mirror now to verify the round-trip end-to-end before trusting the schedule. The first archive lands in your folder within seconds; your cloud-sync client picks it up over the next few minutes.
To restore on a new machine, there are two paths:
- Restore from the folder listing — if you've already configured the mirror folder, scroll to Restore from mirror in the Settings panel. It lists every
.amcmirrorfile in that folder. Pick one, type the passphrase, and choose a mode. - Restore from file (recommended for fresh machines) — the Restore from file button is always visible in the Backup Mirror section, even when no mirror folder is configured. It opens an OS file picker filtered for
.amcmirrorfiles, previews the archive manifest (size, date, source hostname), and lets you choose Replace or Merge mode. This is the primary path for the "just bought a new computer" migration scenario — copy your.amcmirrorfile onto the new machine by any means (USB, cloud drive, email), then browse to it.
See Restore flow below for the difference between Replace and Merge modes.
Settings keys
| Key | Type | Default | Purpose |
|---|---|---|---|
backupMirrorEnabled |
boolean | false |
Master toggle for the automatic copies. When off, no automatic mirror write runs regardless of other state — automatic sync, the local-backup mirror and Sync now all refuse. An explicit manual run is the deliberate exception: Mirror now, and the CLI POST /backup-mirror/run-now, still write one copy on demand. |
backupMirrorPath |
string | '' |
Absolute path to the folder where mirror archives are written. Empty disables the list endpoint. |
backupMirrorPassphrase |
string | '' |
The encryption passphrase. Stored safeStorage-encrypted with the enc: prefix; never crosses IPC outward. |
backupMirrorRetentionCount |
number | 5 |
Newest N archives to keep. After every successful write the older ones are pruned. |
lastBackupMirrorAt |
string | '' |
ISO timestamp of the most recent successful mirror write. Surfaces in the Settings panel. |
lastBackupMirrorError |
string | '' |
Error message from the most recent failed mirror write. Cleared on the next success. Surfaces as a red banner in the Settings panel. |
backupMirrorAutoSyncMode |
string | 'off' |
Automatic sync: off (manual only) · session (pull on launch + pull-then-push on quit) · scheduled (also on a timer). Every mode additionally requires the master toggle + a folder + a passphrase. |
backupMirrorAutoSyncIntervalMinutes |
number | 180 |
Interval for scheduled mode (clamped 60–1440). Sub-hourly disallowed — a snapshot is ~1–3 GB before compression. |
lastBackupMirrorAutoSyncAt |
string | '' |
ISO timestamp of the last successful automatic sync. Surfaces as "Last synced …". |
lastAutoSyncPulledMirrorId |
string | '' |
Internal: newest archive id observed at the last auto-sync (drives the pull short-circuit + "new work available"). Not user-set. |
lastPushedMirrorChangeMarker |
string | '' |
Internal: DB change fingerprint captured at the last auto-push (drives the push short-circuit). Not user-set. |
How it behaves
Sync now (one-button, two-device workflow)
Backup Mirror's snapshots also power a lighter everyday flow: keeping two devices you own roughly in step without the full setup-and-restore dance. The Sync now button (the primary action at the top of the Backup Mirror actions) does both directions of a sync in one click:
- Pull — it scans your mirror folder for the newest archive written by your other device (identified by the source
hostnamein each archive's manifest) and merges its work into this device: the sessions and messages you don't already have, plus the projects those sessions belong to (and any other active projects that device has). The merge is additive — it only ADDS what's missing here, never overwrites a project or session you already have, and needs no restart. Mind maps are the one exception: for a map both devices have, the copy changed most recently wins (no copy of the replaced version is kept), and a map deleted on the other device after its last edit here is deleted here too. Your own archives in the folder are skipped. - Push — it then writes a fresh snapshot of this device, so the other device can pull your latest work next time.
Pull runs before push on purpose: the push's retention prune sweeps the folder newest-first, so pulling first guarantees the other device's archive is merged before any prune could remove it.
Requirements (the button stays disabled until they're met): both devices point their mirror folder at the same synced folder and use the same passphrase. They do not need the same Omniscio version — the merge binds columns by name, so an older or newer build on the other device still merges (see the compatibility gate under Merge mode). When something's off, Sync now says so plainly instead of silently doing nothing — "make sure both devices point at the same synced folder" or "the mirror passphrase must match on both devices". A wrong-passphrase or still-uploading archive is skipped, not treated as a hard failure.
Sync now vs Mirror now — Mirror now only sends this device's snapshot (push). Sync now sends and merges the other device's latest (pull + push). For a single-device disaster-recovery setup, Mirror now (or the automatic write) is all you need; for working across two devices, Sync now is the one button to click when you sit down. The two differ under one setting: with the master toggle off, Mirror now still writes a copy (it is an explicit manual run) while Sync now refuses.
It is not live sync. It's one click per switch, not continuous, and it relies on your cloud-sync client to move the files between devices. With three or more devices, one click pulls the newest other-device archive; because every push carries this device's full history, everyone's work still propagates across the fleet over repeated syncs.
Behind the scenes: backup-mirror:sync-now runs syncPullFromFolder() (pull) then writeBackupMirror() (push). Each half reports independently, so a failed push never hides a successful pull, and the stored passphrase is read in the main process — it never crosses to the UI.
What gets backed up
Everything that matters for reconstructing your Omniscio install:
The entire SQLite database — built via
VACUUM INTO(clean snapshot, no WAL/SHM sidecars). Includessessions,conversation_messages,projects,automations,recipe_schedules,cron_jobs, every other table. A WAL checkpoint runs first so the snapshot includes all writes through the moment of the mirror.config.json— your settings and non-secret preferences (provider/integration secrets are intentionally NOT portable across machines). Projects, snippets, and app settings restore as-is. Secrets do not travel: the mirror writer runsredactConfigBytesForMirror, which strips everyenc:-wrapped settings secret from the embedded config (provider API keys likegeminiApiKey/openaiApiKey/openrouterApiKey, integration tokens likenotionApiKey/jiraApiToken, the backup passphrases, the Firebase service-account key — ~50 in all), and the credentials it does keep (top-level OAuth tokens,accounts[].apiKey, Google-auth tokens) are machine-boundsafeStorage/DPAPIenc:blobs that decrypt to empty on a different machine anyway. So after a restore on a NEW machine you re-enter your provider keys and re-sign-in once — exactly like the sibling Setup Backup to Gmail flow ("After a restore you re-sign in to Claude / Gmail / etc. once"). This is deliberate: a portable, decrypt-anywhere copy of every credential is precisely what the machine-binding exists to prevent. (The file is stillsafeStorage-encrypted at rest, and the mirror's outer AES-256-GCM is the exfil defense if it leaks.)The full attachments tree — every paperclipped image, every dragged PDF, every Office doc you've extracted. The walk pulls from
<userData>/attachments/recursively.A manifest —
manifestVersion,id,appVersion,schemaVersion, ISOtimestamp, sourcehostname, byte counts for each section. Used by the restore preview to show you what you're about to apply before any destructive write.Claude Code files from
~/.claude/— the globalCLAUDE.md(cross-project rules), per-projectCLAUDE.mdfiles (~/.claude/projects/*/CLAUDE.md, project-specific instructions not stored in the repo), and per-project auto-memory trees (~/.claude/projects/*/memory/). These live outside Omniscio's data directory but are critical for Claude Code session context. Optional — the archive succeeds even if none exist.User-authored skills from
~/.claude/skills/— every file under each of your skill folders (theSKILL.mdplus any bundled scripts or assets), captured into askills/section. This is a separate section from the Claude Code files above (which cover onlyCLAUDE.md+ memory): before this, skills rode only in the lighter Setup Backup to Gmail bundle, so a restore from the mirror alone silently dropped every skill. No size cap — skills stream like any other file (the 5 MB / 15 MB caps only exist on the emailed Setup Backup). Optional (omitted when you have no~/.claude/skills/); on restore, Replace overwrites and Merge keeps a skill you've edited on this machine. Rides the portable.amcbackupexport too.Global Claude config from
~/.claude/— yoursettings.json(permissions, hooks, model/statusline preferences),keybindings.json(custom shortcuts), and thescripts/folder (your deployed automation scripts), captured into aglobal-claude-config/section. This is a narrow allowlist — the backup reads only those three things and never touches~/.claude/secrets/,.credentials.json,settings.local.json, or theamc-repo.pathpointer (all machine-bound). Optional (omitted when you have none); on restore, Replace overwrites and Merge keeps asettings.jsonyou've edited on this machine. Heads-up:settings.jsonholds executable hooks and both it andscripts/can contain machine-specific paths, so give them a quick review after a cross-machine restore. Rides the portable.amcbackupexport too.File-based recipes from
~/.claude/recipes/— your*.recipe.jsonrecipe definitions, captured into arecipes/section. These are the on-disk recipe files; the recipe database rows (schedules, metadata) already travel inside the main database — this adds the file definitions themselves, which previously rode only in the Setup Backup to Gmail bundle. Only top-level*.recipe.jsonfiles are captured. Optional (omitted when you have none); on restore, Replace overwrites and Merge keeps a recipe you've edited on this machine. Rides the portable.amcbackupexport too.The KMS/Nothari knowledge vault — your user-authored notes (
.mdfiles) plus theassets/image store, walked from the user-chosennothariVaultRootPathfolder (which may be external to Omniscio's data directory). The database only stores references to these files, so without the files a restore would leave every note reference dangling — this is irreplaceable content no backup captured before. Machine-local index/VCS cruft is excluded (.kmsindex DB,.git,.trashsoft-delete sentinel,node_modules);assets/is kept. Optional — included only when a vault root is configured and readable at write time; on restore the notes land in this machine's configured vault folder (so point KMS at your vault before restoring on a new machine).Per-project notes — the free-text notes you write per project, stored as
<userData>/project-notes/<projectId>.md. A pure file store with no database row, so before this no backup captured them — machine death silently lost them, with no dangling reference to even flag the loss. Small and irreplaceable, folded in exactly like the vault. Optional (included only when you have any); on restore, Replace overwrites and Merge keeps a note you've edited on this machine. Rides the portable.amcbackupexport too.Tasks workspace files — the files Tasks agents wrote while doing a task and the documents you added to Tasks (Auto Context), stored under
<userData>/tasks-workspace/(the Tasks documents sit in its.claude/docsfolder). Neither is in the database, so before this no backup held them: a rebuilt computer got its Tasks back with no documents and none of the files the agents produced. Folders namednode_modulesand.gitinside it are skipped. Optional (included only when the folder holds files); on restore, Replace overwrites and Merge keeps a file already on this machine. The data export and the portable backup carry the same folder.Arij issue attachments — files you attach to an Arij issue (images, PDFs, docs), stored on disk under
<userData>/arij-attachments/<issueId>/(the database only holds the path). Irreplaceable user uploads that no backup captured before — a replace restore used to leave everyarij_attachmentsrow pointing at a missing file. Folded in like session attachments: optional (included only when you have any); on restore, Replace overwrites and Merge keeps a file already on this machine. Rides the portable.amcbackupexport too.Cloud control-plane state — files under
~/.amc/that no other backup path carried, each irreplaceable after the computer is lost.cloud-box-keep.jsonis your per-box keep list, the veto that stops the daily lifecycle sweep deleting a machine; without it a restore has no holds at all.cloud-dispatch-queue.jsonis a restore-safe snapshot of the cloud worker queue's briefs (job id, goal, done test, premise, branch, outcome) — not the live queue, so a restore imports a missing row asfailedand never relaunches it.unlanded-branch-backup/holds every verified git bundle that carries a current unlanded branch tip — the nightly job copies only what is not already copied, so this is a folder of files rather than one, and the newest alone would be one night's changes — which is the only off-machine copy of returned cloud work while pushing stays off, plusbranch-lifecycle.json— every branch description for that repository. A bundle carries refs and objects and never a description, and a description is the only durable record of a parked, held or owner-decided branch, so without this file a recovered machine would bring that work back as ordinary stranded work the rescue paths may adopt and land. On restore all of it lands back in~/.amc/; the next launch reads them, and writes any missing description back into the repository (never over an existing description, never a ready tag). A merge restore deliberately skipsbranch-lifecycle.json— it describes the other machine.Captured screenshots — the snips you take, stored on disk under
<screen-recordings-root>/screenshots/(the database only holds the file path). Small and irreplaceable, so they ride every mirror. On restore they land under this machine's screenshots store.Screen recordings (opt-in) — the recordings you capture, stored elsewhere under
<screen-recordings-root>/. Irreplaceable too, but a single recording can be 1–3 GB and the bundle is assembled in memory, so they are off by default and only included when you turn on "Include screen recordings" in the Backup Mirror settings (which makes each mirror bigger and slower). Secrets remain deliberately out of scope.User-imported books (Books plugin) — the EPUB/PDF books you import into the Books shelf, stored on disk under
<userData>/plugins/books/data/books/<bookId>/(the shelf's database rows hold only a reference to the file). Without the files a restore would leave every shelf entry pointing at a missing book. Small and re-importable from your originals, so they ride every mirror by default; on restore, Replace overwrites and Merge keeps a book already on this machine.The google-workspace MCP audit store — if you use the Google Workspace MCP, its
workspace.db(a log of every Google-Doc mutation plus batch-job history, at<userData>/google-workspace-mcp/workspace.db) is a non-rebuildable trail the main database holds no copy of. It's snapshotted with a WAL-safe online backup. Only the database is carried — never the siblingcredentials/refresh token (that re-derives when you re-authenticate with Google). Included only when the store exists.
Not included — the ephemera that's regenerated on restore (plus screen recordings unless you opted in above):
- WAL / SHM sidecars (
mission-control.db-wal,mission-control.db-shm). The VACUUM'd snapshot is self-contained. - Live process state. Running Claude CLI sessions don't survive — they're system-level processes pinned to the source machine. The restore sets
cli_session_id = NULLandforce_transcript_on_next_spawn = 1on every restored session so the next spawn uses the transcript-injection resume path (see Resume after restore). - Anything under
<userData>/logs/or other diagnostic-only state.
When it writes
The mirror writes from two independent triggers, so a fresh off-machine copy no longer depends on the local ring happening to tick while the app is open.
Its own freshness schedule. A registered service (src/main/services/backup/backup-mirror-freshness.ts, id backup-mirror-freshness) checks every 30 minutes, starting 15 minutes after launch, whether the mirror is stale — never written, or last written longer ago than the backup interval (backupIntervalHours, 6h default / 24h max) — and if so runs the same piggy-back write described below. That schedule is what carries a box restarted more often than the interval: the local ring anchors its first tick to the newest backup on disk, so a shutdown copy at every close pushed that first tick past the end of every session, and the mirror — which refuses the startup and shutdown triggers — was never written at all (audit RT-F019). The freshness schedule starts and stops with the backup ring (Settings → Backups on/off), and it inherits every guard the piggy-back has: the calm-wait, the load deferral, the change-fingerprint short-circuit, the retries and the "sync is failing" card. Two writers never produce two archives either: every mirror write is serialized, and a call whose mirror was written by another call while it waited collapses instead of writing a second, identical multi-GB archive (completedWriteGeneration in backup-mirror-piggyback.ts — lastBackupMirrorAt only moves when a write finishes, so it cannot be used to notice one that landed during the wait).
Sequence per local-backup tick:
- Local backup writes
<userData>/backups/backup-<ts>.db(the on-disk safety net). - If the mirror is fully configured — enabled and a folder and a passphrase, checked via
isBackupMirrorFullyConfigured— and the database has actually changed since the last mirror write (a cheap change fingerprint of your sessions, messages and Tasks — a Tasks edit alone counts as a change — the same short-circuit the scheduled push uses; a round that carried no new data costs no write at all, and a successful piggy-back write stamps the fingerprint so the next scheduled push skips too) — Omniscio immediately callswriteBackupMirror()(the gated piggy-back lives insrc/main/services/backup/backup-mirror-piggyback.ts, extracted from the backup create path). On success,lastBackupMirrorAtadvances andlastBackupMirrorErroris cleared. On a genuine failure it retries a few times, then logs, setslastBackupMirrorError, and raises the "sync is failing" card. The local backup still succeeded — it is the primary guarantee; the mirror is the off-machine layer on top. An enabled-but-unfinished mirror (no folder and/or passphrase) is NOT written and NOT treated as a failure — it's an incomplete setup, so the piggy-back simply skips and a gentle "Finish setting up Backup Mirror" reminder is shown instead (see below). - Manual trigger: clicking Mirror now — or the push half of Sync now (see Sync now) — calls the same
writeBackupMirror()path, bypassing any "too soon" gate the local backup might apply. Mirror now works even while the master toggle is off: the toggle pauses the automatic copies, it does not refuse a copy you explicitly ask for. Sync now still refuses while the toggle is off — its pull decrypts and merges the other device's archive into your live database, so it is gated before that half rather than after it.
A round the local debounce skips still carries an overdue mirror. The local ring refuses a backup that would repeat one already on disk — a restart inside the interval, or a periodic tick landing minutes after another round. That skip is about the LOCAL copy only, and it used to return before the piggy-back existed in the call path, which silently dropped the promise the startup deferral makes ("the next periodic round carries it") and left the off-machine copy stale until the freshness check or the next full local round. Now a skipped round asks the mirror itself: runMirrorPiggybackAfterDebouncedRound runs the same piggy-back when the mirror is older than the newest completed local backup (isMirrorBehindNewestLocalBackup, both in backup-mirror-piggyback.ts), and does nothing when the mirror is already newer than that backup. It is fire-and-forget, so a skipped round never holds the backup chain behind a multi-GB write, and it inherits every guard above — the configuration gate, the startup/shutdown deferral, the change fingerprint, the load deferral and the failure card. A startup or shutdown trigger stays deferred on this path too.
This means the mirror cadence follows the local backup's interval — the freshness schedule asks for a write once the off-site copy is older than backupIntervalHours — so flipping the toggle is the only setting you need to think about. You don't have a separate "how often to mirror" knob to keep in sync.
Disk-citizenship pacing. The snapshot runs OFF the main thread (a short-lived DB host, so a slow copy never freezes the app), and before the push Omniscio waits (bounded) while the database drive or the mirror-target drive is disk-saturated — so a backup never kicks off into an already-busy disk and slows whatever you're loading. It only waits for a calm moment; it never skips or indefinitely delays a backup. The write itself then runs paced: while the machine or either drive is busy, the multi-GB copy yields in short bounded pauses instead of saturating the disk the live database shares — the same back-pressure the local backup's own copy already applies to itself, so it is slow on a busy machine but never absent. The automatic mirror that follows a local backup is more patient still: if the machine or either drive is busy when it is due, it does not start at all — it checks again every 10 minutes, up to 6 times (about an hour), and then writes regardless, the same patience the local backup ring already has. Mirror now and Sync now are unaffected. Fail-open (a machine without the per-volume disk sensor — e.g. macOS/Linux — behaves exactly as before). Reversible: the in-write pacing rides the backup load gate, so it is switched off with AMC_DISABLE_BACKUP_LOAD_GATE=1 (or AMC_DISABLE_ARCHIVE_BACKUP_LOAD_GATE=1) — the same switch the local backup copy's own pacing obeys — while AMC_DISABLE_MIRROR_DISK_PACING=1 turns off only the pre-write saturation wait. See the mirror-disk-pacing invariant in backup-mirror-contract.md. (The complementary "ship only what changed" work — so a small change no longer re-writes the whole archive (~12 GB before compression) — is a proposed follow-up: chunked-incremental proposal.)
Restore flow
The Settings panel's Restore from mirror section lists every .amcmirror file currently in the configured folder, sorted newest-first, showing <id> + size + modified time. Pick one (or browse to a file outside the configured folder), type the passphrase, choose a mode, and confirm.
Replace mode — recommended for "my hard drive died" / "I bought a new machine":
Pre-restore safety snapshot. Before staging anything, Omniscio copies your current
mission-control.dbandconfig.jsonto<basename>.pre-restore-<ISO-timestamp>. The paths land in theRestoreResult.preRestoreBackupsarray so the panel can show you where to find them if you need to revert. There is no automatic prune of these — you delete them when you've confirmed the restore worked.Stage the new files alongside the live ones —
mission-control.db.pending-restore,config.json.pending-restore,attachments-pending-restore/. The live DB is untouched; an open Omniscio keeps working against it until restart.Patch the staged DB — every non-deleted row in
sessionsgetscli_session_id = NULLandforce_transcript_on_next_spawn = 1. (See Resume after restore for why.) A backup written before that column existed still restores: the patch clearscli_session_idand skips the missing column, and the ordinary migration on the next launch adds it. Omniscio never changes a restored database's schema at restore time.Write a flag file —
<userData>/restore-pending.jsoncontaining the mode, manifest id, archive path, staged-at timestamp, and the pre-restore snapshot paths.Tell you to restart.
RestoreResult.requiresRestart = true.On next startup, the swap happens in two phases to respect startup ordering:
- Config swap first (
consumePendingConfigRestore()inindex.ts): BEFOREinitConfigStore()loads settings, the stagedconfig.json.pending-restoreis renamed toconfig.json. This ensures the config store loads the restored settings, not the pre-restore ones. Without this ordering, the old settings load into memory and overwrite the restored file on the next save. - DB + attachments swap second (
consumePendingRestore()insideinitDatabase()): the staged DB is renamed over the live DB (after deleting stale WAL/SHM sidecars), the staged attachments tree is merged into the live one, and the flag file is cleared.
Crash-safe: if the user kills Omniscio during step 6, the staged files remain and the swap retries on the next launch.
- Config swap first (
Your erasure record survives the restore. If you have ever used the privacy wipe, Omniscio keeps a record of which tables it emptied, and no restore may bring those rows back. Rows a delete took with it are covered too: the personal facts and insights a deleted coaching write-up was built from are recorded at the delete and again at the 30-day sweep, so neither a merge nor an import brings them back — one still in Recently deleted returns still in Recently deleted, on its original date, and one already erased stays gone. Restoring the write-up from Recently deleted clears that record. A backup made before that record existed (before September 2026) cannot hold it, and the swap replaces the database that does — so the restore writes the record into a small file beside the database (<basename>.erasure-authority.pending-restore.json, table names and times only, never your content) and, at the next launch, once migrations have created the table, writes it back into the restored database. Only then is the file deleted. If the write-back cannot happen, the file stays and the next launch retries, and the app keeps honouring it in the meantime. A staged restore that cannot prove it respects an erasure recorded after it was staged is still refused and discarded, exactly as before. The local backup-ring restore inherits the same behaviour through the same file.
Screenshots and recordings come back with their library entries. The archive stores media under relative names (screenshots/<file>, screen-recordings/<file>), while the rows carry absolute paths from the machine that made the backup. After the media files are written into THIS machine's store, the staged rows are re-pointed at them by matching the relative tail, and only rows whose media the archive did not carry are hidden. Before this, replace mode hid every recording and screenshot on a cross-machine restore even though the bytes had arrived (mirror-restore-media-rows.ts).
Merge mode — recommended for "I want to pull session history from another machine into this one without losing my work-in-progress here":
- No pre-restore snapshot, no flag file, no restart needed. Merge is non-destructive by design, with one exception: mind maps. For a map both devices have, the copy changed most recently wins (no copy of the replaced version is kept), and a map deleted on the other device after its last edit here is deleted here too, so export any map you want to keep as it is first.
- Compatibility gate, not a version match. Merge mode binds every column by name (never
SELECT *, which would shift values when column order differs), so an archive from an older or newer Omniscio generally merges fine — you do not need replace mode just because the two devices are on different builds. The restore refuses only when the archive stores data too differently to merge safely: a frozen-baseline mismatch, or a column the merge requires that the archive does not have. When it refuses it says so plainly rather than half-merging. - ATTACH the archive DB as
archive, read-only. - Bring over the parent projects, then the new rows. A session's
project_idis a NOT NULL foreign key intoprojects, so before inserting sessions the merge brings over the source device's active projects that aren't here yet — the parents of the merged sessions, plus any chat-less projects — additively, never overwriting an existing project. Foreign-key checks are deferred to commit so parents and children can be copied in one pass; a project that shares a folder path with one you already have is not duplicated (its sessions are re-filed onto your existing project), and a project whose sidebar divider isn't here lands ungrouped. Then it inserts the newsessionsandconversation_messages— only rows whoseidisn't already local, messages scoped to sessions that now exist locally. Existing local rows are never touched (mind maps aside, see step 1); a session whose project genuinely can't be resolved is skipped rather than aborting the whole merge (this is the fix for the old "Sync now merged nothing when the other device added a project" bug). - Patch the newly-inserted sessions —
cli_session_id = NULLandforce_transcript_on_next_spawn = 1(only on the merged rows; your existing sessions are left alone). - Copy attachments for newly-merged sessions only, walking the archive's attachments tree and writing under the live tree.
- Detach + cleanup. The temp ATTACH-source DB file is
unlink'd regardless of success/failure.
The restore result reports restoredSessionCount (replace: count of patched rows in the staged DB; merge: count of inserted rows), mergedMessageCount (merge only), and restoredProjectCount (merge only: parent + active projects brought over). The panel renders a green success card with these counts and, for replace mode, a "Restart now" button.
A merge restore (including the pull half of Sync now) also reports what it left behind as plain-language warnings: Tasks rows the merge could not bring across, dates it could not read, Tasks that belong to a different sign-in, details a newer backup stored that this version cannot hold, tables you erased after the backup was made, and task attachment or session files that failed to write. The panel shows them in a warning toast (and in the Restore from file result card) next to the green summary, so a restore that left something behind never reads as a clean success. The same lines are returned by a cloud-backup merge restore.
Resume after restore
Every session in your Omniscio has a cli_session_id — the UUID the Claude CLI gave it on first spawn. Resuming a multi-turn conversation means passing --resume <cli_session_id> to the CLI, which loads the session state from the CLI's own per-user store at ~/.claude/. After a restore on a different machine, that CLI store is empty — the session IDs in the restored DB don't exist on the new machine, and --resume <missing-id> errors out.
Solution: every restored session is patched to set cli_session_id = NULL and force_transcript_on_next_spawn = 1. On next spawn:
- The spawn gate sees
cli_session_id IS NULLand routes through the transcript-injection path instead of--resume. - Omniscio reconstructs the conversation from
conversation_messagesand stitches it into the new CLI session as the initial context. - Once the CLI assigns a new
cli_session_id, that's persisted and subsequent turns use--resumeagain.
The user-visible effect: you lose the CLI's own session-internal state (which doesn't matter for chat continuity), but the conversation reads identically — every message you sent and every message the agent emitted is back in the new session from turn one. Migration v182 added the force_transcript_on_next_spawn column specifically to make this transition explicit and persistent (an in-memory flag would have lost the gate on the very first restart).
A backup older than that migration still restores. It has no force_transcript_on_next_spawn column, so the patch clears cli_session_id but cannot set the flag; the ordinary migration on the next launch adds the column. Those sessions start a fresh CLI conversation instead of injecting their stored transcript — every message is still in the database and on screen, but the agent begins without it. Current backups are unaffected.
Limits and non-goals
- Storage is your problem. Omniscio does not check the folder for free space, does not warn before filling a drive, and does not upload anywhere itself. Point at a cloud-sync target and let the sync client handle off-machine replication.
- No versioned snapshot system. Retention is a fixed N-newest sweep, and
backupMirrorRetentionCountaccepts 1 to 50. With the default of 5 the mirror reaches back only about 15 to 30 hours on a computer in daily use, so it is a disaster-recovery copy, not a way to undo a change you notice days later; the on-disk backup ring (about 12.5 days of full density at its defaults, plus a thinned weekly tail out to about eight weeks) reaches further back than the mirror does. There's no "snapshot daily but keep weekly for a year" tiered policy in the mirror. Each archive is a whole-database snapshot that can run to gigabytes, and a tiered default would multiply what sits in your synced folder, so any change to this policy needs an explicit decision about that storage, and about the erase-all report's statement of how long backups retain data. - No partial restore. Replace is whole-DB-or-nothing. Merge is whole-archive-or-nothing within the compatibility gate above. There is no "restore only sessions from project X" surface.
- Single passphrase. No per-machine passphrases, no key escrow, no recovery code. Lose the passphrase and the archives become unreadable. This is intentional — every workaround for a lost passphrase weakens the threat model. Need an off-machine backup you can still open after losing the passphrase? The newer Portable Backup DOES escrow a recovery code — every export mints one that unlocks the
.amcbackupon any machine even without the passphrase — so reach for it when cross-machine key portability matters. The mirror (and Setup Backup to Gmail) keep the no-escrow model as the deliberate trade for the mirror's whole-workspace snapshot. - Two archive generations, two version numbers. The manifest's
manifestVersionis 2 for the streamed archive Omniscio writes today and 1 for the older whole-buffer archive, which still restores; any other value throws with a clear message at the manifest-read step. The encrypted stream carries its own version: 2 (compressed before it is encrypted) is written now, and 1 (the same stream without compression, which is every streamed mirror written before compression) still restores. A stream version this build does not know is refused by name, and an Omniscio from before compression was added cannot open a mirror written now — update the new machine first.
If the mirror stops and says its saved passphrase can no longer be read
The passphrase is a saved secret like any other, so it is sealed with the data folder's own encryption key. If that key is ever replaced — see Data folder recovery — the passphrase can no longer be unlocked, and the mirror stops rather than writing snapshots it cannot protect.
You get a "Backup Mirror sync is failing" card saying so. It does not clear itself, because nothing about it will fix itself. Go to Settings → Backup & Restore → Backup Mirror and enter the same passphrase again; the next sync clears the card. Entering a new passphrase would make every archive already in your folder unreadable, and the next successful write would prune the folder down to its retention count — so use the one you chose.
Your existing archives are untouched while it is stopped, and the panel shows the passphrase as set (not missing) — which is what it is.
Related
- Setup Backup to Gmail — the lighter, configuration-only sibling. Different threat model (email transport, not local sync), different inclusion list (no conversations). Both can run in parallel.
- tray-and-window.md — graceful shutdown sequencing; relevant because the pending-restore swap runs on the next startup, so quitting the app cleanly is what gets you to that swap.
- Backup Mirror (part 2) — the rest of this page: first-time activation, the automatic-sync modes, the encryption envelope the archives use, the archive's internal storage layout and retention, the defences the restore path applies, and the IPC channels the settings panel drives.
Last verified 2026-10-18