Subtítulo: El patrón de memoria en archivos que un humano puede leer, por qué le gana a lo sofisticado en muchos casos, las convenciones que lo hacen funcionar, y por qué es el mismo objeto que un runbook o un ADR.
Nota de alcance. Ejemplos ilustrativos. El patrón se ve hoy en agentes de código de uso corriente; los nombres de archivos y los formatos son convención, no estándar. Adaptá las convenciones a tu equipo y revalidá.
Resumen ejecutivo
- La forma de memoria que usan hoy los agentes de código no es un vector store ni un grafo: es un puñado de archivos de texto que un humano puede abrir y leer —notas del proyecto, un TODO que persiste, decisiones registradas—.
- Le gana a la solución sofisticada no por ser más potente, sino por ser inspeccionable: versionable con git, auditable de un vistazo, editable a mano y testeable con las herramientas de texto de siempre.
- Funciona por sus convenciones, no por magia: un hecho por sección, un índice liviano que apunta al resto, fechas absolutas y expiración explícita. Sin esas reglas, el archivo se pudre.
- La memoria en archivos exige curaduría: sin poda crece hasta contaminar el contexto que debía ayudar. Mantenerla es parte del trabajo, no un extra opcional.
- Es el mismo objeto que un runbook o un ADR: conocimiento operativo en texto plano versionado. Y se testea igual: el agente relee lo que escribió, ¿reproduce la decisión correcta?
Al terminar vas a poder: reconocer cuándo un archivo de texto es mejor memoria que un sistema dedicado, aplicar las convenciones que evitan que se pudra, y testear la memoria releyéndola con el agente para ver si reproduce la decisión correcta.
1. El problema: la sesión termina y el agente empieza de cero
Un agente de código resuelve un problema difícil un martes. Descubre que cierta librería no sirve para el caso, que la configuración va en un lado poco obvio, que aquel test flaky fallaba por una condición de carrera. Trabajo real, aprendido a fuerza de intentos. El viernes, sesión nueva, ventana de contexto limpia: vuelve a probar la librería que no servía y vuelve a chocar contra la misma pared.
Todo lo que había aprendido se evaporó con la ventana. Y no por falta de un sistema de memoria elaborado: por falta del más simple de todos, escribirlo en un archivo. El conocimiento existió; nadie lo persistió donde la próxima sesión pudiera encontrarlo.
2. El patrón: memoria que un humano puede leer
La solución que adoptaron los agentes de código modernos es casi decepcionante de simple. En vez de una base vectorial, el agente mantiene archivos de texto en el propio repositorio:
- Notas de proyecto: qué es este repo, cómo se corre, dónde están las cosas, qué decisiones de arquitectura hay que respetar. (Memoria semántica.)
- Un TODO persistente: qué falta, qué se intentó, qué se descartó y por qué. (Memoria episódica, ya curada.)
- Decisiones registradas: por qué se eligió X sobre Y, con fecha. (Semántica con procedencia.)
El agente los lee al empezar y los actualiza al avanzar. No hay embeddings ni recuperación por similitud: hay un archivo que se lee entero o por secciones. Claude Skills (2025) lleva la misma idea al plano procedural —procedimientos empaquetados como archivos que el agente carga cuando la tarea los pide—.
En los términos de la taxonomía de memoria, los archivos cubren sobre todo la memoria semántica y la procedural —lo que es verdad y cómo se hace—, que son justamente las que peor entran en una ventana de conversación efímera.
3. Por qué le gana a la solución sofisticada
Cuatro propiedades, y cada una tiene su lectura desde QA:
- Versionable con git. Cada cambio de la memoria queda en el historial. Se ve qué agente (o qué persona) escribió un hecho, cuándo, y se revierte con un comando. Una memoria vectorial no tiene diff.
- Auditable. Para saber qué “sabe” el agente, abrís el archivo y lo leés. No hay que consultar un índice ni interpretar distancias coseno: lo que ves es exactamente lo que el agente va a leer.
- Editable por humanos. Si un hecho está mal, se corrige con un editor de texto. La memoria envenenada —un hecho falso que se auto-refuerza— se limpia con un commit, no con un reprocesamiento del índice.
- Testeable con herramientas de texto.
grep,diff, un linter, un test que verifica que el archivo tiene las secciones esperadas. La memoria es un artefacto de texto, y todo lo que ya sabés hacer con texto se aplica sin traducción.
La sofisticación de un vector store se paga en opacidad. Un archivo no es más inteligente: es más honesto.
4. Las convenciones que lo hacen funcionar
El patrón no funciona por magia, funciona por reglas. Un archivo de memoria sin convenciones es un cajón de sastre que en veinte sesiones se vuelve ilegible. Las que lo sostienen:
memoria/
├── INDICE.md ← liviano: qué hay y dónde (se lee siempre)
├── proyecto.md ← un hecho por sección, con fecha
├── decisiones.md ← "se eligió X sobre Y — 2026-07-15 — porque…"
└── TODO.md ← qué falta, qué se descartó y por qué- Un hecho por sección (o por archivo). Para recuperar, editar y expirar de forma quirúrgica, sin arrastrar lo de al lado. Un párrafo que mezcla cinco hechos no se puede podar.
- Un índice liviano. Un archivo raíz corto que apunta a los demás, para que el agente sepa qué existe sin cargar todo. El índice se lee siempre; el detalle, bajo demanda. Es la carga diferida de la que habla el pilar, aplicada a la memoria.
- Fechas absolutas. “2026-07-15”, nunca “la semana pasada”. Una memoria que se relee meses después no tiene forma de resolver “ayer”.
- Expiración explícita. Un hecho con fecha de revisión o una marca de “vigente hasta”. Sin expiración, la memoria acumula verdades vencidas que nadie se anima a borrar.
5. Curaduría: la memoria sin poda es contexto contaminado
Escribir en la memoria es la mitad fácil. Podarla es la otra mitad, la que se olvida. Una memoria que solo crece termina siendo un archivo enorme donde el hecho vigente convive con diez versiones viejas, y releerla entera vuelve a llenar el contexto de ruido: exactamente el problema que la memoria venía a resolver. Es la patología de distracción del pilar, mudada de la ventana al archivo.
La regla de mantenimiento es simple de decir y fácil de saltear: cada hecho nuevo obliga a preguntar si alguno viejo quedó obsoleto. La poda no es limpieza opcional de fin de sprint; es parte del ciclo, como cerrar un ticket cuando el trabajo terminó. Una memoria que nadie curó no es una memoria: es un basurero con fechas.
6. Por qué esto es Quality Engineering
El paralelo cierra la idea. Un archivo de memoria de un agente es el mismo objeto que un runbook —cómo se opera esto— o un ADR, architecture decision record —por qué se decidió esto, con fecha—. Conocimiento operativo en texto plano, versionado, que sobrevive a quien lo escribió. La disciplina de QA ya sabe mantener esos artefactos: son la misma materia que la documentación de pruebas, los postmortems y las decisiones de diseño que un equipo maduro deja por escrito en vez de en la cabeza de una persona.
Y por eso se testea igual que cualquier documento operativo: el agente relee lo que escribió y se verifica que reproduzca la decisión correcta. El test concreto: dado un archivo de memoria, se le plantea al agente la situación que ese archivo debería resolver —sin dársela masticada— y se verifica que llega a la conclusión que la memoria contiene. Si releyó “la librería X no sirve, usar Y” y vuelve a proponer X, la memoria existe pero no funciona: está escrita para un humano, no para quien de verdad la relee.
Los archivos son uno de los cinco mecanismos de la taxonomía de memoria, y el que mejor encarna la tesis del pilar: administrar el contexto como recurso finito, en Context engineering. La misma lógica de conocimiento en texto plano versionado —escribir para que otro, o vos en seis meses, lo relea y decida bien— es la del método editorial con evidencia.