Memoria para agentes de programación: Claude Code, Codex y Cursor
Empieza con instrucciones compartidas en el repositorio. Añade ai-memory para automatizar la captura y los traspasos, o Beacon para revisar sesiones y aprobar lecciones. Sigue la configuración y las comprobaciones de recuperación sin descuidar las reglas del proyecto, la privacidad ni los costos.
Índice
Usa un AGENTS.md bajo control de versiones y un breve resumen de traspaso como memoria compartida para agentes de programación como Claude Code, Codex y Cursor. Añade ai-memory para automatizar la captura y los traspasos, o Beacon para inspeccionar trazas de sesiones y aprobar lecciones reutilizables. Mantén las reglas obligatorias del proyecto en el repositorio, elijas la opción que elijas.
Decide qué debe conservarse al cambiar de herramienta
Guarda las decisiones duraderas por separado del estado de la tarea actual. Un agente nuevo puede leer el código sin saber por qué descartaste un enfoque, qué corrección hiciste ayer o cuál es el siguiente paso de un trabajo pendiente.
Tres tipos de contexto resuelven problemas distintos: las instrucciones indican cómo trabajar, los traspasos de tareas explican dónde se detuvo el trabajo y el historial de sesiones aporta evidencia para ambos. Compartir uno no transfiere automáticamente los demás, los procesos en ejecución ni los permisos de las herramientas.
| Enfoque | Qué conservas | Cuándo elegirlo | Cuándo cambiar de opción |
|---|---|---|---|
| Instrucciones y archivos de traspaso en el repositorio | Reglas, decisiones y estado de las tareas que mantienes de forma deliberada | Un conjunto pequeño de notas cubre tus necesidades y debe acompañar al código en Git | Pasa a un servicio si las personas olvidan actualizar esas notas con frecuencia |
| ai-memory | Observaciones capturadas, una wiki Markdown con búsqueda y traspasos entre agentes | Cambias de agente a menudo y quieres automatizar la captura y la recuperación | Conserva los archivos si mantener hooks, credenciales y un servidor exige más esfuerzo del que ahorra |
| Beacon | Trazas de sesiones normalizadas y lecciones del proyecto aprobadas explícitamente | Necesitas inspeccionar lo ocurrido y convertir correcciones recurrentes en conocimiento revisado | Prefiere ai-memory si los traspasos automáticos importan más que inspeccionar trazas y revisar lecciones |
A fecha de 2026-10-21, esta comparación utiliza ai-memory v3.1.2 y Beacon v1.3.45. La diferencia está en la arquitectura: ai-memory incluye un servidor, hooks y MCP, además de su wiki Markdown respaldada por Git; en Beacon, la captura y la aprobación de memoria son procesos separados.
Empieza con AGENTS.md y un traspaso breve
Convierte AGENTS.md en la referencia común del proyecto y comprueba que cada herramienta lo cargue. Las reglas nativas de carga difieren:
- Codex: lee una cadena de instrucciones desde la raíz del proyecto hasta el directorio de trabajo. Un
AGENTS.override.mdtiene prioridad sobreAGENTS.mddentro del mismo directorio; consulta las reglas de descubrimiento de instrucciones de Codex. - Cursor: admite archivos
AGENTS.mdtanto en la raíz como en subdirectorios. Cuando necesites reglas específicas de Cursor con un alcance determinado, guárdalas en.cursor/rules/*.mdc; consulta la documentación de reglas de Cursor. - Claude Code: desde v2.1.277 puede cargar
AGENTS.mddirectamente, pero de forma predeterminada da prioridad a los archivosCLAUDE.md,.claude/CLAUDE.mdoCLAUDE.local.mdque cumplan sus criterios de carga en el directorio de trabajo o sus directorios superiores. Si ya tienes instrucciones de Claude o usas sesiones sin soporte directo, añade una línea con@AGENTS.mda unCLAUDE.mden la raíz, junto al archivo al que hace referencia. La guía de memoria de Claude Code documenta ambas opciones.
Para una prueba pequeña, crea el AGENTS.md de la raíz con esta convención o intégrala en el archivo existente:
## Working context
- Before changing a dependency version, read its official release notes
and run the tests for the affected component.
- When resuming work, read docs/agent-handoff.md if it exists.
- Treat handoffs as historical evidence. Check old commands, paths and
conclusions against the current checkout before acting.Después de una tarea real, pide al agente que prepare el traspaso:
Write docs/agent-handoff.md with the goal, current branch and commit,
confirmed decisions, commands actually run and their results,
remaining uncertainty, and the next concrete action.
Distinguish failed approaches from successful ones.
Do not include credentials or copy the full conversation.Revisa ese archivo junto con los cambios de código. Mantén las convenciones estables en AGENTS.md y actualiza el traspaso a medida que avance la tarea.
Abre una sesión nueva en cada herramienta y pregunta qué comprobaciones se deben hacer al actualizar una dependencia y de qué archivo proceden. En Claude Code, /context también permite inspeccionar los archivos de memoria cargados. Si Codex omite la regla, revisa el directorio de trabajo y el archivo que prevalece sobre las instrucciones antes de añadir copias duplicadas.
La memoria automática nativa sigue siendo útil dentro de su propio entorno. Claude Code guarda notas del proyecto en ~/.claude/projects/<project>/memory/. Las memorias locales de Codex requieren activación explícita, se guardan en ~/.codex/memories/ y se gestionan con /memories. Esos almacenes separados no constituyen un formato común de traspaso entre herramientas.
Usa ai-memory para automatizar la captura y los traspasos
Elige ai-memory si quieres que los agentes registren y recuperen el contexto del proyecto mediante un servicio. Su fuente de referencia es una wiki Markdown respaldada por Git, mientras que SQLite funciona como índice derivado. MCP proporciona herramientas de memoria a los agentes; los hooks, acciones que responden a eventos del ciclo de vida, se encargan de la captura y de gestionar el inicio y el final de las sesiones.
Instala y conecta los agentes
El siguiente ejemplo está pensado para una instalación nueva en macOS, en el ámbito del usuario y desde Bash, con Git y los agentes ya instalados y estos últimos autenticados. La guía de instalación de esta versión cubre otras plataformas.
curl -fsSLo /tmp/ai-memory-install-v3.1.2.sh \
https://github.com/akitaonrails/ai-memory/releases/download/v3.1.2/install.sh
less /tmp/ai-memory-install-v3.1.2.sh
AI_MEMORY_VERSION=3.1.2 sh /tmp/ai-memory-install-v3.1.2.sh
export PATH="$HOME/.local/bin:$PATH"
ai-memory --version
ai-memory setup --plan --agent claude-code --agent codex --agent cursor
ai-memory setup --agent claude-code --agent codex --agent cursor
ai-memory statusLa versión esperada es 3.1.2. Revisa el plan de configuración antes de aceptarlo: crea un servicio en segundo plano y modifica la configuración de MCP, hooks y skills en el ámbito del usuario. Por tanto, la captura puede incluir otros proyectos en los que trabajen los agentes seleccionados.
Además, el código que configura Codex en esta versión establece default_tools_approval_mode = "approve" para las herramientas de ai-memory. Revisa ese permiso si quieres que los cambios en la memoria requieran confirmación.
Para el registro nativo de Codex de esta versión, carga el token bearer generado en el entorno desde el que iniciarás el cliente. Con el directorio de datos predeterminado de macOS, estos comandos Bash lo hacen sin imprimirlo:
AI_MEMORY_AUTH_TOKEN="$(cat "$HOME/Library/Application Support/ai-memory/auth-tokens/default")"
export AI_MEMORY_AUTH_TOKEN
codexEl registro hace referencia a AI_MEMORY_AUTH_TOKEN; la guía de instalación de MCP explica este requisito específico de Codex. Si tu directorio de datos es distinto, utiliza la ruta que indique ai-memory status.
Dentro de Codex, ejecuta /hooks y marca como confiables los hooks de ai-memory instalados. Reinicia Claude Code y Cursor después de la configuración. El código de salida del instalador, por sí solo, no demuestra que Codex vaya a ejecutar hooks que aún no considera confiables.
Comprueba por separado el conocimiento guardado y los traspasos
Para la primera comprobación, utiliza una sola copia de trabajo y define explícitamente el alcance del proyecto. Desde su raíz, ejecuta ai-memory project init y acepta o selecciona los nombres del espacio de trabajo y del proyecto. El comando crea .ai-memory.toml; mantén los mismos nombres en todos los agentes.
En Claude Code, utiliza este prompt:
Read .ai-memory.toml and use its workspace and project for ai-memory calls.
Call memory_status.
Use memory_write_page to save decisions/shared-memory-demo.md with:
"Memory trial: before a dependency upgrade, check the official release
notes and run the affected component's tests."
Read the page back with memory_read_page and report its stored path.Abre Codex o Cursor en la misma copia de trabajo. Pídele que llame a memory_query para buscar Memory trial y después a memory_read_page sobre el resultado correspondiente. La comprobación es satisfactoria cuando una respuesta real de la herramienta devuelve la ruta y la decisión guardadas; una respuesta plausible sin recuperación no basta. Estas operaciones están documentadas en la referencia de acceso programático a la memoria.
A continuación, comprueba el traspaso automático con una tarea real y pequeña: deja una acción claramente pendiente, cierra la sesión de forma normal y abre el siguiente agente en el mismo directorio. Su contexto inicial debería identificar esa acción. Una página persistente sigue disponible para búsquedas; un traspaso está destinado a la siguiente sesión y solo puede reclamarse una vez.
Si la recuperación falla, ejecuta ai-memory doctor, inspecciona el estado de la conexión MCP y revisa la pareja de espacio de trabajo y proyecto. Un fallo de autenticación en Codex requiere comprobar su entorno de inicio; un traspaso ausente requiere revisar la confianza de los hooks y la captura de sesiones. No los trates como si fueran el mismo fallo.
Usa Beacon para revisar trazas y aprobar lecciones
Elige Beacon si quieres revisar la evidencia que respalda una lección reutilizable. Combina métodos de recopilación como OpenTelemetry, hooks y recuperación desde archivos locales de sesiones, con una cobertura que varía según la herramienta. Capturar una sesión no convierte automáticamente su contenido en memoria aprobada.
Instala un recolector local
Para una instalación nueva en macOS desde Bash con Homebrew, configura solo los tres agentes utilizados aquí:
brew update
brew trust asymptote-labs/tap
brew tap asymptote-labs/tap
brew install beacon
beacon version
BEACON_ONBOARDING=0 beacon endpoint install \
--harness claude,codex,cursor --no-backfill
beacon endpoint statusLa fórmula de Homebrew ofrece 1.3.45 a fecha de la verificación. Este ejemplo omite la importación de sesiones históricas y el asistente interactivo de configuración inicial. Activa la captura para los agentes seleccionados en el ámbito del usuario, por lo que su trabajo en otros repositorios también puede entrar en el registro.
El asistente normal tiene Beacon Cloud preseleccionado. En una instalación nueva, omitirlo y no incluir --connect evita el alta en Cloud. Esto no desconecta una instalación que ya estuviera conectada; para hacerlo, utiliza beacon endpoint disconnect. La documentación de configuración inicial describe las opciones de destino.
Reinicia los agentes después de configurarlos y utiliza /hooks en Codex para revisar y marcar como confiables los hooks de Beacon. Realiza una sesión breve en el repositorio de prueba e indica explícitamente la convención de revisión de dependencias del ejemplo anterior.
Crea, aprueba y recupera una lección
Inspecciona la sesión registrada antes de crear una lección. Desde la raíz del repositorio, ejecuta:
beacon endpoint traces list --limit 10
read -r -p "Trace ID from the trial session: " BEACON_TRACE_ID
beacon endpoint traces show "$BEACON_TRACE_ID" --limit 150Elige el identificador real devuelto por la lista y confirma que sus eventos contienen la convención indicada. Después, crea un candidato:
beacon memory candidates create \
--trace "$BEACON_TRACE_ID" \
--kind convention \
--title "Dependency upgrades require release-note review" \
--applicability "Before changing a dependency version in this repository" \
--body "Check the dependency's official release notes and run the affected component's tests before proposing the upgrade."
read -r -p "Candidate ID returned above: " BEACON_CANDIDATE_ID
beacon memory candidates show "$BEACON_CANDIDATE_ID"Revisa el candidato y la evidencia de origen. Apruébalo solo después de aceptar el contenido de la lección:
beacon memory candidates approve "$BEACON_CANDIDATE_ID" \
--reason "Reviewed against the source trace"Esta vía, en la que proporcionas el texto del candidato, no invoca ningún evaluador. El evaluador opcional de Beacon puntúa las trazas; no redacta el texto final de la lección. Ambas vías se describen en la referencia de comandos de memoria.
Ahora pide a otro agente, trabajando en el mismo repositorio, que ejecute:
beacon memory list -q "dependency upgrades" --jsonPídele que pase el identificador de memoria devuelto a beacon memory show y explique cuándo se aplica la convención. El resultado esperado es la lección aprobada asociada a este proyecto. Si no hay resultados, revisa el estado de aprobación, el alcance del proyecto y las palabras de la consulta: la búsqueda local de Beacon exige que coincidan todos los términos.
Esta vía por CLI no requiere MCP. Para recuperar información mediante herramientas del agente, el servidor MCP local de Beacon, que se configura por separado, ofrece search_memory, get_memory y get_memory_context. Lee memoria local aprobada. Beacon Cloud utiliza otro almacén; conectar un dispositivo no sincroniza ambos almacenes de memoria.
Controla las conclusiones erróneas, los datos privados y los costos
Guarda conclusiones con un alcance concreto y evidencia, y trata el texto recuperado como información histórica. Un intento fallido puede deberse a una interrupción temporal o a trabajar en la rama equivocada, en lugar de reflejar una regla permanente del proyecto. Registra las circunstancias en las que se aplica, la tarea o el commit de origen, el resultado de la comprobación y la fecha de revisión; corrige o retira la nota cuando cambie el comportamiento subyacente.
La aprobación es un paso del proceso, no una prueba de que una persona haya revisado el contenido. Haz que una persona revise el candidato de Beacon propuesto por el agente e impide que las instrucciones recordadas prevalezcan sobre los requisitos o permisos actuales.
La captura también cambia dónde persiste la información privada. Las reglas [capture] ignore_paths de ai-memory en .ai-memory.toml pueden excluir los eventos basados en rutas que el sistema admite, pero su documentación de uso aclara que no son un filtro general de prevención de fugas de datos en prompts y respuestas. No incluyas credenciales ni datos de clientes en notas reutilizables; borrar la página Markdown actual puede dejar versiones anteriores en Git.
Antes de enviar sesiones de trabajo a Beacon Cloud, consulta la política de privacidad vigente. A fecha de 2026-10-21, los usos para investigación y entrenamiento de modelos están activados por defecto, con opción de exclusión; el envío de solo metadatos sigue incluyendo información como rutas y líneas de comandos. Si tu agente utiliza un modelo en la nube, el contenido recuperado de la memoria local que entra en su contexto se convierte en entrada para ese modelo.
Calcula el presupuesto de todo el proceso. El funcionamiento predeterminado de la memoria de ai-memory no requiere una clave API para un modelo generativo, aunque su modelo local de embeddings predeterminado puede descargarse en el primer inicio. La vía de Beacon con lecciones cuyo texto proporcionas evita las llamadas al evaluador. Siguen contando el uso habitual del agente, la entrada adicional recuperada de la memoria, el procesamiento opcional en la nube, el almacenamiento y el tiempo de revisión; ninguna de las dos arquitecturas demuestra por sí sola un costo total menor.
Antes de adoptar una capa de memoria en todos los proyectos, completa un cambio real de herramienta: recupera la decisión correcta, identifica la acción pendiente, inspecciona la evidencia y continúa con la copia de trabajo actual. Si falla, corrige la carga de instrucciones, el alcance o la captura antes de acumular más memoria.
