Memory Bank: Cómo los Archivos .md Son la Memoria Persistente del Vibecoding

Si llevas tiempo haciendo vibecoding, probablemente has experimentado ese momento frustrante: estás en medio de una tarea compleja, el LLM parece entender perfectamente tu proyecto, y de repente... empieza a olvidar cosas. Peor aún, deja de responder en el formato correcto o ignora instrucciones que le diste hace apenas unos minutos. Bienvenido al infierno del context window.

El Problema Catastrófico del Context Window

Imagina que tu cerebro tiene una pizarra de tamaño fijo donde solo puedes escribir cierta cantidad de información. Todo lo que sabes, lo que te acaban de decir, y lo que necesitas recordar para responder debe caber en esa pizarra. Cuando se llena, tienes que empezar a borrar cosas para escribir nuevas. Eso es exactamente el context window de un LLM.

El context window es la cantidad máxima de tokens (palabras, símbolos, código) que un modelo puede procesar simultáneamente. Dependiendo del modelo, esto varía desde 32,000 tokens hasta más de 200,000. Suena como mucho, pero en vibecoding se consume brutalmente rápido: cada archivo que lee el agente, cada comando que ejecuta, cada respuesta que genera, todo suma tokens.

Mi Experiencia con Modelos Locales

Esto me pasó de forma particularmente dolorosa experimentando con modelos locales en Cline. El context window se fue llenando hasta un punto donde el modelo ya ni siquiera leía el system prompt que Cline le envía. ¿El resultado? El LLM dejó de responder en el formato JSON específico que Cline espera para procesar sus acciones. El backend de Cline simplemente no podía interpretar las respuestas, y toda la sesión colapsó.

No es que el modelo sea malo. Es que literalmente no tenía espacio para leer las instrucciones básicas de cómo debe comportarse. Es como pedirle a alguien que siga un manual cuando ya no tiene espacio mental para recordar ni la primera página.

El Problema se Multiplica con Múltiples Modelos

¿Recuerdas el post donde hablé de mi stack económico para vibecoding? Ahí explico cómo uso DeepSeek para planificación y Claude Haiku para ejecución. La pregunta obvia es: si son modelos de diferentes proveedores, ¿cómo mantienen el hilo de la conversación?

Lo que hace Cline es enviar el historial completo del chat con DeepSeek a Claude, para que este último sepa en qué punto estamos. Funciona bien... dentro de la misma sesión. Pero ¿qué pasa cuando cambias de chat? ¿Cuando cierras VSCode? ¿Cuando el context window se desborda y tienes que empezar de nuevo?

Pierdes todo. El contexto desaparece como si nunca hubiera existido.

La Solución: Archivos .md como Memoria Persistente

La respuesta a este problema no está en esperar modelos con context windows más grandes (aunque ayuda). Está en crear un sistema de memoria externa que cualquier LLM pueda leer y entender instantáneamente: archivos Markdown estructurados.

El concepto es simple pero poderoso: al final de cada tarea significativa, le pides al agente que genere un archivo .md documentando el estado actual del proyecto, qué se logró, qué sigue, y qué contexto necesitaría otro agente para continuar el trabajo. Este archivo se convierte en la memoria persistente de tu proyecto.

Por Qué Markdown

Markdown es el formato ideal por varias razones: es legible tanto para humanos como para LLMs, consume pocos tokens comparado con otros formatos, tiene estructura semántica clara con headers y listas, es universal y no requiere herramientas especiales para leerlo, y se integra naturalmente en repositorios de código.

El Sistema Memory Bank de Cline

La comunidad de Cline formalizó este concepto con lo que llaman Memory Bank: un conjunto estructurado de archivos Markdown que actúan como la memoria persistente del agente. El sistema funciona con una jerarquía clara de documentos que se construyen unos sobre otros.

Estructura de Archivos Recomendada

El Memory Bank consiste en archivos core que todo proyecto debería tener:

memory-bank/
├── projectbrief.md      # Fundación: requisitos y objetivos core
├── productContext.md    # Por qué existe el proyecto, qué problemas resuelve
├── activeContext.md     # Estado actual: en qué estamos trabajando ahora
├── systemPatterns.md    # Arquitectura y decisiones técnicas
├── techContext.md       # Stack tecnológico, dependencias, constraints
└── progress.md          # Qué funciona, qué falta, issues conocidos

La clave está en la jerarquía: projectbrief.md es la fuente de verdad que informa todos los demás archivos. productContext.md, systemPatterns.md y techContext.md derivan de él. activeContext.md se alimenta de los tres anteriores. Y progress.md trackea el estado basándose en activeContext.md.

El Flujo de Trabajo

Cuando empiezas una sesión de trabajo, le indicas al agente que lea los archivos del Memory Bank. Esto le permite reconstruir su comprensión del proyecto instantáneamente, como si nunca hubiera perdido la memoria. El agente verifica si los archivos están completos, desarrolla una estrategia basada en el contexto, y presenta su enfoque antes de ejecutar.

Durante el trabajo, el agente actualiza estos archivos cuando descubre nuevos patrones en el proyecto, implementa cambios significativos, necesita clarificar el contexto, o tú le pides explícitamente que actualice el memory bank.

La Técnica del Handoff entre Agentes

Aquí viene lo que realmente cambia el juego: usar estos archivos .md como protocolo de transferencia entre diferentes agentes o sesiones. La idea es que cada vez que terminas una tarea significativa, le pides al agente que genere un documento específicamente diseñado para que otro agente pueda continuar el trabajo.

El Prompt Mágico

Al finalizar una tarea, usa algo como esto:

Genera un archivo .md que documente:
1. Estado actual del proyecto y lo que se acaba de completar
2. Decisiones técnicas tomadas y por qué
3. Próximos pasos sugeridos con prioridades
4. Contexto crítico que otro agente necesitaría para continuar
5. Referencias a archivos importantes y sus roles

Este documento debe permitir que otro agente (o tú mismo
en otra sesión) continúe el trabajo sin perder contexto.

Y aquí viene el chiste: gracias a que los LLMs aún no tienen sentimientos, no se ponen celosos cuando les dices que otro va a continuar su trabajo. A diferencia de algunos colegas humanos, el agente documentará todo con gusto sabiendo que no será él quien reciba el crédito de terminar la tarea.

Ejemplo Práctico de Handoff

Supongamos que terminaste de implementar la autenticación de usuarios. El archivo de handoff podría verse así:

# Handoff: Sistema de Autenticación - 2025-11-19

## Completado
- Implementación de JWT con refresh tokens
- Endpoints: /auth/login, /auth/register, /auth/refresh
- Middleware de validación en rutas protegidas
- Tests unitarios para AuthService (85% coverage)

## Decisiones Técnicas
- Se usó bcrypt con salt rounds=12 por balance seguridad/performance
- Refresh tokens en Redis con TTL de 7 días
- Access tokens expiran en 15 minutos (configurable en .env)

## Próximos Pasos
1. [ ] Implementar logout (invalidar refresh token en Redis)
2. [ ] Agregar rate limiting a /auth/login
3. [ ] Tests de integración con Supertest
4. [ ] Documentar endpoints en Swagger

## Archivos Clave
- src/auth/auth.service.ts - Lógica principal
- src/auth/strategies/jwt.strategy.ts - Validación de tokens
- src/config/redis.config.ts - Configuración de Redis

## Contexto Importante
- El proyecto usa NestJS con TypeScript estricto
- Todas las respuestas siguen el formato { data, error, meta }
- Los tests usan Jest con base de datos de prueba en Docker

Con este documento, cualquier agente (o tú mismo después de un café) puede entender exactamente dónde estamos y qué sigue, sin necesidad de reexplicar todo el proyecto.

AGENTS.md: El Estándar Emergente

Este concepto de usar Markdown como instrucciones para agentes está evolucionando hacia un estándar de la industria. AGENTS.md es un formato simple y abierto que funciona como un README pero específicamente para agentes de IA.

La idea es tener un archivo AGENTS.md en la raíz de tu repositorio que contenga todas las instrucciones que un agente necesita para trabajar efectivamente: pasos de build, convenciones de código, patrones de arquitectura, comandos de test, y cualquier cosa que normalmente le explicarías a un nuevo miembro del equipo.

Diferencia con README

Los README están escritos para humanos: quick starts, descripciones generales, guías de contribución. AGENTS.md complementa esto con el contexto detallado que los agentes necesitan: comandos exactos paso a paso, patrones específicos a seguir o evitar, archivos de ejemplo para cada tipo de componente, y configuraciones de entorno.

Por ejemplo, mientras tu README dice "ejecuta los tests", tu AGENTS.md dice exactamente cómo: el comando específico, qué variables de entorno necesita, qué base de datos de prueba usar, y cómo interpretar los resultados.

Beneficios Más Allá del Context Window

Este sistema de memoria por archivos .md tiene beneficios que van más allá de resolver el problema del context window:

Primero, obtienes documentación automática. Como efecto secundario de mantener el Memory Bank, tu proyecto termina con documentación actualizada y útil. El mismo contenido que ayuda al agente a entender el proyecto ayuda a nuevos desarrolladores humanos.

Segundo, logras consistencia entre sesiones. Ya no importa si el context window se desborda, si cambias de modelo, o si vuelves al proyecto después de semanas. El estado del proyecto está persistido y accesible.

Tercero, facilitas la colaboración entre agentes. Puedes tener diferentes agentes especializados en diferentes tareas, todos trabajando sobre el mismo proyecto gracias a la documentación compartida. Un agente para arquitectura, otro para testing, otro para documentación.

Cuarto, creas una historia auditable del proyecto. Los archivos .md en tu repo son versionables con Git. Puedes ver la evolución del proyecto, las decisiones que se tomaron, y por qué.

Implementación Práctica

Si quieres implementar este sistema en tu flujo de vibecoding, aquí está cómo empezar:

Paso 1: Crear la Estructura Inicial

Crea la carpeta memory-bank en tu proyecto y genera el projectbrief.md inicial. Este archivo es la fuente de verdad, así que tómate el tiempo de escribirlo bien o pídele al agente que lo genere basándose en una descripción detallada de tu proyecto.

Paso 2: Establecer la Rutina de Actualización

Haz un hábito de pedirle al agente que actualice el Memory Bank en estos momentos: después de completar una feature significativa, antes de cerrar una sesión de trabajo, cuando el context window se acerque al 50% de uso, y al cambiar de modelo o iniciar un nuevo chat.

Paso 3: Usar el Comando de Update

Cuando pidas la actualización, sé específico:

Actualiza el memory bank con el trabajo completado hoy.
Enfócate especialmente en activeContext.md y progress.md.
Asegúrate de que otro agente pueda continuar mañana
sin contexto previo de esta sesión.

Paso 4: Comenzar Sesiones Correctamente

Al iniciar una nueva sesión, siempre empieza indicándole al agente que lea los archivos del Memory Bank antes de hacer cualquier otra cosa. Esto reconstruye el contexto instantáneamente.

Herramientas Complementarias

Varias herramientas están adoptando y expandiendo este concepto. Cline tiene su sistema Memory Bank integrado con custom instructions específicas que enseñan al agente cómo mantener la documentación. Gemini CLI soporta archivos GEMINI.md para contexto jerárquico por proyecto. GitHub Copilot usa copilot-instructions.md para instrucciones persistentes.

También existen herramientas como Basic Memory, un servidor MCP que construye un grafo semántico persistente en Markdown local, permitiendo que cualquier LLM compatible lea y escriba en tu base de conocimiento.

El Spec-Driven Development

Un enfoque interesante que lleva este concepto al extremo es el "spec-driven development": escribir toda la especificación de tu aplicación en Markdown y dejar que el agente la "compile" a código real. En lugar de editar código directamente, editas la especificación y el agente regenera el código.

Las ventajas son tentadoras: nunca pierdes contexto porque la spec es la fuente de verdad, puedes regenerar el código en otro lenguaje cambiando solo las instrucciones de compilación, y la documentación siempre está actualizada porque es el código.

Conclusión

El context window siempre será una limitación de los LLMs, pero no tiene que ser una limitación de tu productividad. Los archivos Markdown como sistema de memoria persistente son la solución elegante que transforma un problema técnico en una oportunidad para mejor documentación y flujos de trabajo más robustos.

Piénsalo así: cada vez que documentas para el próximo agente, estás documentando para tu yo del futuro que ya olvidó en qué estaba trabajando. Y a diferencia de los colegas humanos que a veces son celosos con su conocimiento, los LLMs documentan todo con gusto sabiendo que el crédito es tuyo.

El Memory Bank no es solo una técnica de optimización. Es un cambio de paradigma en cómo pensamos sobre el desarrollo asistido por IA: no como sesiones aisladas con un genio amnésico, sino como una colaboración continua con un asistente que siempre puede reconstruir su comprensión del proyecto en segundos.

Empieza simple: un projectbrief.md y un progress.md. Deja que el sistema evolucione con tu proyecto. Y recuerda: la memoria más confiable es la que está escrita.