Migra Hermes Agent a una máquina nueva sin perder memoria

Por qué solo tienes una oportunidad de migrar Hermes

Un Hermes Agent que funciona es mucho más que el binario. Son meses de entradas de memoria, un SOUL.md personalizado, una pequeña librería de skills a medida, una tabla de cron con los digests que de verdad usas, un índice vectorial de ChromaDB que el agente ha ido construyendo en silencio y una sesión de Telegram que ya sabe quién eres. Reinstala Hermes en una máquina nueva y nada de eso viaja contigo. Te quedas con un desconocido que comparte tu nombre de usuario.

Este es el escenario contra el que escribimos esta guía. Si tu portátil está a punto de morir, estás pasando de Docker en tu equipo de escritorio a un VPS de verdad, subes de gama tu instancia en Hetzner o quieres una restauración limpia después de un fallo de disco, el proceso es el mismo: captura todo el árbol ~/.hermes/ en la máquina vieja, muévelo a la nueva, ejecuta hermes import y verifica. Hecho en el orden correcto es un trabajo de quince minutos. En el orden equivocado, o pierdes datos o pasas la noche re-autenticando proveedores, IMAP y Telegram.

Si aún estás comparando el self-hosting con un setup gestionado, self-hosting frente a Hermes Agent gestionado es una buena primera lectura, porque Hermify se encarga de las migraciones por ti y esta guía deja de tener sentido. Si vas a ejecutarlo tú, sigue leyendo.

Qué empaqueta realmente hermes backup

El comando hermes backup produce un archivo con marca temporal parecido a hermes-backup-2026-06-01-101955.zip. Captura el contenido de ~/.hermes/, que es donde Hermes guarda todo lo que hace que tu agente sea tuyo. En una instalación madura, ese árbol incluye:

• La base de datos de estado (state.db y archivos relacionados): la fuente de verdad para sesiones, historial de llamadas a herramientas y colas de tareas.
• El vector store de ChromaDB: el índice de memoria semántica que el agente consulta cada vez que necesita recordar algo. Es un directorio de archivos binarios, no un JSON suelto, y hay que moverlo como una unidad.
• SOUL.md, AGENTS.md, USER.md, MEMORY.md: la personalidad, las normas de la casa, el perfil del usuario y la memoria de largo plazo en prosa. Son markdown plano, pero el agente espera encontrarlos en rutas exactas.
• El directorio skills/: todas las skills a medida que has escrito o instalado. Una skill es solo una carpeta con un SKILL.md y sus archivos, pero si falta una, el agente pierde una capacidad en silencio.
• El directorio identity/: la configuración de la persona, el avatar y los presets del modo voz.
• La tabla de cron: las tareas programadas viven dentro de ~/.hermes/, no en el crontab del sistema. Si las pierdes, tu resumen matinal deja de llegar sin avisar.
• Secretos y configuración: config.yaml, claves de API de proveedores, el token del bot de Telegram, credenciales de IMAP/SMTP, secretos de firma de webhooks y cualquier fragmento .env cifrado que el agente haya consumido.

Hay dos flags que importan. hermes backup --quick se salta el escaneo completo de archivos e incluye solo config, sesiones, claves y auth. Es más rápido y más pequeño, pero no lleva memoria ni skills, así que solo sirve para clonar la identidad del agente en una máquina que va a construir su propia memoria desde cero. Para una migración de verdad, ejecuta hermes backup sin flags y deja que se tome el tiempo que necesite.

Paso 1 - Congela la máquina origen

Antes de hacer el backup, silencia al agente. Si Hermes está escribiendo activamente en state.db mientras se genera el archivo, puedes acabar con una base de datos corrupta dentro del zip.

# Si ejecutas Hermes como servicio systemd
sudo systemctl stop hermes

# O si lo ejecutas vía Docker
docker compose stop hermes

# O si lo lanzaste de forma interactiva, sal limpio con Ctrl+C en el shell donde corre

Cuando ya nada tenga la base de datos de estado abierta, genera el backup:

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

Anota la ruta completa que imprime. Ese es el archivo que vas a mover.

Paso 2 - Mueve el archivo con cabeza

El backup contiene secretos. Trátalo como una clave SSH.

• No lo subas a un enlace público, un adjunto de Discord ni un DM de Slack a ti mismo.
• Prefiere scp o rsync sobre SSH, o una carpeta de syncthing en la que ya confíes.
• Si tienes que pasar por un portátil como salto intermedio, borra la copia local en cuanto termine la transferencia.

Una transferencia segura de un VPS viejo a uno nuevo se ve así:

# Desde la máquina nueva
scp vps-viejo:~/.hermes/backups/hermes-backup-2026-07-18-102301.zip ~/

Si estás moviéndolo de un portátil personal a un VPS, hazlo al revés y empuja desde el origen. En cualquier caso, deja el archivo en el home del usuario de destino, no en /tmp ni en una ruta compartida.

Paso 3 - Instala Hermes en el destino

Instala Hermes en la máquina nueva igual que harías para un setup limpio. Es decir, Linux, macOS, WSL2 en Windows o Termux en el móvil, que son los objetivos oficialmente soportados. Sigue la ruta de instalación que coincida con cómo vas a ejecutarlo a largo plazo, ya sea Hermes Agent en Docker, una instalación nativa en Linux o Windows con WSL2.

No arranques todavía el agente. Si se lanza una vez con un ~/.hermes/ vacío, escribirá un state.db fresco y la config por defecto, que van a chocar con el import del siguiente paso. Instala el binario, verifica que hermes --version imprime la misma versión mayor que la máquina origen y párate ahí.

Paso 4 - Importa y reindexa

Con el archivo en su sitio y el binario instalado pero sin ejecutarse:

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

El importador descomprime el archivo dentro de ~/.hermes/, restaura la base de datos de estado y coloca skills, memoria, tareas cron, identidad y secretos en su lugar. Al terminar, reconstruye el índice vectorial para que la búsqueda semántica ordene los resultados con el modelo actual y no con el que usaba la máquina origen:

hermes memory reindex

Si tomaste el backup en una versión de Hermes bastante más antigua, el payload de memoria puede usar un formato legacy. En ese caso, extrae las memorias por separado con un export JSON y vuelve a importarlas explícitamente:

hermes memory import --legacy ~/memories.json

El flag --legacy le dice a Hermes que acepte el esquema antiguo y lo actualice en el momento. hermes memory export --output ~/memories.json en el origen es el comando compañero, útil cuando solo quieres migrar la memoria y reconstruir el resto desde una instalación limpia.

Paso 5 - Verifica antes de confiar

Aquí hay dos comandos que se ganan el sueldo:

hermes doctor   # config, dependencias, alcance de proveedores, permisos de disco
hermes status   # salud del gateway, contador de memoria, integraciones activas

hermes doctor debería devolver verde en config, base de datos, ChromaDB y credenciales de proveedor. hermes status debería mostrar un contador de entradas de memoria cercano al que tenías en el origen, la integración de Telegram como conectada y cualquier tarea programada de larga duración en cola. Si alguno de los dos marca algo, arréglalo antes de volver a encender el gateway.

Después, arranca el agente y mándale desde Telegram un mensaje que necesite tirar de memoria. "¿Qué habíamos decidido del lanzamiento del Q3?" es una buena prueba. Si contesta con contexto, la memoria migró bien. Si dice que no lo sabe, prueba con hermes memory search "lanzamiento Q3" desde la CLI: puede que la memoria esté ahí y que el índice vectorial aún no haya terminado de reconstruirse.

Los detalles de los que nadie te avisa

Incluso un import limpio deja algunos bordes ásperos. Repasa esto antes de dar la migración por cerrada.

• Los secretos cifrados necesitan su clave de descifrado. Si tu máquina origen usaba un almacén de secretos cifrado (Hermes soporta pass, gnome-keyring o un keyfile), el archivo contiene el texto cifrado pero no la clave. Transfiere el keyfile por separado o desbloquea el almacén en la máquina nueva antes del primer arranque del agente.
• Las credenciales de IMAP y SMTP pueden pedir reautenticación. Las app passwords atadas a la huella de un dispositivo a veces se niegan a autenticar desde una IP nueva. Google Workspace y Fastmail son los sospechosos habituales. Rota la app password si la integración de correo se queda muda tras el import.
• La sesión de Telegram puede desviarse. El token del bot de Telegram es portable, pero si además usabas una sesión en modo usuario para leer chats, el archivo de sesión puede estar ligado al dispositivo antiguo. Borra ~/.hermes/telegram/session.session y deja que el agente se vuelva a autenticar en el siguiente arranque.
• Las tareas de cron arrancan en su próximo tick programado, no de inmediato. Si tu daily-digest estaba programado a las 07:00 y terminas la migración a las 07:05, no volverá a dispararse hasta mañana. Lánzalo a mano una vez con hermes cron run daily-digest para comprobar que funciona.
• Rota cualquier cosa que el archivo haya tocado. Incluso con una transferencia cuidadosa, un archivo que contenía tokens de bot y claves de proveedor ha vivido en más máquinas que los dos extremos. Si la migración fue reacción a un compromiso, o si el archivo pasó por almacenamiento compartido, rota la clave de OpenAI/Anthropic/OpenRouter y vuelve a emitir el token del bot en BotFather.

Cuando no quieras hacer todo esto tú

Todo el ritual (congelar, hacer backup, transferir, instalar, importar, reindexar, verificar, rotar) es lo que un host gestionado hace por debajo. Hermify ejecuta un Hermes Agent gestionado en un VPS que operamos nosotros, hace backups cifrados diarios y te da una restauración con un clic si algún día un VPS se tiene que reemplazar. En el día a día del usuario no existe un paso de "moverme a una máquina nueva", porque la máquina es nuestro problema, no el tuyo.

Si decides que eso te encaja más que lanzar esta migración cada año o cada dos, empieza con Hermify: tu agente entra en Telegram en aproximadamente un minuto, tu memoria sigue siendo tuya y el próximo cambio de hardware pasa invisible para ti.

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