«¿No habíamos decidido esto ayer?»
Estaba migrando mi email fuera de Google. Llevaba dos sesiones de Claude Code trabajando en ello: issues en Linear, decisiones tomadas, scripts ejecutados. Abro una tercera sesión y le pregunto «¿qué queda pendiente del degoogle?»
Silencio. Amnesia total.
Es como trabajar con un compañero brillante que cada mañana llega a la oficina sin recordar absolutamente nada de lo que hicisteis el día anterior. Ni las decisiones, ni los errores, ni los descubrimientos. Cada sesión es un lienzo en blanco.
Y resulta que hay un fichero que soluciona exactamente este problema. Lleva meses ahí. Y casi nadie lo conoce.
CLAUDE.md vs MEMORY.md: el manual y el cuaderno
Si usas Claude Code, probablemente ya conozcas CLAUDE.md. Es el fichero donde le dices a la IA cómo trabajar: qué idioma usar, qué herramientas tienes, tus convenciones de código.
CLAUDE.md es tu manual de instrucciones. Lo escribes tú. Lo mantienes tú.
MEMORY.md es otra cosa. Es un cuaderno de campo que la IA escribe sola. Apunta lo que aprende mientras trabaja contigo: errores que cometió, decisiones que tomasteis, patrones del proyecto, cosas que probó y no funcionaron.
Dicho en cristiano:
| CLAUDE.md | MEMORY.md | |
|---|---|---|
| Quién lo escribe | Tú | La IA |
| Qué contiene | Instrucciones | Aprendizajes |
| Cuándo cambia | Cuando tú quieres | Después de cada sesión |
| Analogía | El reglamento | El cuaderno de campo |
Si CLAUDE.md es el contrato que le das al becario el primer día, MEMORY.md son las notas que el becario va tomando en su libreta mientras trabaja.
Dónde vive
~/.claude/projects/<hash-del-directorio>/memory/MEMORY.md
Cada directorio de proyecto tiene su propio fichero de memoria. Si trabajas en ~/code/proyecto-a, tiene un MEMORY.md. Si abres Claude Code en ~/code/proyecto-b, tiene otro diferente. No se mezclan.
El fichero se carga automáticamente en el contexto al inicio de cada sesión. No tienes que hacer nada.
¿No hay un MEMORY.md global?
No. Solo por proyecto. Y esto es un problema.
Hoy creé un wrapper de op (el CLI de 1Password) que cachea secretos durante una hora. Es útil en todos mis proyectos, no solo en el que estaba trabajando. Pero MEMORY.md lo apuntó solo en la memoria de ese directorio.
CLAUDE.md sí tiene una versión global (~/.claude/CLAUDE.md), que se carga en todas las sesiones. MEMORY.md no tiene equivalente. Si la IA aprende algo que aplica a todo tu entorno (un alias, una peculiaridad de tu sistema, una preferencia), tiene que apuntarlo en cada proyecto por separado. O no lo apunta.
En la práctica, lo que hago es meter ese tipo de conocimiento transversal en mi CLAUDE.md global a mano. No es ideal, pero funciona.
Si borro el proyecto, ¿se borra la memoria?
No. La memoria vive en ~/.claude/projects/, no en tu directorio de código. Si borras ~/code/mi-proyecto/, el MEMORY.md sigue ahí, huérfano, ocupando espacio y sin que nadie lo lea.
¿Alguien hace limpieza? Va a ser que no. No hay ningún garbage collector que detecte directorios de proyecto eliminados. Con el tiempo, ~/.claude/projects/ acumulará memorias de proyectos que ya no existen.
Si eres de los que borra proyectos con frecuencia, de vez en cuando conviene echar un ojo:
ls ~/.claude/projects/
Y borrar los directorios que ya no reconozcas. No va a pasar nada malo — lo peor que puede ocurrir es que la IA empiece de cero la próxima vez.
Qué aspecto tiene
Este es un ejemplo real. Hoy, después de una sesión migrando mi email fuera de Google Workspace, mi MEMORY.md quedó así:
# Memory - [email protected]
## Degoogle [email protected] — COMPLETADO (2026-02-12)
- Email: migrado a iCloud+ custom domain (plan 200 GB, coste 0€)
- ChatGPT: passkey configurada (iCloud Keychain)
- Linear: passkey web + API token funcionan
- Google Workspace: cancelado tras Takeout
## Wrapper op (cache de 1Password CLI)
- Ubicación: ~/.local/bin/op
- Cachea `op read` durante 1h, el resto pasa directo
- Por qué: Claude Code lanza un proceso nuevo por cada comando Bash
## Lecciones técnicas
- `stat` es GNU en este Mac (coreutils via Homebrew). Usar `stat -c %Y`
- Linear API: `issueCreate` requiere UUID del team, no el key
Nada de filosofía. Hechos concretos. La próxima vez que abra una sesión aquí, Claude ya sabe que el degoogle está hecho, que tengo un wrapper de op, y que stat es GNU en mi Mac.
El problema real que resuelve
No es solo «recordar cosas». Es evitar que la IA repita errores.
Hoy, la primera vez que escribí el wrapper de op, usé stat -f %m (sintaxis BSD). Falló porque mi Mac tiene GNU coreutils via Homebrew. Lo arreglé con stat -c %Y.
Sin MEMORY.md, la próxima vez que necesite stat en este proyecto, probará stat -f %m otra vez. Con MEMORY.md, ya sabe que no debe hacerlo.
Es la diferencia entre un compañero que apunta las cosas y uno que confía en su memoria. El que apunta no repite errores.
Cómo evitar que se llene de porquería
Aquí viene la pregunta obvia: si la IA escribe lo que quiere, ¿no acabará siendo un vertedero de notas irrelevantes?
Hay varias salvaguardas:
1. Límite de 200 líneas. Todo lo que pase de la línea 200 se trunca al cargar. Esto fuerza a ser conciso.
2. Organización por temas. Se pueden crear ficheros separados (debugging.md, patterns.md) y enlazarlos desde MEMORY.md. El fichero principal es un índice, no un cajón de sastre.
3. Tú tienes la última palabra. Es un fichero de texto en tu disco. Puedes editarlo, borrarlo, o decirle a Claude «limpia MEMORY.md, esto ya no es relevante».
4. La IA se autocorrige. Las instrucciones del sistema le dicen que actualice o elimine memorias que resulten estar equivocadas o desactualizadas.
En la práctica, funciona sorprendentemente bien. La IA tiende a ser más disciplinada que muchos humanos tomando notas — probablemente porque no tiene ego ni apego a sus propias ideas.
Por qué no lo conoce nadie
Buena pregunta. Lleva meses en Claude Code, funciona por defecto, y no recuerdo haberlo visto destacado en ningún changelog ni blogpost de Anthropic.
Mi teoría: es una funcionalidad que nació como infraestructura interna para mejorar la experiencia entre sesiones, no como un feature de cara al usuario. No tiene UI, no tiene toggle, no tiene panel de configuración. Es un fichero de texto en un directorio oculto.
Y ahí está el problema. Las funcionalidades más útiles suelen ser las más invisibles, porque nadie las busca si no sabe que existen.
La cuarta capa de memoria
Si leíste mi post sobre Linear, Beads y Tasks, MEMORY.md encaja como una cuarta capa que complementa a las demás:
| Capa | Horizonte | Quién escribe | Qué contiene | Ejemplo |
|---|---|---|---|---|
| Linear | Semanas/meses | Humano | Qué quieres | «Lanzar v2 en marzo» |
| Beads | Días/sesiones | Humano + IA | Qué hay que hacer | «Arreglar bug en cache» |
| Tasks | Horas | IA | Qué estoy haciendo | «Ejecutando tests» |
| MEMORY.md | Permanente | IA | Qué he aprendido | «stat es GNU aquí» |
Las tres primeras son sobre trabajo: qué hacer, en qué orden, quién lo hace. MEMORY.md es sobre conocimiento: qué hemos aprendido haciéndolo.
Y ahí está la clave. Beads y Tasks son efímeros por diseño: una tarea se completa y se cierra, un issue se resuelve y se archiva. MEMORY.md es lo que queda después. Las lecciones, no los deberes.
Un ejemplo concreto de cómo se complementan: hoy usé Linear para trackear las issues del degoogle (PER-16 a PER-28). Tasks para seguir los pasos dentro de cada issue. Y MEMORY.md para apuntar que la API de Linear necesita UUIDs para los teams, no los keys. Las issues se cerraron. Las Tasks desaparecieron. La lección de los UUIDs sigue ahí para la próxima vez.
Cómo empezar a usarlo
No hay que activar nada. Ya está funcionando.
Lo único que tienes que hacer es decirle a Claude «apunta esto en tu memoria» cuando ocurra algo que merezca la pena recordar:
- Decisiones técnicas («elegimos iCloud+ para el email»)
- Errores y soluciones («
states GNU, usar-cno-f«) - Contexto del proyecto («el degoogle está completado»)
- Preferencias descubiertas («el usuario prefiere X sobre Y»)
Y de vez en cuando, revisar ~/.claude/projects/*/memory/MEMORY.md para ver qué ha apuntado y podar lo que sobre.
El cuaderno del buen aprendiz
Hay una frase de Feynman que viene al pelo: «The first principle is that you must not fool yourself — and you are the easiest person to fool.»
Un LLM no se engaña a sí mismo porque no tiene ego. No piensa «ya me acordaré» ni «esto es demasiado obvio para apuntarlo». Si le dices que apunte algo, lo apunta. Si descubre que una nota es incorrecta, la corrige.
En cierto modo, es mejor tomando notas de lo que la mayoría de nosotros seremos nunca. Solo le faltaba un sitio donde guardarlas.
Ahora lo tiene.
Read this article in English.
