Data lifecycle

Locate the database, understand startup checks and automatic backups, export a consistent snapshot, and restore safely.

Files and permissions

On macOS, the default data directory is ~/Library/Application Support/synapse. Run synapse path to print the resolved data, shared-guidance, and CLI paths for the current environment.

Path	Purpose
`brain.db`	Scoped memory, import provenance and batches, settings, vault metadata, global mappings, and scope approvals.
`SOUL.md`	The editable shared guidance loaded by both connected tools and the MCP server.
`brain.db-wal` and `brain.db-shm`	SQLite write-ahead-log sidecars while the database is active.
`brain.lock`	Shared lifecycle lock held by the app, CLI operations, and MCP server.
`backups/`	Automatic pre-migration and pre-restore SQLite snapshots.

On Unix systems the data and backup directories use mode 0700; database files, sidecars, locks, and backups use 0600.

Startup

Every database open follows the same sequence:

Create and secure the data directory if needed.
Acquire a shared lifecycle lock.
Open SQLite with foreign keys enabled, a five-second busy timeout, and WAL journal mode.
Run PRAGMA foreign_key_check, and PRAGMA quick_check when this store has not already been read.
Reject a database newer than the current application supports.
Create a pre-migration snapshot when an existing database needs a numbered migration, then apply the migration transactionally.
Reapply owner-only file permissions.

shell

synapse data check
synapse data check --json

Automatic backups

Before changing an existing schema, Synapse creates backups/brain.<timestamp>.v<version>.db. Before replacing an existing database during restore, it creates backups/brain.<timestamp>.restore.db.

These are complete snapshots created through SQLite VACUUM INTO, not copies of a live database file. Synapse does not currently rotate them; include the folder in your normal local backup policy and remove old snapshots deliberately.

Export a portable snapshot

shell

synapse data export "$HOME/Desktop/synapsebackup.db"
synapse data check --json

The destination must not already exist. Synapse opens the active database normally, writes a consistent compact snapshot, secures its permissions, then reopens it read-only and validates integrity before reporting success.

Restore a snapshot

Quit the Synapse desktop app.
Stop every connected MCP process by closing the relevant tool sessions.
Run the restore command from a separate terminal.

shell

synapse data restore "$HOME/Desktop/synapsebackup.db"
synapse data check

Restore opens the source read-only, validates page and relationship integrity, and requires its schema version to match the current release. It then tries to acquire the exclusive lifecycle lock. If the app or any MCP server still holds the database, restore refuses without changing anything.

When a current database exists, Synapse validates it and creates a recovery snapshot before atomically replacing it. WAL and SHM sidecars are cleared, file permissions are secured, and the containing directory is synced.

Memory wipe is not a reset

synapse memory wipe --confirm removes every memory entry and import batch but leaves SOUL.md, settings, vault labels, stored values, global mappings, and scope approvals. Use it when you want a clean memory history without rebuilding guidance or credential setup.

There is no one-command factory reset. To remove Synapse completely, first forget each secret through the app or CLI, then quit all processes and remove the application, installed launcher, and data directory deliberately. On the encrypted store the data directory is the credential store, so removing it takes every value with it — synapse uninstall --data says so before it acts.