Migrating Hermes Agent: The Right Way to Restore From Backup

How I moved my AI agent to a new server without losing a single conversation, memory, or skill

The Problem

I run Hermes Agent — a personal AI agent that handles my crypto research, social media posting, three Telegram profiles, scheduled reports, and a growing knowledge base.

One day I asked the obvious question: "How do I move you to another server?"

The answer turned out to be deceptively simple — and full of traps.

What Hermes Actually Is

Everything Hermes knows lives in one folder:

~/.hermes/
├── config.yaml          # settings
├── .env                 # API keys (DeepSeek, Alibaba, Telegram bots)
├── state.db             # ALL conversation history (12,000+ messages)
├── memories/            # long-term memory
├── skills/              # learned procedures
├── profiles/            # separate agents (each with own bot)
├── scripts/             # cron scripts, social posting
└── knowledge.db         # my knowledge base (23 entries and growing)

A backup of this folder IS the migration. No export wizard, no cloud sync — just files.

The Critical Mistake (Almost Everyone Makes)

My first instinct was:

"Install Hermes on the new server, THEN overwrite the files from backup."

WRONG. Here's why:

1. Fresh install creates a fresh config.yaml, state.db, memories/
2. Overwriting them later creates a mix of old and new — version conflicts, lost memory, orphaned sessions
3. You end up debugging why your agent "forgot" things

The Right Order

Unpack the backup FIRST. Install Hermes SECOND.

# 1. Create the user
sudo useradd -m -s /bin/bash hermes

# 2. Unpack the backup (decrypted tar.gz)
cd /home
sudo tar -xzf hermes_light.tar.gz

# 3. Fix ownership
sudo chown -R hermes:hermes /home/hermes

# 4. Install the code (venv) — it reads configs from ~/.hermes
cd /home/hermes/.hermes/hermes-agent
python3 -m venv venv
venv/bin/pip install -e .

# 5. Copy systemd units
sudo cp hermes-gateway*.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now hermes-gateway hermes-gateway-profiles

Hermes is smart: when it sees an existing ~/.hermes/config.yaml, it uses it instead of creating a new one. Memory, profiles, history, skills — all picked up automatically.

What Survives

The Backup Script

To make this repeatable, I wrote a small script that does tar + GPG encryption in one command. Two modes:

The raw full backup (uncompressed) is ~8.7 GB — gzip brings it down to 2.6 GB because binaries compress well.

What's included in FULL:

Both modes are encrypted with GPG (asymmetric, ED25519 key) before the archive leaves the server. The public key lives on the server; the private key stays on my Windows machine — so even a compromised server can't read the backup.

Light is the right choice for migration — venv and git history rebuild in minutes (pip install -e . + git pull), but conversations and memory never do. Full is for archival when you want an exact snapshot of everything.

Lessons Learned

1. Backup the irreplaceable, skip the recreatable. venv and .git rebuild in minutes; conversations and memory never do.
2. Encrypt before downloading. Your state.db contains every private conversation. GPG on the server, decrypt on Windows with Kleopatra.
3. Unpack before install. The agent adopts existing files like a parent adopts a child — but only if the files are there first.
4. Test the restore. We tested both light and full modes. The script works, the backup is verified, the restore path is documented.

The Takeaway

Moving an AI agent is just file management — IF you know the one golden rule:

Restore data first. Install software second. Never let a fresh install overwrite what you've already restored.