Backup, Restore and Upgrade Your Personal AI Harness

Image: Nick on Unsplash.

A backup is a hypothesis until you have restored it into a clean environment and checked that your data and your workflows both still work. Inventory what the assistant depends on, back it up with a manifest, restore somewhere fresh, re-authorise access deliberately, then rerun your tests.

The restore is the product.

The backup is just the ingredient.

This guide is part of the AI harness engineering guide. For moving to a different provider rather than recovering the same system, see the provider exit test.

Decide what you need to recover

List everything the assistant depends on and sort it.

State	Original or derived?	Back up?
Your documents	Original	Yes
Memory records	Original	Yes
Prompts, workflows, tool contracts	Original	Yes, under version control
Evaluation cases and results	Original	Yes
Task state and pending approvals	Original, short-lived	Yes, but treat with care on restore
Run receipts and logs	Original	Yes, with retention limits
Search indexes and embeddings	Derived	Optional; can be rebuilt
Caches	Derived	No
Credentials, tokens, OAuth grants	Secret	Separately, if at all; prefer re-authorising

Then set two targets for yourself: how much recent work you can afford to lose, and how long you can be without the assistant. Those decide how often you back up and how fast the restore must be.

Design the backup manifest

A manifest makes a backup checkable.

{
  "created": "2026-10-18T22:00:00Z",
  "harness_version": "0.4.2",
  "schema_versions": { "memory": 3, "tasks": 2 },
  "files": [
    { "path": "memory/records.json", "sha256": "…", "records": 214 },
    { "path": "documents/", "sha256_tree": "…", "files": 1380 },
    { "path": "workflows/", "sha256_tree": "…", "files": 12 }
  ],
  "excluded": ["indexes/", "cache/", "secrets/"],
  "requires": ["re-authorise mail (read-only)", "re-authorise calendar (read-only)"]
}

Encrypt backups that contain personal data, and keep the key somewhere other than the backup. Keep at least one copy somewhere other than the machine running the assistant.

Leave credentials out of the main backup. Restoring old tokens can quietly bring back access you had revoked. Re-authorising takes minutes and forces a fresh look at what each connection should be allowed to do.

Restore into a clean, isolated environment

Do not test a restore on your live setup.

1. Prepare a fresh environment: a new folder, user account, virtual machine or spare computer.
2. Install the recorded harness version from the manifest.
3. Verify the backup: check every checksum before using anything.
4. Restore originals: documents, memory, workflows, tool contracts.
5. Rebuild derived data: search indexes and embeddings.
6. Keep it offline from real accounts until verification passes.

If a schema has changed since the backup, run the documented migration and check record counts before and after.

Re-authorise without reviving revoked access

Before connecting anything:

• review each connection in the manifest's requires list,
• grant the narrowest scope that still works,
• confirm that anything you revoked since the backup stays revoked,
• treat restored pending approvals as expired, and ask again.

The last point matters. An approval you gave last week was for last week's situation. Restoring it should not let an action run today without a fresh decision. The permissions guide covers approval expiry.

Verify data and behaviour

Two kinds of check, both required.

Data integrity:

checksums match the manifest,
record counts match,
a sample of memory records shows the right sources and dates,
documents open and are searchable.

Behaviour:

run your evaluation suite,
include the boundary cases, so restored permissions are tested, not assumed,
compare results with the last good run.

External effects:

check pending and uncertain actions against the outside world before replaying anything,
remember that restoring your database does not unsend an email.

The scheduling guide explains how to reconcile uncertain actions so a restore cannot cause duplicates.

Upgrade and roll back deliberately

Most restores happen after an upgrade goes wrong. Plan for it:

1. Back up immediately before upgrading, and record versions.
2. Upgrade a copy first if you can, and run the evaluation suite there.
3. Define stop conditions: failed tests, migration errors, missing records.
4. Roll back to the backup and the previous version if a stop condition is hit.

Know what rollback cannot do. It restores your system's files and records. It does not reverse emails sent, events created or payments made during the bad version. It may also not be possible after a one-way schema migration, which is why the pre-upgrade backup matters.

Maintain a recovery habit

A simple rhythm:

Frequency	Action
Daily or after changes	Automatic backup with manifest
Monthly	Verify checksums of the latest backup
Quarterly, and before major upgrades	Full restore into a clean environment and run the suite
After any incident	Restore drill, plus a regression case for what went wrong

Record each drill: date, versions, time taken, problems found. That record is the difference between believing you can recover and knowing it. For tracing what went wrong in the first place, see the troubleshooting guide.

Frequently asked questions

Is exporting memory enough to back up the whole assistant?

No. You also need documents, workflows, tool contracts, evaluation cases and enough version information to rebuild the rest.

Should API keys be restored automatically?

Usually not. Re-authorise each connection deliberately so revoked access stays revoked and scopes stay narrow.

Can restoring an old database undo a sent message?

No. Restores affect your system, not the outside world. Reconcile external actions before replaying any work.

How often should I test restoration?

At least quarterly and before major upgrades, plus after any incident.