MemoryBrain

MemoryBrain › Guías

CLAUDE.md, AGENTS.md y la memoria de Claude Code y Codex: ¿qué es cada uno?

CLAUDE.md y AGENTS.md contienen instrucciones del proyecto. La memoria automática guarda aprendizajes entre sesiones. Codex busca AGENTS.md; Claude Code puede leer ambos nombres, según la versión, los archivos presentes y la configuración.

Por Carlos Moya. Actualizado el 8 de noviembre de 2026.

Comprueba qué está leyendo tu agente

  1. Identifica la herramienta y la versión

    En Claude Code, ejecuta claude --version. El soporte directo de AGENTS.md llegó en v2.1.277, el 18 de septiembre de 2026. No confundas estos archivos del repositorio con la memoria de la app de chat.

  2. Revisa los archivos y la precedencia

    Codex carga primero las instrucciones globales de ~/.codex y después las del proyecto hasta el directorio de trabajo. En cada nivel elige AGENTS.override.md antes que AGENTS.md; las instrucciones más cercanas al directorio de trabajo prevalecen sobre las anteriores.

    Claude Code usa por defecto AGENTS.md si no encuentra CLAUDE.md, .claude/CLAUDE.md o CLAUDE.local.md en el directorio de trabajo o sus antecesores. Si los encuentra, usa los archivos de Claude. En /config, «Project instructions» permite cambiar esa selección y leer ambos.

  3. Comprueba la carga, no solo la respuesta

    En Claude Code, revisa /memory. Antes de v2.1.280, los AGENTS.md leídos directamente no aparecían en esa lista. En Codex, empieza una sesión nueva y pide que enumere las fuentes de instrucciones cargadas. Contrasta las rutas con tus archivos.

  4. Prueba una regla sencilla

    Añade una convención observable, pide un cambio pequeño y revisa el resultado. No uses secretos ni una operación de despliegue como prueba. Una respuesta que recita una regla no demuestra que la aplique.

Instrucciones y memoria automática son cosas distintas

AGENTS.md es un formato abierto para orientar agentes de programación. Pon ahí comandos reales del proyecto y convenciones revisadas por el equipo. No es un registro automático de todas las sesiones.

En Claude Code, la memoria automática contiene notas que escribe Claude. Su índice es MEMORY.md y puedes revisarla desde /memory. Los archivos CLAUDE.md se acumulan desde directorios superiores; los más próximos se leen después y CLAUDE.local.md se añade tras CLAUDE.md en cada nivel. Evita reglas contradictorias: son contexto, no permisos obligatorios.

Codex tiene además una memoria local propia, separada de la de ChatGPT web. Está desactivada por defecto. Al activarla, puede generar archivos de memoria a partir de chats anteriores aptos y actualizarlos en segundo plano; no necesariamente al cerrar cada chat. En Codex CLI, /memories controla si el chat actual puede usar recuerdos o contribuir a recuerdos futuros. Los archivos generados se guardan bajo el directorio de Codex, por defecto ~/.codex. Revísalos como estado generado, no como sustituto de AGENTS.md ni como instrucciones que debas editar a mano de forma habitual.

Un archivo mínimo que puedes adaptar

Ejemplo didáctico para AGENTS.md. Sustituye el comando por uno que exista en tu repositorio:

# Instrucciones del proyecto
## Validación
- Ejecuta npm test después de cambiar lógica.
- Indica qué has comprobado y qué no.
## Estilo
- Sigue las convenciones del archivo que editas.
- No añadas dependencias sin explicar el motivo.

Si Claude no carga AGENTS.md directamente, un CLAUDE.md situado a su lado puede contener @AGENTS.md. Es una importación explícita; evita mantener dos copias que acaben diciendo cosas distintas.

La release v2.1.277 excluía Bedrock, Vertex y Foundry del nuevo soporte. Es una limitación de esa release. La documentación actual describe cambios posteriores, incluidos casos anteriores a v2.1.281. Comprueba tu versión y la carga real antes de aplicar aquella excepción a una instalación actual.

Dónde encaja una memoria personal

Las decisiones personales con su fuente pueden vivir fuera del repositorio. MemoryBrain sirve esa memoria a ChatGPT y Claude; no sustituye las instrucciones ni los permisos del agente de código. Más: cómo revisar un archivo de memoria antes de confiar en él.

Preguntas frecuentes

¿Puedo usar solo AGENTS.md?

Codex lo reconoce. Claude Code también puede leerlo, pero comprueba la versión, los archivos de Claude presentes y el ajuste Project instructions.

¿CLAUDE.md obliga al agente a cumplir todas las reglas?

No. Es contexto para orientar al agente. Los permisos y las restricciones que deban imponerse necesitan controles de la herramienta.

¿El ejemplo es una configuración probada en mi repositorio?

No. Es una plantilla didáctica. Adapta el comando de pruebas y comprueba su carga en una sesión nueva.

Pruébalo

Mira cómo funciona una memoria que guarda la fuente de cada cosa, sin crear una cuenta.

Entrar en la listaVer una demo sin cuenta

Fuentes