Cómo crear agentes de IA que no olvidan (usando archivos de memoria)

La mayoría de los agentes de IA no fallan porque el modelo sea malo.

Fracasan porque se despiertan con amnesia en cada sesión.

Le dices a Claude: "usamos pnpm, no npm".

Siguiente sesión: vuelve a intentar npm.

Le dices: "aquí no hay exportaciones por defecto".

Siguiente sesión: escribe una exportación por defecto.

Cada corrección que haces se desvanece en cuanto termina la sesión.

Hay una solución de un solo archivo para esto.

Me tomó tres meses de repetirme a mí mismo encontrarla.

Esto es todo lo que aprendí.

Por qué fracasan la mayoría de los agentes de IA

No es el modelo.

Es la capa que falta debajo del modelo.

→ Escribes un prompt

→ El agente realiza la tarea

→ La sesión termina

→ El recuerdo se pierde

→ Siguiente sesión: los mismos errores

→ Repites las mismas instrucciones

→ Para siempre

Este bucle es la mayor fuente de tiempo perdido en la programación con IA.

No es código malo. No son alucinaciones.

Es la repetición.

La capa que falta: la memoria

Todos se obsesionan con qué modelo es el más inteligente.

Capa equivocada.

La verdadera mejora no es un modelo más inteligente.

Es darle al modelo un lugar donde almacenar lo que aprende.

→ Prompts → le dice al agente qué hacer ahora mismo

→ Agentes → ejecutan la tarea

→ Memoria → persiste el contexto entre sesiones

→ Contexto persistente → no más correcciones repetidas

→ Sistema de aprendizaje → el agente realmente mejora con el tiempo

Esta es la diferencia entre una herramienta y un compañero de equipo.

Una herramienta hace lo que dices, cada vez, desde cero.

Un compañero de equipo recuerda lo de ayer.

Los 5 archivos de memoria que todo agente de IA necesita

Una vez que aceptas que la memoria es la capa que falta, la siguiente pregunta es: ¿dónde reside?

Cinco archivos. Cada uno con un trabajo diferente.

→ CLAUDE.md — el documento informativo personal de Claude

→ AGENTS.md — el estándar universal, leído por todas las herramientas principales

→ CLAUDE.local.md — tus preferencias personales, nunca se sube a git

→ MEMORY.md — notas que la IA escribe sobre sí misma, automáticamente

→ README.md — para humanos, no para agentes

Veamos cada uno.

CLAUDE.md — el que lo empezó todo

Coloca esto en la raíz de tu proyecto.

Claude lo lee al inicio de cada sesión.

Piénsalo como un documento informativo para un nuevo miembro del equipo con amnesia.

Un buen CLAUDE.md tiene cuatro secciones:

→ Contexto del proyecto — una línea. "Aplicación de comercio electrónico Next.js con Stripe y Postgres."

→ Estilo de código — no "formatear el código correctamente" sino "usar módulos ES, exportaciones nombradas, sangría de 2 espacios."

→ Comandos — cadenas exactas. pnpm test:integration, no "ejecutar las pruebas."

→ Arquitectura — "Las rutas de la API van en /src/api/[resource]/route.ts. Patrón repositorio para acceso a BD."

1# CLAUDE.md
2
3## Contexto del Proyecto
4Aplicación de comercio electrónico Next.js 14. Integración Postgres + Stripe.
5
6## Estilo de Código
7- Solo módulos ES
8- Exportaciones nombradas, nunca exportaciones por defecto
9- Sangría de 2 espacios
10- Modo estricto de TypeScript
11
12## Comandos
13- Instalar: pnpm install
14- Desarrollo: pnpm dev
15- Pruebas: pnpm test:integration
16- Linting: pnpm lint:fix
17
18## Arquitectura
19- Rutas de API: /src/api/[resource]/route.ts
20- Acceso a BD: solo patrón repositorio
21- Componentes: /src/components, un archivo por componente

Objetivo: menos de 300 líneas.

Cada línea compite por la atención con el trabajo real.

Ejecuta /init y Claude genera un archivo de inicio automáticamente.

Luego borra la mayor parte.

El archivo por defecto incluye cosas que Claude ya sabe de tu package.json. Conserva solo lo que Claude haría mal sin el archivo.

El sistema @imports — mantenlo ligero

CLAUDE.md no necesita contenerlo todo.

Puede importar otros archivos:

Ver

@README .md para la visión general del proyecto Ver

@docs/api-patterns .md para las convenciones de la API Ver

@package .json para los scripts npm disponibles

Las importaciones pueden ser recursivas — hasta 5 niveles de profundidad.

Esto resuelve el problema del "archivo gigante único".

Para equipos: el equipo de frontend es dueño de docs/frontend-rules.md.

Seguridad es dueño de docs/security.md.

CLAUDE.md simplemente los importa a todos.

Un archivo raíz. Muchas fuentes especializadas.

AGENTS.md — el estándar universal

CLAUDE.md solo funciona para Claude.

Si tu equipo también usa Cursor, Copilot o Gemini CLI — nunca lo leen.

AGENTS.md soluciona esto.

Un archivo. Todos los agentes principales lo leen.

Compatible con Claude Code, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Aider, Zed, Warp y más.

Es markdown estándar. Sin esquema especial. No se requiere YAML.

1# AGENTS.md
2
3## Visión General del Proyecto
4Plataforma de comercio electrónico construida con Next.js 14, Postgres y Stripe.
5
6## Compilación y Pruebas
7- Instalar: pnpm install
8- Desarrollo: pnpm dev
9- Pruebas: pnpm test
10- Linting: pnpm lint:fix
11
12## Estándares de Código
13- Modo estricto de TypeScript
14- Exportaciones nombradas sobre exportaciones por defecto
15- Las rutas de la API siguen las convenciones REST en /src/api/
16
17## Requisitos de Pruebas
18- Todos los PRs deben incluir pruebas
19- vitest para pruebas unitarias, playwright para pruebas e2e

Piénsalo como un README para agentes de IA.

README.md es para humanos. AGENTS.md es para cada agente, independientemente del proveedor. CLAUDE.md añade extras específicos de Claude por encima.

Son complementarios. No compiten.

Auto-memoria — la IA que toma sus propias notas

Esta es la capa más nueva e interesante.

Claude Code ahora escribe sus propios archivos de memoria durante tus sesiones.

memory/ ├── MEMORY.md ← índice, se carga en cada sesión ├── debugging.md ← notas sobre patrones de depuración ├── api-conventions.md ← decisiones de diseño de API └── ...

El cambio clave:

Tú escribes CLAUDE.md. Tú proporcionas las instrucciones.

Claude escribe MEMORY.md. Captura lo que ha aprendido.

→ El humano escribe las reglas

→ El agente descubre patrones mientras trabaja

→ El agente escribe su propia memoria

→ Las sesiones futuras empiezan siendo más inteligentes

Puedes activar esto directamente. Al final de una sesión productiva, solo di:

"Actualiza tus archivos de memoria con lo que aprendiste hoy sobre nuestro código."

Los aprendizajes persisten. No más tener que reexplicar tu envoltorio ORM personalizado por quinta vez.

Ejecuta /memory en cualquier momento para revisar o editar lo que Claude ha guardado.

El flujo de trabajo /init y luego borrar

La forma más rápida de iniciar un archivo de memoria en un proyecto nuevo:

1. Ejecuta /init en el directorio de tu proyecto
2. Claude genera un CLAUDE.md inicial basado en tu código
3. Borra lo que no necesitas

El paso 3 es donde la mayoría se equivoca.

El archivo generado es un borrador, no un producto terminado.

A menudo incluye relleno. "Este proyecto usa JavaScript." Gracias — se ve en package.json.

Editar a partir de un borrador razonable es mejor que escribir desde un archivo en blanco.

Después de la configuración, construye de forma orgánica.

Cuando Claude haga una suposición incorrecta — por ejemplo, si sigue importando un paquete obsoleto — no lo corrijas solo una vez.

Dile: "añade a mi CLAUDE.md: importar siempre desde @company/utils-v2, no desde @company/utils."

La instrucción persiste para todas las sesiones futuras.

Cada pocas semanas, pídele a Claude que revise y limpie CLAUDE.md.

Las instrucciones se acumulan. Algunas se vuelven redundantes. Otras empiezan a contradecirse. Una pasada rápida lo mantiene afilado.

Mi configuración real

Después de probar todo esto en varios proyectos de producción, esto es lo que se ha mantenido:

→ AGENTS.md en la raíz del proyecto — instrucciones compartidas que cualquier herramienta de IA lee. Comandos de compilación, estándares de código, requisitos de pruebas.

→ CLAUDE.md con @imports para el comportamiento específico de Claude. Se mantiene por debajo de 100 líneas, principalmente señalando archivos en docs/.

→ CLAUDE.local.md para peculiaridades personales — mis datos de prueba, URLs de sandbox, comandos de acceso directo. Nunca se sube a git.

→ Auto-memoria activada. Claude toma sus propias notas. Las reviso mensualmente.

→ Todo lo demás reemplazado con enlaces simbólicos que apuntan de vuelta a AGENTS.md. Una única fuente de verdad.

1# Configuración de enlaces simbólicos para consistencia entre herramientas
2ln -sfn AGENTS.md .github/copilot-instructions.md
3mkdir -p .cursor/rules && ln -sfn ../../AGENTS.md .cursor/rules/main.mdc

No es elegante.

Pero elimina la deriva de instrucciones en todas las herramientas del equipo.

El cambio más grande

La mayoría de los desarrolladores piensan:

Mejor modelo = mejor agente.

Equivocado.

La fórmula real:

Modelo + Memoria + Recuperación + Retroalimentación = Agente Útil

Un modelo más inteligente sin memoria seguirá olvidando tu comando de prueba mañana.

Un modelo modesto con gran memoria se vuelve más agudo cada semana.

La memoria es la variable que se acumula.

La inteligencia del modelo no lo es.

La mejora más grande que hice en mi flujo de trabajo con IA no fue cambiar de modelo.

Fue darle al modelo una memoria.

La diferencia entre:

"Claude, usamos pnpm" — cada sesión

y:

"Claude ya lo sabe" — cada sesión

Es la diferencia entre una herramienta y un compañero de equipo.

Si te fue útil:

→ Vuelve a publicar para compartirlo con todos los desarrolladores que todavía se repiten a sí mismos con Claude

→ Sigue a @sairahul1 para más sistemas que se acumulan mientras duermes

→ Marca esto como favorito — configúralo esta noche, deja de corregir mañana

Escribo sobre IA, creación de productos y sistemas que funcionan sin ti.