Run it

Backing up before an upgrade

An upgrade is not a binary swap: it migrates state. The four things worth saving are config.yaml (which the new version rewrites to its own schema version), the memory store, the session database and auth.json — and nothing else, because caches and binaries are regenerated. Our archive of exactly those paths is 122 MB across 5,279 entries and takes 35 seconds; the only proof it is usable is extracting three files and comparing sha256 against the originals.

An upgrade looks like a download. It is really a migration of everything the agent knows about itself — and the part that breaks is never the download.

What an upgrade touches

Two categories, and only one of them is obvious:

  1. The binary. Replaced. If it is wrong, you roll back the binary.
  2. Your state, rewritten in place. config.yaml gets migrated to a new _config_version; the session database can gain columns; the memory store can be rewritten by a consolidation pass. If any of these goes wrong, rolling back the binary does not restore the old shape.

The second category is why the backup exists.

Size, and where the risk actually is

Measured on this machine:

Path Size Can you regenerate it?
state.db (sessions) 146 MB No — it is the history
skills/ (822 SKILL.md) tens of MB No — it is the expensive part
local-memory.json 652 KB No
memories/MEMORY.md 5,878 B (3,382 chars) No
auth.json 3 KB No, and it cannot be rebuilt at all
config.yaml 9 KB No — 22 sections of hand-tuned settings
cron/ 21 files Re-creatable by hand, painfully
cache/, bin/, logs/, bootstrap-cache/ hundreds of MB Yes — next run

The uncomfortable pairing: the file that decides whether you can log in is 3 KB, and the file that dominates the archive is 146 MB. Backing up only what is small loses the history; backing up only what is big loses the keys.

The archive

L="$LOCALAPPDATA"
tar -czf "$L/Temp/hermes-backup.tar.gz" -C "$L" \
  hermes/config.yaml hermes/auth.json hermes/local-memory.json hermes/state.db \
  hermes/memories hermes/skills hermes/cron hermes/profiles hermes/scripts

Real run, 2026-11-18:

elapsed=35s
archive: 122M
entries=5279
hermes/config.yaml         present
hermes/auth.json           present
hermes/state.db            present
hermes/cron                present

Three things to notice: 35 seconds is cheap enough to do before every upgrade; 122 MB is small enough to keep three of them; and the entry count (5,279) is the number you will compare against after a restore.

One trap, because it bit us writing this

On Windows under git-bash, -C "C:\Users\..." fails with tar (child): Cannot connect to C: resolve failed. MSYS turns the drive letter into a remote host. Use a POSIX path (/c/Users/...) or cd first and pass relative paths. The same class of bug has its own page in the platform notes.

Verify the archive, do not trust it

tar exiting 0 means the archive was written, not that it is readable. Extract three files and compare hashes:

R="$LOCALAPPDATA/Temp/restore-drill"
mkdir -p "$R"
tar -xzf "$LOCALAPPDATA/Temp/hermes-backup.tar.gz" -C "$R" \
  hermes/config.yaml hermes/memories/MEMORY.md hermes/auth.json

for f in hermes/config.yaml hermes/memories/MEMORY.md hermes/auth.json; do
  a=$(sha256sum "$LOCALAPPDATA/$f" | cut -c1-16)
  b=$(sha256sum "$R/$f" | cut -c1-16)
  printf '%-28s orig=%s restored=%s %s\n' "$f" "$a" "$b" "$([ "$a" = "$b" ] && echo MATCH || echo DIFF)"
done
hermes/config.yaml           orig=9380b09296f29604 restored=9380b09296f29604 MATCH
hermes/memories/MEMORY.md    orig=d89f7b0685e59738 restored=d89f7b0685e59738 MATCH
hermes/auth.json             orig=32974e6ed5e5d6a5 restored=32974e6ed5e5d6a5 MATCH

Three matches prove: the archive is readable, the paths are what you think, and the bytes survive the round trip. Count the entries too — tar -tzf … | wc -l — because a truncated archive can still extract the first files cleanly.

How you know it worked

A backup is proved by a restore, and a restore is proved by behaviour, not by files:

  • The binary starts and reports a version you expect.
  • grep -cE '^[a-z_]+:' config.yaml returns 22. Section count is the cheapest structural check that the config survived a migration.
  • The memory block is the same length: wc -m memories/MEMORY.md → 3,382 characters. A shorter file after an upgrade means a consolidation pass ate entries.
  • The job list still has 21 items in cron/, and the scheduler shows them.
  • The skills directory still has 66 top-level folders (822 SKILL.md). This is the number that tells you whether an idempotent file-copy step actually copied.
  • auth.json still has mode 600 after restoring. cp/tar across filesystems can drop it, and a world-readable credentials file is a different incident.

How to undo it

  • Roll back the binary, not just the config. If the upgrade migrated _config_version forward, an older binary may refuse the newer file. Restore the pair: binary and config.yaml from the same archive.
  • Keep three archives, dated. The one you need is usually the one from before the upgrade that looked fine and broke a week later.
  • Restore into a copy first. Extract to a scratch directory, start the agent with a different profile/home if your version supports it, and only then overwrite. Overwriting the live state with an unverified archive is how a backup becomes the incident.
  • Never restore state.db over a running process. Stop it, copy the file, start it. A half-written SQLite file is a corrupt one.

What we have not verified

  • A restore of the full 146 MB database followed by a schema upgrade. We verified the three small files by hash; we have not restored the DB into an older or newer version.
  • Whether auth.json survives a machine change (same drive layout, different hostname). Plausible that tokens are bound to the install id; we have not tested it.
  • Archive size at 10× the history. 122 MB is one machine with 14 sessions; the growth curve matters when the backup stops being a 35-second job.

The short version: back up the four things you cannot regenerate, archive them in 35 seconds, and prove the archive by extracting and hashing — because “I have a backup” and “I have restored this backup” are different claims.

Questions people actually ask

What does an upgrade actually change?

The binary, and the shape of your state: config.yaml gets migrated to a new _config_version, and the session database can gain columns. The parts that hurt are the migrations, not the download.

What can I skip?

cache/, bootstrap-cache/, bin/, logs/ and node/ — all regenerated on the next run. Skipping them keeps the archive at 122 MB instead of several hundred.

How big is the session database?

146 MB on this machine, and it dominates the archive. That single file is why the backup is a file copy problem and not a "just tar the config" problem.

How do I know the backup is usable?

Extract three files from the archive and compare sha256 with the live ones. If they match, the archive is readable and intact. If you never restore from it, you do not have a backup — you have a file.

Sources


Last checked: 2026-11-18 · The archive below was created and verified on this machine on 2026-11-18: 122 MB, 35 s, 5,279 entries, 822 SKILL.md files, and a three-file extract whose sha256 prefixes matched the originals exactly.