Tutorial: memoria procedural — que tu agente despierte sabiendo cómo trabajas

Una caja restaurada de un snapshot revive sin boot. No vuelve a correr systemd, ni el entrypoint, ni .bashrc: eso pasó cuando se horneó la imagen. Una caja que durmió tres días despierta con el mundo de hace tres días y nada lo señala.

Aquí montas lo contrario en cuatro pasos: las convenciones de tu proyecto viven en el repo y se recargan solas en cada despertar. Necesitas una cuenta de Easybits con una API key y un repo de git.

Dos reglas que te ahorran rehacer esto en un mes:

• La procedural va en el repo (AGENTS.md, skills), no en el disco de la caja: versionada y con una sola verdad. En /data solo lo que es de esa caja — cachés, trabajo a medias. Tres cajas del mismo agente son tres /data aislados.
• No la escondas detrás de una tool. Una tool se llama bajo demanda y el agente puede no llamarla. "Aquí las cotizaciones llevan IVA desglosado" tiene que estar delante de sus ojos desde el primer token, no a una decisión de distancia.

Paso 0: el token, con el alcance mínimo

Un fine-grained PAT de GitHub limitado a un repo: si se filtra, no abre el resto de tu cuenta. Settings → Developer settings → Personal access tokens → Fine-grained tokens → Generate new token, y tres campos:

• Repository access: Only select repositories → tu repo. No "All".
• Permissions → Repository → Contents: Read and write. Ese solo permiso basta para clone, pull y push. Si el agente solo lee, déjalo en Read-only.
• Expiration: ponle fecha. 90 días; rotarlo es un secret_set más.

Sale una sola vez (github_pat_...). Cárgalo al vault por la UI (/dash/developer/secrets) o pidiéndoselo a un agente con la tool secret_set — la misma operación por las dos puertas. El nombre va en MAYUSCULAS_CON_GUION_BAJO, que es como lo referencias luego: $secret:GITHUB_TOKEN. El valor no se devuelve nunca; secret_list solo enseña nombre y último uso.

Paso 1: la memoria entra por git

Todo lo que sigue es un archivo memoria.mjs que puedes correr tal cual:

El $secret: resuelve contra tu vault en el servidor. El token viaja a la caja solo para esa operación y desaparece: no queda en .git/config, no aparece en un ps. Puedes comprobarlo tú mismo, y vale la pena hacerlo una vez:

Paso 2: declara el bootstrap

Es el script que el host corre cada vez que la caja despierta, antes de que el agente reciba su primer mensaje:

Por REST es lo mismo:

Cuatro cosas que conviene saber:

• Hazlo idempotente. Corre en cada despertar: checkout -B, no -b; ln -sfn, no ln -s. Un script que falla la segunda vez es peor que ninguno.
• async (default) no frena el primer mensaje; blocking espera hasta timeoutSeconds antes de servir. Un sleep 25 en async cuesta 1s al que escribe; en blocking, los 25.
• Un bootstrap roto nunca deja la caja inalcanzable. El resultado queda anotado en eb_boot_exit y eb_boot_err, legibles desde fuera.
• Nunca metas una credencial en el script. La receta viaja en el metadata de la caja y aparece en los listados.

Variables disponibles: EB_RESUME=1 y EB_SANDBOX_ID. El cwd es /data/work.

Paso 3: dónde encaja lo que sí necesita credencial

Esta frontera es el detalle que más se malinterpreta, así que conviene tenerla clara:

El bootstrap hace el trabajo local — ramas, enlaces, convenciones. No lleva secretos, así que no puede hacer fetch de un repo privado. Tu caja despierta con las convenciones aplicadas pero con el código del último pull.

Lo que necesita credencial pasa por la tool:

En la práctica: pon "empieza haciendo pull" como primera línea de tu AGENTS.md. Como el bootstrap lo enlaza en cada despertar, el agente lo lee siempre y lo hace él mismo. La memoria procedural se encarga de mantener al día la semántica.

Paso 4: verifica que funciona

La prueba que importa no es reanudar a mano, sino despertar la caja con tráfico normal — que es como despierta de verdad:

Cinco despertares, una sola rama: el bootstrap corre siempre y es idempotente de verdad. Si algo falló, el motivo está en el metadata de la caja (eb_boot_exit, eb_boot_err).

Y el trabajo, de vuelta

¿Quién corre eso? Nadie automáticamente — y conviene tenerlo claro porque no hay hook de apagado. El push lo dispara una de dos cosas:

• El propio agente, durante su turno, si tiene las tools montadas. Pones "cuando termines una tarea, haz commit y push" en tu AGENTS.md y lo hace como usaría cualquier otra herramienta. Es la opción coherente con todo lo anterior: el bootstrap enlaza el AGENTS.md en cada despertar, así que la instrucción está siempre delante de sus ojos.
• Tu orquestador, desde tu código, cuando el agente termina de responder.

Y la consecuencia que hay que decir en voz alta: si la caja se destruye sin que nadie haya empujado, ese trabajo se pierde. Dormir no lo pierde — /data sobrevive al sueño. Destruir la caja, sí. Por eso el push no es el final decorativo del ciclo: es el único momento en que el trabajo deja de depender de que la caja siga viva.

Hecho eso, cada sesión deja su rama y la revisas como revisarías la de un compañero.

Lo que queda montado es sencillo de describir: el repo guarda cómo se trabaja, el bootstrap lo reactiva en cada despertar, /data guarda lo de esa caja, y lo que necesita llave pasa por una tool que la usa y la tira. Un agente que duerme meses y despierta al día.