Backup de memoria antes de actualizar, para que no llores por un bug de migración de esquema

Las actualizaciones rara vez son el problema. El problema son las actualizaciones en las que algo sale mal. En abril tuve una migración de Prisma que le forzó sin querer una constraint nueva a nuestra tabla agent_observations. Unas 4.000 observations quedaron muertas. Por suerte teníamos un pg_dump de dos días antes, si no se habría ido toda la capa de memoria de la fleet. Desde entonces, backup antes de actualizar es obligatorio, no un lujo. Aquí está la rutina que sigo desde entonces.

1. Tener claro qué hay que respaldar en realidad

La memoria no es solo la base de datos. Son varias cosas juntas. La base de datos Postgres con todas las tablas agent_* es el bloque grande. Luego las configuraciones, o sea ~/.claude/settings.json, ~/.claude/mcp.json o .claude.json según el setup. Luego las skills y los subagentes bajo ~/.claude/skills/ y ~/.claude/agents/. Y si alojas tú mismo servidores MCP, también su estado (a menudo Postgres o SQLite igualmente).

Si solo aseguras la base de datos y te olvidas de las configuraciones de .claude, en una emergencia restauras a un entorno donde Claude no sabe qué servidores MCP existen. Lo hice una vez y luego pasé dos horas reconfigurando herramientas.

2. De qué base de datos estamos hablando

Comprueba dónde vive tu memoria de verdad. En la mayoría de los setups que he visto es Postgres, en local o en un servidor. Míralo en la configuración MCP. En mi caso es postgres://localhost:5433/your_app_db con las tablas nex_* y agent_* dentro.

Si usas una solución de memory-as-a-service (o sea la variante alojada), la base de datos no está en tu lado. Entonces tu tarea de backup es una llamada a una API de exportación o un snapshot del proveedor de hosting. Acláralo antes, no mientras ocurre el desastre.

3. El comando pg_dump que funciona de verdad

No uses solo pg_dump dbname > file.sql. Eso se vuelve inmanejable rápido con bases de memoria grandes. El formato custom con compresión es mejor.

pg_dump \
  --host=localhost \
  --port=5433 \
  --username=postgres \
  --dbname=your_app_db \
  --format=custom \
  --compress=9 \
  --file=memory-backup-$(date +%Y-%m-%d-%H%M).dump

Eso te da un fichero binario compacto que se lee con pg_restore. En mi caso, para una base de 107 MB salen unos 18 MB de backup. Compress 9 es lento, pero para un paso al día o por actualización da igual.

Opcionalmente puedes poner --exclude-table='pg_*' si quieres dejar fuera las cosas del sistema, aunque el formato custom lo ignora en buena medida de todos modos.

4. Asegurar las configuraciones por separado

Un tarball de todo el directorio .claude. Pequeño, rápido, completo.

tar -czf claude-config-$(date +%Y-%m-%d).tar.gz \
  -C "$HOME" .claude

Si tienes secretos en las configuraciones (claves de API en mcp.json), tómatelo en serio y no dejes el tarball en un bucket público. Guárdalo cifrado o déjalo en local. Antipatrón clásico: script de backup que sube a S3 sin que nadie revise la política del bucket.

5. Una restauración de prueba en una segunda base de datos

Un backup sin test de restauración no es un backup. Eso lo aprendí a las malas una vez. Hazlo una vez ahora y sabrás que funciona.

createdb -h localhost -p 5433 -U postgres memory_restore_test
pg_restore \
  --host=localhost --port=5433 --username=postgres \
  --dbname=memory_restore_test \
  --no-owner --no-privileges \
  memory-backup-2026-05-19-1430.dump

Después haz un SELECT count(*) FROM agent_observations; en la base de prueba y compáralo con la real. Si los números cuadran, tu backup es bueno. Luego un dropdb a la base de prueba.

Este test lo haces una vez al montarlo todo y después otra vez tras cada actualización de esquema grande. No a diario. Si no, se vuelve pesado.

6. Ciclo de vida del backup, cuántos conservar

Tres niveles que a mí me han funcionado. Últimos 7 días, uno por día. Después las últimas 4 semanas, uno por semana. Después los últimos 12 meses, uno por mes.

Con compress 9 y el tamaño de mi base son en total unos 1 GB de volumen de backup. En un servidor de 500 GB es irrelevante. En una Storage Box de Hetzner sale barato.

Un patrón concreto de script de limpieza (no lo copies tal cual, adáptalo a tu estructura):

# Conserva los últimos 7 diarios, borra el resto
find ./backups/daily -name "memory-backup-*.dump" -mtime +7 -delete

7. Automatizar con cron, pero con mail de aviso

Los backups que nadie revisa no son backups. Una entrada de cron que hace el dump cada noche a las 3 y te manda el resultado por mail.

0 3 * * * /usr/local/bin/memory-backup.sh 2>&1 | mail -s "Memory Backup $(hostname)" you@example.com

Si pasas una semana sin recibir mail, sabes que algo está roto. Pero si el mail dice "OK" todos los días, a las tres semanas lo ignoras y sigues sin enterarte. Mejor: mail solo cuando falla. O un servicio de healthcheck que reciba un ping cuando el script corre y avise si lleva 30 horas sin oír nada.

8. Un dump fresco antes de cada actualización

Este es el punto de verdad del playbook. Antes de cada ejecución de migración, antes de cada db push de Prisma, antes de cada migrate deploy, haz un dump y nómbralo con claridad.

pg_dump ... --file=memory-pre-update-$(date +%Y-%m-%d-%H%M)-VOR-PRISMA-MIGRATE.dump

Suena excesivo, pero es disciplina. Si la migración sale bien, borras el dump una semana después. Si no sale bien, tienes el estado correcto de hace 10 minutos y no el de anoche.

En mi caso eso corre como hook de pre-commit sobre la carpeta de migraciones de Prisma. Cuando cambia un fichero de esquema, git pregunta si quiero hacer backup antes. 80 por ciento sí, 20 por ciento no (base de dev, da igual).

9. El caso especial de memory-as-a-service

Si usas una solución de memoria alojada (por ejemplo a través de un proveedor de MCP en la nube), el comportamiento del backup es distinto. Comprueba tres cosas.

Si el proveedor hace snapshots automáticos, y con qué frecuencia. En muchos es cada 6 o cada 24 horas, lo que puede ser poco frente a un bug de esquema.

Si hay una API de exportación. No quieres depender. Comprueba si hay una ruta /export que te dé tus datos como JSON o SQL.

Qué pasa si el proveedor quiebra. Suena paranoico, pero con proveedores MCP pequeños es real. Saca una exportación al menos una vez por semana y guárdala en local.

10. Simulacro de restauración una vez por trimestre

Último paso, a largo plazo. Una vez por trimestre coges tu backup más reciente, lo restauras en una base de prueba, apuntas Claude Code hacia ella con una configuración de prueba, y miras si lee la memoria. No es divertido, pero si dura un tercio de hora y lo haces una vez por trimestre, quedas inmune a los clásicos.

Qué quieres probar ahí. Si la restauración pasa. Si Claude ve las observations y las decisions. Si los recalls entre agentes siguen funcionando (permisos, índices). Si funciona una búsqueda sobre un tag antiguo.

Si algo de eso falla, lo sabes ahora y no en plena emergencia.

Si después quieres mantener la memoria limpia a largo plazo, échale un ojo a Reparar memory drift y Memoria portable. El backup es la capa de emergencia, la higiene y la portabilidad son el trabajo diario.