Export and restore safely

Outcome and prerequisites

You will take a consistent snapshot of the whole store, make a change you can see, restore over it, and prove the change is gone. Then you will understand exactly what a snapshot contains, what it deliberately leaves out, and how that affects moving to another machine.

• The synapse CLI installed.
• A destination path that does not already exist.
• A terminal you can keep open, to record one memory ID.

1. Check the store before you trust a copy of it

   shell Copy

   synapse path
   synapse data check

   text Copy

   Database: /Users/example/Library/Application Support/synapse/brain.db
   Version: 7
   Integrity: ok

   Integrity must read ok. Two separate checks stand behind that word: a relationship check that runs every time the database opens, and a full page-by-page scan that reads the whole file. Exporting a store that fails either one copies the problem rather than saving you from it.

   If it reports anything else, stop here and follow the corruption guidance in Troubleshooting before continuing.

2. Create a fresh export

   shell Copy

   backup="$HOME/Desktop/synapsetutorialbackup.db"
   test ! -e "$backup"
   synapse data export "$backup"

   text Copy

   Exported /Users/example/Desktop/synapsetutorialbackup.db

   That one line hides four steps. Synapse writes a consistent compact snapshot rather than copying a file that may be mid-write, secures its permissions to owner-only, reopens it read-only, and validates it — all before reporting success. An export that would not open is a failure here rather than a surprise months later.

   The snapshot is a complete SQLite database. It holds every memory with its scope and project, vault and secret metadata, scope trust records, import batches, skill install receipts, mesh history, and your settings.

3. Add one marker after the export

   shell Copy

   printf '%s\n' 'This entry exists only after the tutorial export.' \
     | synapse memory add synapserecovery
   synapse memory list synapserecovery

   text Copy

   Stored memory #42

   Record that ID. It is the marker that must disappear when the restore succeeds — which is what turns this from "the command did not error" into an actual proof.

4. Stop every database user

   Quit the Synapse desktop app. Close every connected session so its synapse mcp child process exits. A plain CLI command releases its lock when it finishes, so nothing needs doing about those.

   Reading the database takes a shared lock; restoring requires an exclusive one. If you deliberately leave a session open, the next step will refuse and tell you to close the app and connected tools.

5. Restore

   shell Copy

   synapse data restore "$backup"

   text Copy

   Restored /Users/example/Desktop/synapsetutorialbackup.db
   Previous database: /Users/example/Library/Application Support/synapse/backups/brain.1785776950101.restore.db

   Read the second line. Before replacing anything, Synapse wrote the current database into the backups folder with a restore marker in its name. If you have just restored the wrong file, that path is your way back — and it is printed rather than left for you to discover.

   The sequence is: validate the source, validate the current database, acquire the exclusive lock, snapshot the current state, then replace atomically. Any step failing leaves the original in place.

6. Verify the earlier state actually returned

   shell Copy

   synapse data check
   synapse memory list synapserecovery

   Integrity should read ok, and the marker must be absent — an empty result is the success condition. Confirm something you expect to still be there as well, so you are testing that the right state returned rather than that the database is merely empty:

   shell Copy

   synapse memory list

   Reopen the desktop app and your connected tools only after this verification passes.

What a snapshot does not carry

This is the part that surprises people, and it follows directly from the security model.

# a complete manual copy, when the database alone is not enough
cp -R ~/Library/Application\ Support/synapse ~/Desktop/synapse-full-copy

Backups you did not ask for

Synapse writes snapshots on its own at two moments: before any schema migration, and before any restore. Both land in the same place:

ls ~/Library/Application\ Support/synapse/backups/

Only the newest few are kept, so the folder cannot grow without limit — the same rule that bounds worker logs and the crash log. That means an automatic backup is a safety net for the operation that just happened, not an archive. If you want a copy to keep, take an explicit export and move it somewhere Synapse does not manage.

Moving to a new Mac

1. On the old machine

   Run synapse data export, and copy SOUL.md and the skills/ directory alongside it. Note which secrets exist with synapse secret list for each vault — the names, since you cannot export the values.

2. On the new machine

   Install Synapse, install the CLI, then restore the export before connecting any tools. Put SOUL.md and skills/ back in the data folder.

3. Then

   Recreate each secret with synapse secret set, re-approve each project scope with synapse allow — approval is per machine, because it is a statement about a file you have read — connect your tools, and run synapse skill install.

synapse doctor

One command to confirm the new machine matches the old one: same schema version, same memory count, tools connected, skills installed.

Next step

Finish the maintainer level with Check, migrate, and remove Synapse, which covers the health report in full and both removal paths.