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

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

Fracasan porque despiertan con amnesia cada sesión.

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

Siguiente sesión: vuelve a intentar npm.

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

Siguiente sesión: escribe un export 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 para 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 hace la tarea

→ La sesión termina

→ La memoria se pierde

→ Siguiente sesión: los mismos errores

→ Repites las mismas instrucciones

→ Para siempre

Este ciclo es la fuente más grande de tiempo perdido en programación con IA.

No código malo. No alucinaciones.

Repetición.

La capa que falta: la memoria

Todos se obsesionan con qué modelo es 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

→ 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 vive?

Cinco archivos. Cada uno con un rol 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

Repasemos cada uno.

CLAUDE.md — el que empezó todo

Ponlo 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. "App de comercio electrónico con Next.js, Stripe y Postgres."

→ Estilo de código — no "dar formato correcto al código" sino "usar módulos ES, exports con nombre, indentación de 2 espacios."

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

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

1# CLAUDE.md
2
3## Contexto del proyecto
4App de comercio electrónico con Next.js 14. Integración Postgres + Stripe.
5
6## Estilo de código
7- Solo módulos ES
8- Exports con nombre, nunca exports por defecto
9- Indentación de 2 espacios
10- TypeScript modo estricto
11
12## Comandos
13- Instalar: pnpm install
14- Dev: pnpm dev
15- Pruebas: pnpm test:integration
16- Linter: pnpm lint:fix
17
18## Arquitectura
19- Rutas API: /src/api/[recurso]/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 atención con el trabajo real.

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

Luego borra la mayor parte.

El archivo por defecto incluye cosas que Claude ya sabe desde tu package.json. Conserva solo lo que Claude podría hacer 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 convenciones de 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 solo los importa a todos.

Un archivo raíz. Múltiples 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. Sin YAML requerido.

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- Dev: pnpm dev
9- Pruebas: pnpm test
10- Linter: pnpm lint:fix
11
12## Estándares de código
13- TypeScript modo estricto
14- Exports con nombre en lugar de exports por defecto
15- Las rutas API siguen convenciones REST en /src/api/
16
17## Requisitos de pruebas
18- Todos los PRs deben incluir pruebas
19- vitest para pruebas unitarias, playwright para e2e

Piénsalo como un README para agentes de IA.

README.md es para humanos. AGENTS.md es para todo agente, sin importar el proveedor. CLAUDE.md añade extras específicos de Claude 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 aprendió.

→ El humano escribe reglas

→ El agente descubre patrones mientras trabaja

→ El agente escribe su propia memoria

→ Las sesiones futuras comienzan 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 nuestra base de código."

Los aprendizajes persisten. No más tener que reexplicar tu wrapper 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 base de código
3. Borra lo que no necesites

El paso 3 es donde la mayoría falla.

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

A menudo incluye contenido de relleno. "Este proyecto usa JavaScript." Gracias — se ve desde 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, que siga importando un paquete obsoleto— no lo corrijas una sola vez.

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

La instrucción persiste para cada sesión futura.

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 revisión 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 quedó:

→ 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 comportamiento específico de Claude. Se mantiene por debajo de 100 líneas, principalmente apuntando a archivos docs/.

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

→ Auto-memoria activada. Claude toma sus propias notas. Yo 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.

Incorrecto.

La fórmula real:

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

Un modelo más inteligente sin memoria aún olvida tu comando de pruebas mañana.

Un modelo modesto con buena 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 memoria al modelo.

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 esto fue útil:

→ Compártelo para que llegue a todos los desarrolladores que aún se repiten frente a Claude

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

→ Guarda esto — configúralo esta noche, deja de corregir mañana

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