Back up and restore memory

Use Brain’s Backups page in the web app to snapshot your product’s memory or restore a completed snapshot. Restoring replaces all current memory. It does not merge records or recover just one memory.

Before you start

Select the product you intend to back up or restore. A snapshot can be restored only to the product it came from.

For MCP, use a credential scoped to that product: creation requires write access, inspection requires read, and brain_backup_restore requires admin. See MCP access.

Before restoring, check the snapshot’s date and contents. Any memory, entity, or relation created after it will be removed by the replacement. Brain takes a safety snapshot first, but recovering from a failed or unwanted restore requires another restore.

What a snapshot covers

Included	Outside the snapshot and unchanged by restore
Every memory in the product: shared, agent-private, and session memory	Daemons, their schedules, and source connection settings
Knowledge-graph entities, topics, and relations	Daemon run history and cognition state
Stored search vectors, copied back without recomputing them	Usage and billing records, API keys, and access settings

The snapshot records its product, creation time, memory mode, memory and relation counts, size, engine version, and vector size. Entities are included in the data but not added to the memory count; relations have their own count.

Take a snapshot

Open Backups and start an on-demand snapshot. There are no options for a partial snapshot or a different product. Over MCP, call brain_backup_create without arguments.
Keep the returned snapshotId. The request returns accepted immediately while export runs in the background. The web page refreshes during processing; over MCP, poll brain_backup_status with that ID.
Wait for completed. Only a completed snapshot is restorable. A failed entry includes its error.

Only one on-demand snapshot can run per product at a time; a second request is rejected. Scheduled and safety snapshots can run alongside it. While a restore is running, both snapshot creation and another restore are blocked.

An on-demand export still running after 15 minutes is marked failed as stale. A slow export may nevertheless finish and leave two entries for the same attempt. Completed snapshots from that attempt can be restored.

Find and retain snapshots

The list shows the 50 most recent snapshots, newest first. With MCP, use brain_backups_list, or brain_backup_status with a snapshotId. Omitting snapshotId asks for the latest snapshot.

Snapshot kind	When created	Retention
Scheduled	Daily at 04:00 UTC for products holding memory	30 days
On demand	When you request it	90 days
Safety snapshot	Before every restore	90 days

Completed snapshots expire. Cleanup runs daily at 05:00 UTC and deletes both the stored data and its entry. Failed entries remain as records. There is no snapshot count or size limit.

Statuses are running, completed, or failed. Counts, size, engine version, and vector size remain empty until completion. Each entry also shows its ID, trigger, creation and update times, and any error.

Restore a snapshot

In Backups, choose a completed snapshot from the current product. Check its date: everything currently remembered will be wiped before the snapshot is loaded. There is no dry run, merge mode, or per-record reconciliation.
Give explicit confirmation and repeat the current product’s identifier. Over MCP, brain_backup_restore requires snapshotId, confirm: true, and confirmProductId matching that product exactly.
Keep the returned restoreId. Watch the restore in the web app, or poll brain_restore_status with restoreId. Acceptance is not completion.
Wait for the final state, then perform the result check below.

Checks before replacement

Brain checks access, confirmation, product ownership of the snapshot, and vector size before deleting memory. A vector-size mismatch blocks restoration because vectors are copied without recomputation. If the configured vector size changes, older snapshots with a different size cannot be restored. An engine-version difference is recorded but does not block the restore.

When processing starts, these checks run again, including a check that the snapshot’s internal scope names the current product. A failure at that point stops processing before the wipe.

Restore stages

Stage	What happens
Safety snapshot	Brain exports current memory and records the safety snapshot’s ID.
Wipe	Brain deletes the product’s current memory.
Load	Memories and entities are loaded first, then relations.
Finish	The restore reports memory and relation counts.

Restore states are pending, wiped, importing, completed, and failed. The record contains the restore ID, source snapshot, safety snapshot, status, counts, errors, and start and finish times. The web app shows the current or most recent restore; MCP status lookup requires its restoreId.

Verify it works

Check that the restore is completed, then open Browse and search for a known statement from the chosen snapshot. Inspect a graph entity if the snapshot included graph data.

The reported counts come from the snapshot’s recorded totals; they are not per-record verification during loading. Snapshots record a checksum, but restore does not verify it. Completion and counts alone do not replace checking the memory you expected to recover.

Recover from a problem

Problem	What to do
Restore fails before the wipe	Current memory was not deleted; read the error and fix the failed check.
Restore fails after the wipe, leaving memory empty	Start a new restore from the safety snapshot recorded in the failed restore.
Restore was unwanted	Restore its safety snapshot to return to the preceding memory. It expires after 90 days.
No progress for 30 minutes	The restore is marked `failed`. Underlying work may later finish, but that terminal status stays failed. Inspect actual memory before assuming nothing loaded.
Very old snapshot is too large to load	Older exports were read in one piece and can exceed the allowed processing time. A fresh snapshot uses the current multipart format.

Metering

Snapshot creation and restoration are not metered and consume none of Brain’s quotas. They use no language model; restoring stored vectors uses no embedding tokens. See what Brain meters for other operations.

Was this page helpful?