Migrate Hermes Agent to a New Machine Without Losing Memory

Why You Only Get One Shot at a Hermes Migration

A working Hermes Agent is more than the binary. It is months of memory entries, a personalized SOUL.md, a small library of custom skills, a cron table with the digests you actually rely on, a ChromaDB vector index the agent has been quietly building, and a Telegram session that already knows who you are. Reinstall Hermes on a fresh box and none of that comes with it. You end up with a stranger that shares your username.

That is the failure mode this guide is written against. If your laptop is about to die, you are switching from Docker on your desktop to a proper VPS, you are upgrading a Hetzner instance class, or you just want a clean-machine restore after a disk failure, the process is the same: capture the full ~/.hermes/ tree on the old machine, move it to the new one, run hermes import, and verify. Done in the right order it is a fifteen minute job. Done in the wrong order you either lose data or spend an evening re-authenticating providers, IMAP, and Telegram.

If you are still comparing self-hosting to a managed setup, self-hosting vs managed Hermes Agent is worth reading first, because Hermify handles migrations for you and this whole guide becomes irrelevant. If you are committed to running it yourself, read on.

What hermes backup Actually Packages

The hermes backup command produces a timestamped archive that looks like hermes-backup-2026-06-01-101955.zip. It captures the contents of ~/.hermes/, which is where Hermes stores everything that makes your agent yours. On a mature installation that tree includes:

• The state database (state.db and related files) - the source of truth for sessions, tool call history, and job queues.
• The ChromaDB vector store - the semantic memory index the agent searches whenever it needs to remember something. This is a directory of binary files, not a JSON blob, and it needs to move as a unit.
• SOUL.md, AGENTS.md, USER.md, MEMORY.md - the personality, house rules, user profile, and long-term memory prose. These are plain markdown, but the agent expects to find them at exact paths.
• The skills/ directory - every custom skill you have written or installed. Skills are just folders with a SKILL.md and any files they reference, but a missing skill means the agent silently loses a capability.
• The identity/ directory - the persona configuration, avatar, and any voice-mode presets.
• The cron table - scheduled tasks live inside ~/.hermes/, not in the host system's crontab. Losing them means your morning digest quietly stops arriving.
• Secrets and config - config.yaml, provider API keys, the Telegram bot token, IMAP/SMTP credentials, webhook signing secrets, and any encrypted .env fragments the agent has consumed.

Two flags matter. hermes backup --quick skips the full file scan and includes only config, sessions, keys, and auth. It is faster and smaller, but it does not carry memory or skills, so it is only useful if you are cloning the agent's identity onto a machine that will build its own memory from scratch. For a real migration, run hermes backup with no flags and let it take its time.

Step 1 - Freeze the Source

Before you take the backup, quiet the agent. If Hermes is actively writing to state.db during the archive, you can end up with a corrupted database in your zip.

# If you run Hermes as a systemd service
sudo systemctl stop hermes

# Or if you run it via Docker
docker compose stop hermes

# Or if you launched it interactively, exit cleanly with Ctrl+C in the shell running it

Once nothing is holding the state database open, take the backup:

hermes backup
# writes ~/.hermes/backups/hermes-backup-2026-07-18-102301.zip

Note the full path it prints. That is the file you are going to move.

Step 2 - Move the Archive Safely

The backup contains secrets. Treat it like an SSH key.

• Do not upload it to a public share link, a Discord attachment, or a Slack DM to yourself.
• Prefer scp or rsync over SSH, or a syncthing folder you already trust.
• If you must go via a laptop as an intermediate hop, delete the local copy the moment the transfer completes.

A safe transfer from an old VPS to a new one looks like:

# From the new machine
scp old-vps:~/.hermes/backups/hermes-backup-2026-07-18-102301.zip ~/

If you are moving from a personal laptop to a VPS, do it the other way around and push from the source. Either way, land the file somewhere in the target user's home directory, not /tmp, and not a shared path.

Step 3 - Install Hermes on the Target

Install Hermes on the new machine the same way you would for a fresh setup. That means Linux, macOS, WSL2 on Windows, or Termux on a phone - those are the officially supported targets. Follow the installation path that matches how you plan to run it long-term, whether that is Hermes Agent in Docker, a native install on Linux, or Windows via WSL2.

Do not start the agent yet. If it launches once with an empty ~/.hermes/, it will write a fresh state.db and default config, which will collide with the import in the next step. Install the binary, verify hermes --version prints the same major version as the source machine, and stop there.

Step 4 - Import and Rebuild

With the archive in place and the binary installed but not running:

hermes import ~/hermes-backup-2026-07-18-102301.zip

The importer unpacks the archive into ~/.hermes/, restores the state database, and copies skills, memory, cron jobs, identity, and secrets into place. On finish, rebuild the vector index so semantic search returns results ranked against the current model rather than whatever the source machine last used:

hermes memory reindex

If you took the backup on a much older Hermes version, the memory payload may use a legacy format. In that case, extract memories separately from a JSON export and re-import them explicitly:

hermes memory import --legacy ~/memories.json

The --legacy flag tells Hermes to accept the older schema and upgrade it in place. hermes memory export --output ~/memories.json on the source is the companion command, useful when you want to migrate memory only and rebuild everything else from a clean install.

Step 5 - Verify Before You Trust It

Two commands earn their keep here:

hermes doctor   # config, dependencies, provider reachability, disk permissions
hermes status   # gateway health, memory count, active integrations

hermes doctor should return green on config, database, ChromaDB, and provider credentials. hermes status should show a memory entry count close to what you had on the source, the Telegram integration as connected, and any long-running scheduled tasks queued. If either flags something, fix it before you turn the gateway back on.

Then start the agent and send a message from Telegram that requires memory recall. "What did we decide about the Q3 launch?" is a good probe. If the agent answers from context, the memory move worked. If it says it does not know, run hermes memory search "Q3 launch" from the CLI - the memory may be there but the vector index has not fully rebuilt yet.

The Gotchas Nobody Warns You About

Even a clean import can leave a few edges rough. Walk through these before you consider the migration done.

• Encrypted secrets need their decryption key. If your source machine used an encrypted secrets store (Hermes supports pass, gnome-keyring, or a keyfile), the archive contains the ciphertext but not the key. Transfer the key file separately or unlock the store on the new machine before the first agent run.
• IMAP and SMTP creds may need re-auth. App passwords tied to a device fingerprint sometimes refuse to authenticate from a new IP. Google Workspace and Fastmail are the common offenders. Rotate the app password if the mail integration is silent after import.
• Telegram session can drift. The Telegram bot token is portable, but if you were also using a user-mode session for reading chats, the session file may be tied to the old device. Delete ~/.hermes/telegram/session.session and let the agent re-auth on next start.
• Cron jobs restart at their next scheduled tick, not immediately. If your daily-digest was scheduled for 07:00 and you finish the migration at 07:05, it will not fire until tomorrow. Trigger it manually once with hermes cron run daily-digest to prove it works.
• Rotate anything the archive touched. Even with a careful transfer, an archive containing bot tokens and provider keys has existed on more machines than the two endpoints. If the migration was in response to a compromise, or if the archive passed through any shared storage, rotate the OpenAI/Anthropic/OpenRouter key and re-issue the Telegram bot token from BotFather.

When You Do Not Want to Do This Yourself

The whole ritual - freeze, backup, transfer, install, import, reindex, verify, rotate - is what a managed host does automatically. Hermify runs a managed Hermes Agent on a VPS we operate, takes daily encrypted backups, and gives you a one-click restore if a VPS ever needs to be replaced. There is no "move to a new machine" step in the user's day, because the machine is our problem, not yours.

If you decide that is a better fit than running the migration yourself every year or two, Get started with Hermify - your agent is live on Telegram in about a minute, your memory stays yours, and the next hardware change is invisible to you.

Sources

• How to Backup and Restore Hermes Agent Memory - hermes-agent.ai
• How to backup and migrate Hermes Agent server - Tool Navigators
• Hermes Agent backups: state.db, skills, identity - LumaDock
• Backup Hermes Agent - j3ffyang, Medium
• CLI Commands Reference - Hermes Agent official docs