A backup is a recovery contract: inside FishMem Desktop snapshots

A backup is not the file produced by an Export button. It is a tested promise that a user can recover the state they care about after a device failure, a bad upgrade, or an accidental replacement. For a local memory system, that promise includes much more than the rows currently visible in the interface.

FishMem Desktop treats a backup as a versioned namespace snapshot. Canonical records and their history travel with the snapshot. Search indexes and other projections are declared rebuildable rather than promoted to source truth.

The short version

• The backup carries canonical memories, history, graph state, documents, journal events, and operation identity.
• Vector and sidecar projections are marked for rebuild, avoiding device-specific index authority.
• Desktop validates the entire snapshot before deleting current data.
• If restore fails after replacement begins, Desktop purges the partial import and attempts to restore the pre-operation snapshot.
• Recovery is complete only after semantic indexes are ready and real recall operations pass.

Define what must survive

The first design decision is which data can be recreated and which data cannot. The answer should be written into the format rather than left to tribal knowledge.

Data	Portable authority	Restore behavior
Memory content and scope	Canonical records	Preserve stable IDs, timestamps, validity, and deletion state
Corrections and audit	Immutable history and events	Restore with the record so prior decisions remain explainable
Entities and associations	Canonical graph rows	Validate internal references before commit
Source documents	Versioned source content and descriptors	Restore the source family before rebuilding retrieval
Vectors, FTS, sidecar views	Derived projections	Rebuild and verify against canonical content

Why copying the SQLite file is not the product contract

A raw database copy may be useful for emergency forensics, but it couples recovery to one schema version, one storage engine, and one moment in the process lifecycle. It may also capture a write in progress or omit external source objects. A product backup needs a stable, validated representation above those implementation details.

The FishMem snapshot has a format version and a source namespace identity. Export hydrates document sources into the portable form and records that vector and sidecar state must be rebuilt. Import can bind the snapshot to a different empty namespace while preserving canonical identities and history.

Export should be boring and atomic

Desktop asks the user for a destination, exports the default namespace through the engine, and writes JSON through a temporary file before renaming it into place. The final file uses restrictive permissions. A crash during serialization should leave either the previous file or no final file, not a half-written backup that looks valid.

The current Desktop backup has a 512 MB input safety limit on restore. That limit is a fence, not a claim that every 512 MB snapshot will restore instantly. Large local libraries still need enough disk space and time to rebuild their semantic projections.

Validate before touching current data

Restore is destructive and requires an explicit RESTORE confirmation inside the Desktop service contract. Before current data is purged, the app checks that the selected path is a regular JSON file within the size limit and parses the complete portable snapshot against the target namespace.

Validation needs to reject more than malformed JSON. It checks the format version, record shapes, namespace rebinding, stable identities, and internal references. A snapshot in which a history row points to a missing memory should fail before replacement begins.

Restore is a state machine, not one database call

1. Parse and validate the incoming snapshot.
2. Export the current namespace as an in-memory rollback snapshot.
3. Purge the current namespace.
4. Import the selected snapshot under a unique idempotency identity.
5. Rebuild required projections and verify their counts.
6. Return imported memory, document, and vector totals.

If import or projection rebuild fails, Desktop purges the partial target and imports the saved pre-operation snapshot. If both restore and rollback fail, it returns an aggregate error rather than claiming that either library is healthy.

Rollback reduces risk; it does not replace an independent backup. Power loss, disk failure, or filesystem corruption can interrupt both the main restore and the local rollback attempt.

“Records restored” and “recall ready” are different states

Semantic retrieval depends on a local multilingual embedding model and a compatible index identity. On a new machine, the model may still be downloading. After a model or index change, vectors may require rebuilding. Desktop therefore exposes readiness errors instead of silently falling back to a lower-quality remote or keyword-only path.

The interface should distinguish at least these states:

• snapshot validated;
• canonical records restored;
• documents restored;
• semantic index rebuilding;
• search ready;
• restore failed and rollback succeeded or failed.

Test recovery with user journeys

A backup test that compares JSON counts is necessary but insufficient. A release exercise should start from an installed application and verify the behavior users depend on:

1. add a scoped memory and a source document;
2. update the memory and confirm history;
3. export a backup to a user-selected path;
4. change or remove the local state;
5. restore the backup;
6. wait for the local model and index to become ready;
7. search, get, update, inspect history, and delete through the packaged CLI path;
8. restart the app and repeat a recall check.

This proves that the UI, main process, service, SQLite store, local embedding runtime, and CLI agree on the recovered state. Merely reopening a window proves only that Electron launched.

Operational checklist

• Keep at least one backup outside the device being protected.
• Record the FishMem Desktop version that created the snapshot.
• Test restore after format or schema changes, not only export.
• Do not edit snapshot IDs or references by hand.
• Wait for semantic readiness before judging search quality.
• Verify a small set of known memories and document citations after recovery.

What the current contract does not promise

A Desktop snapshot is not continuous replication, cloud synchronization, multi-device merging, or protection against a compromised operating system. Desktop remains a single local authority with a user-owned backup workflow. Teams that need shared operations, managed recovery, organizations, and hosted workers should evaluate the Cloud or self-hosted service surfaces instead.

Further reading

• FishMem Desktop boundaries and local runtime
• Desktop SDK guide
• FishMem architecture and snapshot invariants