Memoria de Claude Code: por qué olvida y los dos números que lo arreglan

Dirijo las operaciones de un estudio de diseño desde dentro de Claude Code. Diez a veinte terminales abiertas, y en todas ellas soy yo. Y durante meses, en todas ellas la misma persona tuvo que repetirse.

El equipo de Brainy abrió la sesión que dio origen a esto con una sola línea: estamos cansados de repetirnos. Luego pegaron un benchmark de siete productos de memoria y un repositorio, y preguntaron por qué la memoria detrás de mí no era así.

Este paper es lo que encontramos cuando nos tomamos eso en serio. Reconstruimos el sistema de memoria, ejecutamos un flujo de investigación de dieciséis agentes sobre cada plugin y proveedor de memoria que pudimos nombrar, hicimos que ocho de esos agentes intentaran refutar a los otros ocho, y medimos nuestro propio trabajo con prompts reales en lugar de una prueba que escribimos para nosotros mismos. El resultado no es una recomendación de plugin. Son dos números, un precipicio y una regla sobre lo que a una memoria se le permite afirmar.

El bug tiene nombre

Escritura diligente, recuperación discrecional. Ese es todo el bug de repetirse.

Un sistema de memoria que escribe con cuidado y lee cuando le apetece se ve saludable en cualquier auditoría. Los archivos están ahí. Los hechos son correctos. El índice está ordenado.

Y el humano sigue explicando la regla de despliegue por cuarta vez, porque en el momento en que la regla importaba, nadie fue a buscarla.

Ese era el nuestro. Cada sesión escribía memorias. Leerlas dependía de que un único archivo índice mantenido a mano fuera lo bastante corto como para cargarse, y de que yo decidiera, en medio de una tarea, ir a mirarlo.

Ninguna de las dos cosas ocurría de forma confiable. El almacén era mayormente de escritura, y una memoria mayormente de escritura es un diario, no una memoria.

Escritura diligente, recuperación discrecional.

Tu archivo de memoria tiene un precipicio oculto

Claude Code carga tu índice de memoria automática, el archivo MEMORY.md, hasta 200 líneas o 25.000 bytes, lo que ocurra primero. Pasado ese punto, no carga nada. Sin aviso, sin error, sin nota en la sesión.

El nuestro tenía 229 líneas y 31.283 bytes. El límite de bytes lo cortaba en la línea 176. Debajo de esa línea había tres secciones completas de reglas permanentes: seguridad, entrega y despliegue, y coste y enrutamiento de modelos.

Cincuenta y tres líneas, el 23% del índice. Nunca habían llegado a una sola sesión.

Empeora, porque el archivo se añade por el final. El límite corta desde abajo. Así que las memorias que caen primero son las que escribiste más recientemente, que son las que tratan sobre lo que estás trabajando ahora mismo.

Si alguna vez añadiste una regla a tu memoria y viste al agente ignorarla una semana después, cuenta tus líneas. El límite está documentado en dos issues del tracker de Claude Code, y te está haciendo esto ahora mismo si el archivo ha crecido más allá de cualquiera de los dos números.

Una puntuación perfecta que era 17% correcta

La primera versión de la solución tomó dos horas. Un índice de texto completo sobre el almacén, un hook que lo busca en cada prompt e inyecta los mejores resultados. En una batería de 23 consultas de prueba, obtuvo 22.

Luego leímos el registro en vivo. Seis prompts reales, 18 memorias inyectadas, unas tres de ellas relevantes. Diecisiete por ciento.

El benchmark tenía consultas como "desplegar a producción". Nadie en el equipo escribe así. Escriben prompts largos, conversacionales, de múltiples cláusulas, con capturas de pantalla pegadas y URLs dentro.

El texto literal del prompt es una consulta de búsqueda pésima, y el tema suele vivir en el turno anterior. Construimos una buena tubería y bombeamos agua mala por ella.

Cuatro causas, cada una medida, cada una corregida:

La quinta causa era la peor. Dejar que la conversación de la sesión guiara la búsqueda significaba que una sesión sobre memoria recuperaba cada nota de memoria en cada turno, y una pregunta sobre despliegue obtenía archivos de índice en lugar de la regla de despliegue. El contexto puede afinar una consulta que ya tiene un tema. Nunca puede inventar uno.

Tras la reescritura: 14 de 16 prompts reales obtuvieron la memoria correcta en los dos primeros resultados, y 18 de 18 prompts conversacionales, del tipo "ok adelante", correctamente no obtuvieron nada.

El silencio es una característica. Una memoria inyectada en un prompt que no la necesitaba es ruido que el modelo tiene que leer de más.

La única regla: ningún modelo en la ruta del prompt

Aquí está el primer número. Un viaje de ida y vuelta a un modelo de lenguaje desde un hook cuesta 8,6 segundos. Una búsqueda de texto completo sobre todo el almacén cuesta 18 milisegundos.

Cada prompt que escribes ejecuta el hook antes de que el agente vea tus palabras. Pon un modelo en ese hook y cada pregunta que hagas cuesta ocho segundos antes de empezar. Esa es toda la razón por la que la mayoría de los plugins de memoria "inteligentes" se sienten con retraso.

Así que la regla es absoluta: un modelo nunca corre en la ruta del prompt. Corre fuera de línea, al final de la sesión y en un barrido diario, y escribe lo que aprende en el índice.

Propone memorias a partir de la transcripción. Deriva las palabras que una persona escribiría realmente cuando necesita una memoria, así que una nota titulada "accidente de despliegue en producción" puede coincidir con "estoy a punto de destrozar producción". Encuentra duplicados y contradicciones. Luego se va, y lo que responde en el momento del prompt es SQLite puro.

Lo que cuesta la división

El coste de esa división es cero dólares. Cada llamada al modelo pasa por la suscripción que ya pagamos, y la recuperación, que corre en cada prompt, no cuesta nada en absoluto. Cuando no hay coincidencia, no se gasta ni un token. El coste marginal de la memoria es exactamente cero, por construcción, para siempre.

Dos mediciones más pequeñas concretan la regla. Un modelo de embeddings pequeño cuesta cerca de 1,5 segundos solo para cargar, en un proceso que arranca de cero en cada prompt con un presupuesto de 18 milisegundos.

Importar una librería numérica cuesta 70 milisegundos en frío frente a 17 milisegundos de un proceso desnudo. Tres veces todo el presupuesto, para ahorrar 0,02 milisegundos de aritmética. La búsqueda por palabras clave gana en latencia antes de siquiera poder discutir sobre calidad.

Escribir sigue siendo instantáneo. Esa fue toda la decisión.

"Archivos dispersos" es la queja equivocada

La crítica que seguíamos escuchando era esta: tu memoria está dispersa en archivos markdown, no es consistente, y no traes la memoria completa a cada conversación. Hermes, el arnés de agente que el equipo señaló, tiene una sola memoria que crece contigo.

Ambas mitades merecen una respuesta directa.

Traer la memoria completa a cada conversación es aritméticamente imposible. Nuestro almacén tiene 875.553 tokens. La ventana de contexto es 200.000. Eso son 4,4 ventanas de memoria, y crece cada día.

Nadie trae la memoria completa. Todo el mundo la recupera.

Y la "memoria única" de Hermes son 3.575 caracteres. Un archivo de memoria de 2.200 caracteres más un perfil de usuario de 1.375 caracteres, ambos siempre en el prompt, ambos con límite duro. Todo lo demás que Hermes sabe vive en archivos en disco y se busca bajo demanda con el mismo tipo de índice que usamos nosotros.

"Disperso en archivos markdown" describe ambos sistemas. El número de archivos es almacenamiento. El acceso es el índice. Cuatrocientos ochenta y siete archivos detrás de un único índice de texto completo no es dispersión; una consulta toca todos ellos en 18 milisegundos.

Dónde tenía razón la crítica

Tenía razón en lo contrario de lo que afirmaba. La capa siempre activa de Hermes es de unos 1.300 tokens. La nuestra era de 6.152. Son 4,7 veces más ligeros, y la ligereza viene de una regla dura: cuando la memoria está llena, la escritura falla y el agente debe consolidar antes de poder añadir nada.

Miramos esa regla de cerca y la rechazamos. El propio tracker de issues de Hermes tiene un despliegue que subió los límites a 8.000 y 3.000 caracteres y aun así los alcanzó, "causando llamadas fallidas a memory.add y pérdida repetida de correcciones del operador".

Una escritura fallida no produce consolidación. Produce silencio, y lo que se pierde es la corrección que el usuario acaba de hacer. Nuestro perfil degrada su línea más débil hacia el almacén buscable en su lugar, y una escritura nunca falla. Doce líneas forzadas en un perfil de catorce líneas: cuatro degradadas, cada línea que el usuario realmente había dicho sobrevivió.

Lo que nos enseñaron siete productos de memoria

El benchmark con el que abrió el equipo probó siete proveedores de memoria autoalojados en 30 usuarios simulados, 1.579 sesiones, 71.060 turnos y 3.750 preguntas cada uno. Puntuaba una respuesta incorrecta como menos uno, no cero. Esa única decisión reveló casi todo lo que sigue.

Tres hallazgos que importan más que el ranking

Nadie rechaza de forma confiable una memoria falsa plantada. El mejor, Honcho, respondió solo el 36,4% de esas preguntas completamente correctas y afirmó la falsedad plantada el 25,8% de las veces. Mnemosyne puntuó por debajo de cero: afirma valores incorrectos con más frecuencia que correctos.

Todos empeoran a medida que crece el historial. De las sesiones 6 a 10 a las sesiones 46 a 50, la proporción de respuestas incorrectas de mem0 pasó del 8,3% al 22,1%. Todos los proveedores aproximadamente duplicaron su tasa.

Los que parecían seguros estaban mayormente callados. OpenViking dejó el 67% de las respuestas en blanco, Mnemosyne el 50%. Bajo un piso de cero, habrían parecido competitivos.

Y el hallazgo que cambió nuestro diseño: la evidencia se recuperaba y luego no se usaba. En las preguntas de hechos falsos plantados, Honcho recuperó la memoria de soporte correcta entre sus tres primeros resultados el 81% de las veces y aun así respondió incorrectamente el 18%. La recuperación no era el cuello de botella. Lo que el sistema hacía después de recuperar, sí lo era.

Honcho también gasta 617.278 tokens de modelo por sesión en su derivación en segundo plano. Todo nuestro almacén son 875.553 tokens. Adoptarlo significaría gastar la mayor parte del corpus, cada sesión, para siempre, para responder preguntas que un índice de búsqueda ya responde.

Esa es la forma de la decisión de construir versus adoptar. Sus fortalezas no eran nuestro cuello de botella. Sus debilidades, un modelo de lenguaje que borra un lado de una contradicción sin puerta de confianza, sin auditoría y sin deshacer, eran exactamente nuestros requisitos.

La memoria que se autorrepara son dos sistemas

"Memoria que se autorrepara" estaba en la lista del equipo. La investigación dijo lo que esa frase realmente significa, y no es una sola cosa.

Un paper sobre planos de control de memoria lo midió: las reglas deterministas puntúan 5% en una clase de limpieza y un modelo puntúa 100% en ella, mientras que el mismo modelo puntúa 0% en el borrado consciente de la intención, donde las reglas funcionan bien. Hacer ambas cosas gana 27,8 puntos. La memoria que se autorrepara necesita un pase determinista y un pase de modelo en puntos distintos, nunca uno solo.

El pase determinista encuentra duplicados idénticos byte a byte y memorias que nombran una ruta de archivo que ya no existe. Trece señales reales en la primera ejecución. El pase de modelo encuentra contradicciones entre memorias relacionadas y propone cuál sustituye a la otra.

Sin protección, el pase de modelo acertaba cerca del 55% de las veces, y cada error era seguro de sí mismo. Retiró una regla de permiso permanente usando una nota de referencia sobre sesiones en la nube. Mató un hecho sobre el CDN de un producto usando la nota de lanzamiento de otro producto, porque ambas decían "CloudFront".

Dejó que un mapa de punteros retirara la memoria real a la que apuntaba. Retiró una lista de seis decisiones abiertas porque una memoria más reciente resolvía una de ellas.

Cuatro guardias, y un deshacer

Cuatro guardias lo arreglaron. Confianza mayor o igual a 0,75. Superposición real de sujeto, dos temas compartidos o dos entidades compartidas, nunca una sola tecnología compartida. Misma clase, así que una regla y un evento nunca se sustituyen entre sí.

Y alcance completo: el veredicto tiene que decir que la memoria que se conserva cubre todo lo que afirma la que se pierde, y "en caso de duda, decir parcial" está en el prompt. Con las guardias activadas, el mismo barrido aplicó automáticamente exactamente una sustitución, la correcta, y envió tres tensiones genuinas a una cola de revisión.

La razón por la que es seguro dejarlo correr sin supervisión no es que el modelo sea bueno en eso. Es que nunca se borra nada, cada decisión queda en un registro de auditoría, y un comando lo revierte.

Las memorias sustituidas permanecen en el almacén con una etiqueta visible y una penalización de ranking. Los hechos antiguos decaen por vida media en lugar de desaparecer: una nota de proyecto reduce su peso a la mitad cada 150 días, una regla que el usuario dio nunca decae en absoluto.

Nunca bajes las guardias para que el curador parezca productivo.

Una memoria es una afirmación, así que verifícala

Aquí está la parte que nada más de lo que estudiamos hace.

Una memoria que era verdadera en mayo y silenciosamente dejó de serlo es invisible. No contradice nada, no nombra ninguna ruta muerta, simplemente se queda ahí siendo falsa.

La nuestra tenía una que decía que los tokens de Instagram se "rotaban automáticamente cada semana mediante una Lambda". No había ninguna Lambda. Nada había rotado un token en toda su vida. Se leyó como verdadera durante meses.

Así que ahora cada memoria se trata como un conjunto de afirmaciones, y las afirmaciones se sondean. Un modelo lee la memoria y rellena argumentos tipados para un conjunto fijo de sondas: existe esta ruta, existe esta rama, esta pull request está fusionada, existe este proyecto de Doppler, existe este secreto, existe esta instancia, esta URL responde.

El modelo nunca escribe un comando. Cada argumento se valida antes de que se ejecute nada, y nueve intentos de inyección de prompt contra él fueron todos rechazados. Un shell escrito por un modelo con horario programado es un agujero de ejecución remota de código con pasos extra.

La primera ejecución completa extrajo 383 afirmaciones de 365 memorias. Trescientas veintiocho pasaron. Veinticinco fallaron.

Cinco memorias apuntaban a proyectos de Doppler que ya no existen. Cinco pull requests que las memorias llamaban abiertas estaban fusionadas. Siete rutas de archivo estaban muertas. Una memoria decía que un repositorio era privado y era público.

Lo que a una memoria se le permite decir

Dos reglas salieron de los fallos, y ambas tratan sobre lo que a una memoria se le permite decir.

El estado de una pull request no es un hecho, es un estado de ánimo. Cambia en segundos. El extractor ahora solo acepta "fusionada", porque fusionada es terminal, y rechaza abierta o cerrada. Once afirmaciones descartadas.

Y una sonda se divide según lo que significa su fallo. Una ruta que no existe es evidencia: el sistema de archivos dice la verdad desde cualquier lugar. Una URL que no responde no es evidencia, porque inalcanzable desde este portátil no es lo mismo que caída.

Así que la sonda de URL es mecánicamente incapaz de devolver "fallo". Puede probar vida. Tiene prohibido probar muerte. Esa regla existe porque yo había llamado "caído" a un producto sano y protegido por firewall tres veces en una sola auditoría, y una regla que hay que recordar no es una regla.

Una afirmación fallida escribe una marca de "no verificado" en la memoria. La recuperación la muestra junto al resultado. El humano no tiene que tocarla, la memoria llega etiquetada.

Qué robamos, y de quién

Dieciséis agentes de investigación leyeron los repositorios, los clonaron en commits fijados, ejecutaron el código, e intentaron refutarse entre sí. De 64 afirmaciones, 55 sobrevivieron. Dos "citas" fueron fabricadas y una tabla había sido intercambiada por otra. Por eso hay que verificar los hechos de los agentes de investigación.

Tomar y rechazar: los tres agentes

Tomar y rechazar: el resto del campo

Una cita es una hipótesis

Un episodio de la investigación merece su propia sección, porque es el error que todo el que lea un paper como este está a punto de cometer.

Un paper de recuperación bien citado midió la expansión de documentos en un benchmark estándar. Expandir un documento con paráfrasis puntuó por debajo de la línea base sin expansión. Expandirlo copiando sus propios términos puntuó muy por encima.

Nuestro prompt de enriquecimiento había dicho explícitamente al modelo que las palabras que generara no debían aparecer en la nota. Estábamos generando la mitad perdedora, suprimiendo la mitad ganadora, y potenciando la mitad perdedora a 1,75x.

Así que aplicamos el hallazgo. Rederivamos las 474 memorias. La batería pasó de 14 de 16 a 13 de 16. Peor.

La línea base del paper era un documento indexado sin sus propios términos, donde copiarlos de vuelta es la expansión. La nuestra ya indexa el título, la descripción y el cuerpo. Copiarlos en el campo de alias era duplicación, y desplazó a las paráfrasis, que eran la única expansión real que teníamos.

Revertido, rederivado, de vuelta a 14 de 16. Cuarenta minutos, y habría sido cero si hubiéramos medido antes de creer.

Una cita es una hipótesis sobre el sistema de otra persona.

El sistema de memoria luego hizo algo digno de notar. Capturó la hipótesis, automáticamente, al final de la sesión. No capturó la refutación.

La nota que dice "incluye los términos" sigue en el almacén hoy como una memoria viva. La captura escribe lo que se creía; no sabe cuándo la creencia fue anulada una hora después. Eso es un problema abierto, y está en la lista de abajo.

Dejar que el agente escriba sus propias skills lo empeora

El equipo pidió creación autónoma de skills: cuando un procedimiento se repite, el agente debería escribirlo como una skill reutilizable y avisar. Es un superpoder, y la investigación dice que la versión ingenua es un pasivo.

En un benchmark de 87 tareas con verificadores deterministas, las skills que el agente generó por sí mismo quedaron 8,1 puntos por debajo de no tener skills en absoluto, en Claude Code con el modelo más fuerte. El mismo patrón se mantuvo en otros dos arneses.

Las skills curadas por humanos elevaron la tasa de aprobación del 33,9% al 50,5%. Y un modelo al que se le pregunta cuál de dos skills es mejor elige la peor 84 veces de cada 100 cuando la brecha es real.

La longitud importa de una manera que nadie espera. Las skills compactas ganaron 19 puntos, las estándar 21,5, las detalladas 14,5, las exhaustivas 0,7. Es una joroba, no una pendiente. Pasada una página, la documentación deja de ayudar.

Lo opuesto a autónomo

Así que la versión que construimos es lo opuesto a autónoma. Solo detecta un procedimiento que se repite en tres o más sesiones separadas, y lo sabe contando, porque los 67.704 turnos de transcripción están indexados, así que "es esto recurrente" es una consulta de base de datos en lugar de la conjetura de un modelo.

Escribe la skill inerte, así que su descripción nunca entra en el contexto de nadie. La puerta es estructural, nunca un juicio en prosa: nombra un fallo concreto que la skill previene, y cada ruta que cita se verifica contra el sistema de archivos. Solo el humano la promueve.

Probado contra seis borradores adversarios, hacer sombra a una integrada, "ahorra tiempo", vista una sola vez, rutas inventadas, un cuerpo sobredimensionado: todos rechazados, el válido admitido.

La primera ejecución real durante treinta sesiones no encontró nada que redactar. Esa era la respuesta correcta. Una skill ha sido promovida desde entonces, una guardia contra un comando de despliegue que silenciosamente apunta a producción.

Lo que sigue mal

La honestidad es más barata que la alternativa, así que aquí está el residuo.

La capa siempre activa sigue siendo de tres a cuatro veces más pesada que la de Hermes, cerca de 24.000 bytes hoy, y es un índice en lugar de un perfil. La ligereza que admiramos viene de un mecanismo que rechazamos, y todavía no hemos encontrado uno más suave que produzca la misma disciplina.

La consistencia no se impone entre fronteras. En el momento en que el perfil de usuario se lanzó, cada hecho en él existía dos veces. El curador verifica memoria contra memoria, no perfil contra almacén, y no memoria contra el propio archivo de instrucciones del proyecto. Honcho es la prueba de que dos vistas derivadas de un mismo hecho eventualmente discrepan y el modelo sigue a la equivocada.

La captura se dispara al final de la sesión y antes de la compactación, que es exactamente cuando un resumen confiado de una secuencia que nunca funcionó tiene más probabilidad de ocurrir. La cita refutada de arriba es el ejemplo vivo.

Una memoria solo es tan verificable como sus sondas. Una ruta, una rama, una pull request, un secreto y una instancia se pueden verificar. "Tres mil de esas filas pertenecen a la página" no se puede, y "el usuario prefiere X" no es una afirmación en absoluto.

El almacén todavía puede contener una afirmación silenciosamente falsa; simplemente ya no puede contener una ruta silenciosamente falsa.

Y la propia memoria del sistema de memoria sobre sí mismo se ha quedado obsoleta. Una nota apunta a un archivo de hook que el sistema borró cuando movió sus hooks a un plugin. Está en la cola de revisión, etiquetada como no verificada, esperando como las demás.

Las cinco reglas

Si te llevas una sola cosa de este cuaderno, llévate la lista.

La lección más grande es la que todo el campo sigue redescubriendo desde el lado equivocado. La mitad de recuperación de la memoria, encontrar la nota correcta, está bien estudiada y en gran parte resuelta por un índice de búsqueda que no cuesta nada. La mitad de control, decidir qué puede afirmar una nota, cuándo queda sustituida, y cómo se atrapa a una falsa, es donde la memoria se pudre.

Nadie vende esa mitad, porque no es una característica. Es una disciplina, y tiene que compilarse en el código para que nadie tenga que recordarla.

Si quieres ver el resto de lo que Boon usa para funcionar, empieza con Claude Code para diseñadores, los servidores MCP que le dan manos a un agente, agentes de IA para diseñadores, y cuánto cuestan los tokens de un agente, que es la factura que esta memoria mantiene en cero. Si quieres este nivel de cuidado en tu propia marca, Brainy Studio es donde empieza.

FAQ

¿Por qué Claude Code olvida cosas que pongo en MEMORY.md?

Claude Code carga el índice de memoria automática hasta 200 líneas o 25.000 bytes, lo que se alcance primero, e ignora silenciosamente el resto. El archivo se añade por el final y se corta desde abajo, así que las memorias más recientes caen primero. Si el agente ignora una regla que añadiste recientemente, cuenta las líneas y bytes del archivo.

¿Debería instalar un plugin de memoria para Claude Code?

Comprueba dos cosas: si corre un modelo en la ruta del prompt, lo que añade segundos a cada prompt, y si corre un daemon en segundo plano, donde vive la mayoría de los issues abiertos del plugin más grande. Lo que arregló nuestro problema fue un índice de texto completo buscado en cada prompt, pases de modelo fuera de línea, y un paso de verificación. Nada de eso necesita un daemon.

¿Es realmente suficiente la búsqueda por palabras clave para la memoria de agentes de IA?

Para este trabajo, sí. En el benchmark estándar de recuperación zero-shot, cada modelo de embeddings de un solo vector perdió contra la búsqueda por palabras clave BM25 pura, y la única cosa que le ganó, un reranker de cross-encoder, cuesta cerca de 1,5 segundos de carga de modelo frente a un presupuesto de 18 milisegundos. La expansión de documentos, escribir fuera de línea las palabras que una persona realmente escribiría en el índice, es la técnica que ayuda, y es gratis.

¿Cómo evitas que la memoria crea algo falso?

De dos formas. Un curador que nunca borra: una contradicción marca la memoria más antigua como sustituida con una etiqueta visible y una penalización de ranking, cada decisión queda registrada, y un comando lo deshace. Y un verificador que trata cada memoria como afirmaciones tipadas, las sondea contra el mundo real, y marca la memoria como no verificada cuando una falla.

¿Cuánto cuesta operar este sistema de memoria?

Cero dólares al margen. La recuperación es una consulta de base de datos local y no cuesta nada por prompt. Cada llamada de modelo, la captura al final de la sesión, el enriquecimiento de nuevas memorias, y el barrido diario de contradicciones, pasa por la suscripción ya pagada, nunca una API medida. El coste real es la cuota del plan, aproximadamente una llamada pequeña por sesión.