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:
- The binary. Replaced. If it is wrong, you roll back the binary.
- Your state, rewritten in place.
config.yamlgets 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.yamlreturns 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.jsonstill has mode 600 after restoring.cp/taracross 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_versionforward, an older binary may refuse the newer file. Restore the pair: binary andconfig.yamlfrom 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.dbover 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.jsonsurvives 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.
Related
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.