Memoria del agente de IA entre sesiones: archivo de progreso, diario de decisiones, git y script de inicio

Por qué el agente no recuerda nada

El modelo no guarda estado entre ejecuciones. Todo lo que el agente «sabe» de su tarea está en la ventana de contexto de la sesión actual: los archivos leídos, la salida de los comandos, el diálogo con usted. Si la sesión se cierra o el contexto se desborda, la nueva empieza de cero y solo ve lo que está escrito en el disco.

Un modelo útil: un ingeniero brillante que cada mañana llega al trabajo con la memoria borrada por completo. Entiende el código rápidamente, pero no recuerda qué variante de arquitectura se eligió ayer, por qué se descartaron las demás ni en qué estado están las pruebas. Sin notas, pasará entre quince y veinte minutos explorando y, con bastante probabilidad, rehará algo que usted ya había descartado a conciencia.

Por eso la memoria del agente de IA no es una propiedad del modelo, sino una parte del harness: un conjunto de archivos y reglas que usted diseña. La buena noticia es que no hacen falta bases de datos vectoriales ni servicios especiales. Bastan unos cuantos archivos Markdown, git y disciplina.

Por qué una ventana de contexto grande no resuelve el problema

Parece que basta con esperar a un modelo con una ventana más grande. Pero una tarea compleja llena cualquier ventana: el agente lee la base de código, acumula el historial de decisiones, recibe salidas de pruebas muy verbosas y mantiene todo el diálogo. Las necesidades crecen al mismo ritmo que la ventana. Es un problema de arquitectura, no de tamaño.

Hay además un segundo efecto. Cerca del límite de la ventana, muchos modelos empiezan a tener prisa por terminar: se saltan verificaciones y eligen la solución simple en lugar de la correcta. Anthropic describe esta observación para sus modelos, aunque la intensidad del efecto varía de un modelo a otro. Una sesión larga al límite del contexto no solo corre el riesgo de perder información, sino también de empeorar la calidad del trabajo.

Compactación: qué se conserva y qué se pierde

La compactación es la reducción de la parte antigua del diálogo a un resumen breve, para liberar espacio en la misma sesión. En Claude Code lo hace el comando /compact, y la compactación también ocurre automáticamente al acercarse al límite. El comando /clear, en cambio, borra el historial y empieza la conversación de nuevo.

El problema de la compactación es que el resumen suele conservar el «qué» y perder el «por qué». El código terminado queda en los archivos, pero el razonamiento —por qué se eligió la opción B, por qué no se usó una biblioteca, por qué se omitió a conciencia una optimización— se reduce a un par de palabras o desaparece. El siguiente paso del agente «mejora» una decisión consciente, porque ya no ve las razones.

Una regla práctica sin métricas complicadas: cuando la tarea haya ocupado alrededor del 60% de la ventana, deje de escribir código y prepare el relevo. Si el contexto está ocupado en un 40% y el final de la tarea está cerca, basta con la compactación.

Cuatro artefactos que componen la memoria del agente

En lugar de confiar en la memoria del modelo, cree un diario de a bordo. Consta de cuatro partes, y cada una tiene su papel.

1. PROGRESS.md — dónde estamos ahora.
2. DECISIONS.md — por qué se hizo así y no de otra forma.
3. Commits de git — puntos de control del estado sin coste.
4. Protocolo de relevo en AGENTS.md — qué hacer al llegar y al salir.

PROGRESS.md: archivo de progreso

Responde a una sola pregunta: en qué estado está el proyecto ahora mismo. El agente lo lee primero al empezar la sesión y lo actualiza al final, antes de irse. El archivo es corto y se reescribe, no se amplía sin fin: la historia vive en git.

# PROGRESS.md

## Objetivo actual
Búsqueda en el catálogo de productos (funcionalidad search-01)

## Estado
- HEAD: 4f2a9c1
- make check: en verde, 142/142 pruebas
- Hecho: índice en PostgreSQL (tsvector), endpoint GET /search
- Verificado: pruebas unitarias + consulta manual con curl en 3 búsquedas

## Bloqueos
- No hay datos de morfología para el idioma kazajo: esperamos una decisión

## Siguiente paso
Añadir paginación a GET /search, criterio: prueba de la segunda página

Fíjese en los cuatro campos que bastan para el relevo: el hash del commit, la proporción de pruebas que pasan, los bloqueos y el siguiente paso. Si una sesión nueva no puede continuar el trabajo de forma inequívoca a partir de este archivo, a la plantilla le falta un campo.

DECISIONS.md: diario de decisiones

Guarda justamente el «por qué» que se pierde en la compactación. Formato de cada entrada: la decisión, el motivo, qué se descartó y por qué, y las restricciones.

## 2026-03-14 — Caché de ajustes de usuario en Redis
- Decisión: Redis, TTL de 5 minutos, invalidación activa al escribir.
- Motivo: se lee en cada petición y el volumen de datos es mínimo.
- Descartado: vista materializada en PostgreSQL — cambios demasiado frecuentes,
  el mantenimiento no compensa.
- Restricción: no cachear los ajustes de pago.

La línea más valiosa aquí es la de «Descartado». Es la que impide que la sesión siguiente «optimice» la decisión de vuelta hacia una opción que ya se consideró y se rechazó. El diario de decisiones, a diferencia del archivo de progreso, solo crece: las entradas antiguas no se borran, sino que se marcan como sustituidas por otras nuevas.

Historial de git como puntos de control

Los commits son instantáneas versionadas del estado que ya forman parte del trabajo. El agente puede leer git log y git diff y reconstruir qué ha cambiado. Para que el historial funcione como memoria, el mensaje del commit debe explicar la intención, no repetir el diff.

# mal
git commit -m "update search.py"

# bien
git commit -m "search: índice tsvector en lugar de LIKE

LIKE '%q%' no usa el índice; con 200k productos la consulta tarda 1.8 s.
La paginación aún no está hecha, ver PROGRESS.md."

Los commits pequeños y frecuentes tras cada ejecución verde de las pruebas proporcionan además un punto de retorno. Si la sesión se desvió, es más sencillo volver al último estado verificado que desenredar ediciones a medio terminar.

Protocolo de relevo en AGENTS.md

Los archivos de estado no sirven de nada si el agente no los conoce. Por eso en el archivo de instrucciones de entrada (AGENTS.md o CLAUDE.md) se escribe un protocolo breve: qué hacer al llegar y qué hacer al irse.

## Al llegar al turno
1. Leer PROGRESS.md y DECISIONS.md.
2. Encontrar la tarea activa en .agent/feature_list.json.
3. Ejecutar make check: comprobar que el repositorio está coherente.
4. Continuar desde el «Siguiente paso», sin reabrir lo ya resuelto.

## Al salir del turno
1. Ejecutar make check y hacer commit del estado en verde.
2. Actualizar PROGRESS.md: HEAD, pruebas, bloqueos, siguiente paso.
3. Añadir las nuevas decisiones a DECISIONS.md.
4. No dejar cambios a medias en el árbol de trabajo.

Conviene que el protocolo sea corto: son unas pocas líneas en el archivo de entrada, no un documento aparte.

Script de inicio: cómo acelerar el arranque de la sesión

Para que el agente no tenga que reconstruir el panorama a mano, déle un único script que compruebe el entorno e imprima el estado. El script debe ser idempotente —se puede ejecutar cuantas veces haga falta— y terminar con un mensaje explícito de que está listo.

#!/usr/bin/env bash
set -euo pipefail

echo "== 1. Entorno =="
command -v uv >/dev/null || { echo "FAIL: uv no está instalado"; exit 1; }
uv sync --frozen

echo "== 2. Repositorio =="
if [ -n "$(git status --porcelain)" ]; then
  echo "WARN: el árbol de trabajo tiene cambios sin commit"
else
  echo "OK: limpio"
fi
echo "HEAD: $(git log -1 --oneline)"

echo "== 3. Comprobación =="
make check

echo "== 4. Estado =="
cat PROGRESS.md

echo "Listo para trabajar"

En el protocolo de llegada basta entonces con una línea: «ejecuta scripts/init.sh». En Claude Code este arranque se puede automatizar con un hook al inicio de la sesión (evento SessionStart), aunque incluso sin hook el agente ejecutará el script siguiendo la instrucción del archivo.

Qué guardar en la memoria del agente y qué no

El error principal es convertir la memoria en un cajón de sastre. Cada línea que el agente lee al empezar ocupa sitio en el contexto, y lo superfluo diluye lo importante.

Separe también por tiempo de vida. Las reglas del proyecto cambian poco y afectan a todas las tareas: su lugar está en el archivo de instrucciones de entrada. El estado cambia en cada sesión: su lugar está en el archivo de progreso. Si se mezclan, el archivo de entrada crece deprisa con notas obsoletas.

Primera sesión: la inicialización como fase aparte

La memoria entre sesiones no ayuda si la primera sesión acabó en caos. La imagen típica: en un repositorio vacío escribe «añade búsqueda» y, media hora después, resulta que el framework de pruebas está mal configurado y el formato de las migraciones no es el adecuado. La búsqueda aparece, pero los cimientos están torcidos.

La causa es que la implementación y la inicialización optimizan cosas distintas: la primera, el número de funcionalidades terminadas en esta sesión; la segunda, la velocidad y la fiabilidad de todas las sesiones siguientes. El agente tiende a lo resultado visible, es decir, al código. Por eso conviene separar la inicialización en una sesión propia con un criterio de terminado de cuatro condiciones.

• Arrancar: make setup y make dev funcionan desde un clon limpio.
• Comprobarse: existe make test y al menos una prueba real que pasa.
• Ver el progreso: existe el archivo de estado y se puede leer.
• Retomar el trabajo: hay una lista de tareas con criterios de aceptación.

Si inicia proyectos nuevos con frecuencia, cree una plantilla de repositorio: Makefile, framework de pruebas, esqueleto de AGENTS.md, carpeta .agent/, scripts/init.sh, linter y CI. Así la inicialización se reducirá a la particularidad de cada proyecto.

Cómo comprobar que la memoria funciona

La métrica más honesta es el tiempo desde el inicio de una sesión nueva hasta el primer cambio de código con sentido. Sin artefactos suele ser de quince a veinte minutos de exploración; con un buen relevo, de dos a tres. Mídalo una vez antes y otra después, y verá si la disciplina compensa.

Una segunda forma es la prueba de arranque en frío. Abra una sesión nueva, escriba «continúa» y haga cinco preguntas: cuál es el objetivo actual, en qué estado están las pruebas, qué decisión se tomó sobre el tema clave y por qué, qué bloquea, cuál es el siguiente paso. Si el agente responde a las cinco basándose en los archivos y sin suposiciones, la memoria está bien diseñada. Cada respuesta insegura señala un campo que falta en la plantilla.

Errores habituales

• El archivo de progreso solo crece. Al cabo de un mes tiene cientos de líneas de historia. Reescríbalo para el estado actual; la historia está en git.
• Falta la línea «descartado». Un diario de decisiones sin alternativas rechazadas no protege de las discusiones repetidas.
• El agente actualiza el estado «a ojo». Escriba cómo se comprobó: el comando y el resultado, no «todo funciona».
• Relevo al límite de la ventana. Cerca del borde del contexto el agente ya tiene prisa; empiece el handoff antes, alrededor del 60%.
• Árbol de trabajo sucio al salir. Los cambios a medio hacer sin commit confunden a la sesión siguiente.

En resumen

La memoria del agente de IA entre sesiones se construye sobre archivos, no sobre el modelo: PROGRESS.md guarda el estado actual, DECISIONS.md, las razones y las alternativas descartadas; los commits de git son puntos de control con la intención explicada, y el protocolo de relevo en AGENTS.md obliga a leer y actualizar todo esto. El script de inicio reduce el arranque a un solo comando, y la prueba de arranque en frío muestra si los registros son suficientes. El diario de a bordo del agente y el contrato de arranque se analizan en la práctica en el curso de harness engineering.