# Back up and restore memory

A snapshot is a complete copy of everything one product remembers, kept for a fixed period and restorable in one operation. Restoring is a full replace: what the product remembers now is wiped and the snapshot takes its place, so read [what a restore does](#restore-a-snapshot) before you start one.

Both operations are capabilities of Brain itself. See [look up a Brain tool](/reference/mcp-tools) for the calls.

## What a snapshot covers

| Included | Not included |
|---|---|
| Every memory the product holds, in every scope — the shared pool, each agent's private memory and each session's own memory | Daemons and their schedules |
| The knowledge graph — entities, topics and the relations between them | Connections to GitHub, Google Drive and ClickUp, and the settings of the sources built on them |
| The search vectors computed for those memories, stored and copied back as they are | Daemon run history and the state of cognition |
| | Usage and billing records |
| | Access settings and API keys |

Nothing is left out of a snapshot because of who wrote it or which agent it belongs to. Nothing outside memory is backed up, and nothing outside memory is touched by a restore.

Each snapshot also records, for itself: when it was created, which product it belongs to, the memory mode it was taken in, the number of memories and relations, its size, the engine version and the vector size it was built with. The last two matter when you come to restore it.

## Take a snapshot

1. **Start the export.** Nothing is configurable — there is no way to snapshot part of memory and no way to snapshot a different product. The request is accepted immediately, you get a snapshot identifier straight away, and the export runs in the background.
2. **Watch it reach a final state.** A snapshot is `running`, then either `completed` or `failed`. Only a `completed` snapshot can be restored.
3. **Read what it holds.** A completed entry carries its identifier, how it was triggered, when it was created and last changed, the number of memories and relations, and its size. A failed one carries the reason instead.

Brain also snapshots every product that holds memory once a day, at 04:00 UTC. You do not configure this and it consumes nothing you are billed for. A third kind appears on its own: before every restore Brain takes a **safety snapshot** of the memory that is about to be replaced, marked as taken before a restore.

> Only one on-demand snapshot can be in flight per product; starting a second while the first runs is rejected. The daily snapshot and the safety snapshot are exempt and can run alongside one. While a restore is running, both new snapshots and a second restore are blocked until it finishes.

> An on-demand snapshot still running after 15 minutes is marked failed. This is a safety valve, not a limit on your data: a genuinely slow export reclaimed this way may finish anyway, so one attempt can leave two entries. Both are complete snapshots and either can be restored.

Counts read literally. The number of memories is the memories alone — knowledge-graph entities are stored in the snapshot and restored from it, but are not added into that figure, and relations are counted separately. The counts, size, engine version and vector size stay empty until the snapshot completes, because they are only known once the export has been written.

## Find a snapshot

- **Look one up by its identifier** when you already know which snapshot you mean.
- **Ask for the latest one** for the product without naming an identifier at all.
- **List them** to see the 50 most recent, newest first.

## How long snapshots are kept

| How it was taken | Kept for |
|---|---|
| Daily scheduled | 30 days |
| On demand | 90 days |
| Taken before a restore | 90 days |

Only completed snapshots expire; a failed entry stays as a record. Expired snapshots are removed once a day, at 05:00 UTC, and removal deletes the stored data as well as the entry. There is no limit on how many snapshots a product may hold and no limit on how large one may be.

## Restore a snapshot

**A restore replaces memory; it does not merge.** Brain wipes everything the product currently remembers and then loads the snapshot in its place. There is no merge mode, no dry run and no per-record reconciliation. Nothing is deduped, skipped or duplicated, because nothing survives the wipe: any memory, entity or relation created after the snapshot was taken is gone when the restore completes.

You can only restore a snapshot of your own current product, and you confirm twice — an explicit confirmation, plus the product's own identifier repeated back. A snapshot belonging to another product cannot be named. Membership of the product is what grants the right to do this; there is no separate backup role.

### What is checked before anything is destroyed

Brain refuses the restore, without touching your memory, if:

- the confirmation is missing, or the repeated product identifier does not match,
- you are not a member of the product,
- the snapshot does not exist, or does not belong to this product,
- the snapshot's vector size differs from the one Brain uses now.

Vectors are restored exactly as they were stored and are never recomputed, so a snapshot built at a different vector size cannot be loaded at all. If that setting ever changes, snapshots taken before the change stop being restorable. A difference in engine version between the snapshot and the running Brain is **not** blocking — it is recorded and the restore proceeds.

> These checks run a second time when the work actually starts, together with a check that the snapshot's own internal scope names this product. A failure at that point stops the restore before the wipe, and your memory is untouched.

### The stages

1. **Safety snapshot.** The current memory is exported first, and the restore records which snapshot that was.
2. **Wipe.** Everything the product remembers is deleted.
3. **Load.** Memories and entities are written first, then the relations between them, so that both ends of a relation exist before it is created.
4. **Finish.** The number of restored memories and relations is reported.

A restore is `pending`, `wiped`, `importing`, `completed` or `failed`. You can check the running one, or the product's most recent one, at any time. Its record carries the restore identifier, the snapshot it came from, the safety snapshot taken before it, the status, the number of memories and relations, the error if it failed, and when it started and finished.

> The counts on a finished restore are the counts the snapshot recorded for itself, not a measurement taken while loading. They tell you how large the snapshot was, not that every record was verified on the way in.

## What can go wrong

| Situation | What to do |
|---|---|
| A failure after the wipe leaves the product empty | Start a new restore from the safety snapshot taken in stage 1. A restore that failed before the wipe deleted nothing and needs no undo. |
| The safety snapshot is gone | It expires after 90 days, like any other on-demand snapshot. It is not kept indefinitely. |
| A restore makes no progress for 30 minutes | It is marked failed. If the underlying work later finishes, the data is in place but the status stays `failed` — a terminal status is never rewritten. Check what the product actually remembers before assuming the restore did nothing. |
| A very old snapshot is too large to restore | Snapshots taken before Brain began splitting exports into parts are read in one piece, and a large one can exceed the time allowed. Create a fresh snapshot, which uses the current format. |
| You expected the snapshot's checksum to be verified | Snapshots record a checksum, but a restore does not verify it. What is verified is that the snapshot belongs to this product and was built at the vector size in use now. |

## Billing

Creating a snapshot and restoring one are not metered and consume none of your allowances. Restoring writes stored vectors back as they are, so it spends no embedding tokens, and neither operation uses a language model.

## Next steps

- [Check what Brain meters](/brain/limits-and-usage): the five meters, and what happens when the month's allowance runs out.
- [Read what a memory is](/brain/memory-model): the scopes a snapshot covers, and what the counts refer to.
- [Search the knowledge graph](/brain/knowledge-graph): the entities and relations a snapshot carries alongside the memories.
- [Ingest a source on a schedule](/brain/daemons): daemons are outside a snapshot and survive a restore untouched.
- [Look up a Brain tool](/reference/mcp-tools): the calls that create, list and restore a snapshot.