Memoria de IA: Memoria Persistente de Codificación Cross-Agent

Dejas Claude Code a mitad de una tarea tras cuatro horas de ida y vuelta: decisiones de arquitectura tomadas, tres enfoques probados y descartados, una cuestión abierta sin resolver. Una hora después abres Codex en el mismo directorio para intentar algo en lo que es mejor. Codex no sabe nada de eso. Vuelves a explicar la arquitectura, los enfoques fallidos y la cuestión abierta, porque ese contexto vivía en la transcripción de una herramienta y en ningún otro sitio. Multiplica eso por la cantidad de CLIs de agentes que realmente usas en una semana determinada; y en 2026, con Claude Code, Codex, Cursor, Antigravity, Grok Build, Kimi Code y una docena más siendo viables al mismo tiempo, ese número rara vez es uno.

El error habitual en cómo se resuelve la “memoria de agentes de IA” es recurrir directamente a una base de datos vectorial y dar el problema por resuelto. ai-memory, un proyecto open source en Rust de Fabio Akita, adopta una postura deliberadamente distinta: compilar un resumen coherente al final de una sesión en lugar de recuperar fragmentos de registros sin procesar al inicio de la siguiente, almacenarlo como markdown plano en un repositorio git en lugar de embeddings en un vector store, y tratar “qué proveedor de agente estás usando ahora mismo” como algo irrelevante para determinar si tu memoria te acompaña. Esta publicación recorre cómo está construido eso en la práctica.

Aprenderás:

• Por qué “compilar, no recuperar” es un enfoque fundamentalmente distinto de la memoria de agentes frente a las herramientas basadas en RAG
• Cómo los traspasos cross-agent te permiten salir de Claude Code y reanudar el mismo trabajo en Codex, Cursor o Gemini CLI
• Cómo el sistema híbrido de recuperación combina búsqueda de texto completo, coincidencia de entidades y vecinos del grafo, con vectores como algo opcional, no requerido
• Por qué la memoria recuperada se trata explícitamente como evidencia no confiable, nunca como instrucciones
• Cómo se compara operativamente el autoalojamiento de un único binario Rust con markdown respaldado por git frente a un servicio gestionado de base de datos vectorial
• Dónde están las limitaciones reales de esta herramienta y qué es lo que deliberadamente no intenta hacer

Tabla de contenidos

1. Lo básico
2. La arquitectura completa
3. Capas principales explicadas
4. Recorrido de extremo a extremo
5. Casos especiales
6. Escalado y desafíos de producción
7. Ejemplos de código
8. Errores comunes
9. Buenas prácticas de producción

Lo básico

Qué cubre realmente ai-memory

ai-memory resuelve dos problemas relacionados pero distintos. El primero es el que la mayoría de las herramientas de memoria intentan abordar: una sesión de agente termina y todo lo discutido —decisiones tomadas, enfoques probados y rechazados, preguntas abiertas— desaparece a menos que una persona lo anote manualmente en algún lugar. El segundo es el que casi nada más aborda: incluso si una herramienta individual recuerda su propio historial, esa memoria no viaja cuando cambias a un proveedor de agente distinto. Una sesión en Claude Code y una sesión en Codex son, por defecto, dos islas sin puente entre ellas.

La respuesta de ai-memory a ambos problemas es el mismo mecanismo subyacente. Los hooks del ciclo de vida capturan observaciones saneadas —prompts, llamadas a herramientas, límites de sesión— mientras la sesión se ejecuta. Al final de la sesión, esas observaciones se compilan en una página markdown coherente, no simplemente se archivan como un log en bruto. El siguiente agente que se abra en ese proyecto, independientemente del proveedor que sea, recibe un traspaso acotado de “dónde lo dejaste” antes de su primer prompt.

Por qué este es un problema de alto valor que merece resolverse bien

• El panorama de agentes en 2026 realmente está así de fragmentado. Los desarrolladores ahora suelen tener instalados Claude Code, Codex y al menos otro CLI, y recurren al que mejor encaja con la tarea: sandboxing en la nube por aquí, profundidad nativa de terminal por allá. Un sistema de memoria ligado a un solo proveedor resuelve una porción cada vez más estrecha del flujo de trabajo real de un desarrollador.
• La pérdida de contexto tiene un coste real y recurrente. Volver a explicar la arquitectura y los enfoques fallidos no solo es molesto: consume tokens, consume tiempo y arriesga que el siguiente agente repita un enfoque que ya falló por razones que nunca llegó a conocer.
• La mayoría de las herramientas competidoras resuelven esto con una base de datos vectorial, lo que implica infraestructura de embeddings, un almacén que mantener disponible y un paso de recuperación que puede perder contexto que un humano consideraría obvio. Apostar por “compilar un resumen, no recuperar fragmentos” es una apuesta genuinamente distinta y vale la pena entenderla en sus propios términos.

La arquitectura completa

Agent CLI (Claude Code, Codex, Cursor, ...)
        │  lifecycle hooks fire-and-forget
        ▼
ai-memory server (single Rust binary)
        │
        ├── wiki/   ── markdown source of truth, git-versioned
        ├── raw/    ── sanitized transcript segments (managed workstreams only)
        ├── db/     ── SQLite: FTS5 index, entities, embeddings
        └── logs/
        │
        ▼
Session end ──▶ compile observations into a markdown page ──▶ typed handoff (pending)
        │
        ▼
Next agent's SessionStart ──▶ server finds pending handoff ──▶ injects "where you left off"

El principio rector es: un servidor, un directorio de datos, y el propio CLI es un cliente HTTP ligero. ai-memory status, bootstrap, search y el resto hablan con el servidor en ejecución en lugar de tocar directamente SQLite o los archivos del wiki. Markdown es la verdadera fuente de la verdad; SQLite es un índice reconstruible sobre él, lo cual importa más de lo que parece una vez que consideras lo que eso significa para copias de seguridad y recuperación.

Capas principales explicadas

1. Captura del ciclo de vida sin fricción

Qué es: Los hooks envían observaciones acotadas y saneadas de prompts, llamadas a herramientas y límites de sesión con el patrón fire-and-forget mientras un agente trabaja, sin bloquear la ejecución del propio agente.

Por qué importa: Una captura que obliga al desarrollador a recordar hacer algo derrota el propósito. Esto tiene que ocurrir automáticamente, y “fire-and-forget” significa específicamente que un servidor de memoria lento o inaccesible no se convierte en un cuello de botella en el bucle del propio agente.

Consejo de producción: Esto es captura acotada y saneada, no una transcripción completa: los lanzamientos directos intercambian exhaustividad por una sobrecarga casi nula, el valor por defecto correcto para la mayoría del uso cotidiano.

2. Compilar, no recuperar

Qué es: Al final de la sesión, las observaciones relevantes se compilan en una página markdown coherente en lugar de dejarse como un log en bruto para que un paso de recuperación futuro lo examine. Esto aplica directamente lo que a veces se llama el patrón wiki LLM de Karpathy: un índice pequeño de páginas curadas supera a un gran corpus de historial en bruto que necesita volver a buscarse cada vez que se necesita.

Por qué importa: La memoria estilo RAG recupera fragmentos y espera que encajen con coherencia en contexto. Una página compilada ya es coherente: un registro de decisiones o un resumen de sesión por derecho propio, legible por un humano, no solo algo consumible en mitad de una recuperación.

Consejo de producción: Esta es también la razón por la que el wiki sigue siendo útil incluso sin ningún LLM configurado: un resumidor basado en reglas sigue produciendo algo utilizable, solo que menos pulido que una página consolidada por un LLM.

3. Traspasos cross-agent

Qué es: La funcionalidad para la que existe el resto de la arquitectura. Sales de un CLI de agente a mitad de tarea, abres otro distinto más tarde en el mismo proyecto, y la nueva sesión recibe un traspaso tipado —preguntas abiertas, siguientes pasos, un resumen de sesión— antes de su primer prompt.

Por qué importa: Esta es la parte que casi ninguna herramienta de memoria comparable aborda directamente. La mayoría se limita al ecosistema de un único proveedor; la matriz de compatibilidad de ai-memory abarca deliberadamente más de veinte CLIs precisamente para que el traspaso no quede limitado a permanecer dentro de las herramientas de una sola empresa.

Consejo de producción: No todos los agentes exponen un verdadero evento de fin de sesión. Para los que no lo hacen, ejecutar ai-memory finalize-session manualmente después de tu último turno es lo que realmente activa el resumen y el traspaso.

4. Workstreams gestionados

Qué es: Una capa opcional encima del sistema base de traspasos. ai-memory run claude, y después ai-memory run codex --yolo, continúa de forma transparente un mismo workstream lógico —reanudación nativa de sesión por harness más un registro portable y consultable de eventos— en lugar de solo un traspaso único en forma de resumen.

Por qué importa: Un resumen compilado de traspaso está bien; la reanudación nativa de sesión con un registro portable completo es mejor cuando la fidelidad a “exactamente lo que ocurrió” importa más que un resumen condensado: la diferencia entre “más o menos donde lo dejaste” y “tu sesión anterior real, continuada”.

Consejo de producción: El modo gestionado actualmente cubre un subconjunto significativo pero acotado de la matriz completa de compatibilidad. Comprueba si tu harness específico está cubierto antes de asumir que ai-memory run funciona en cualquier lugar donde sí funciona el sistema base de traspasos.

5. Recuperación híbrida consciente de autoridad

Qué es: Consultar el wiki combina búsqueda de texto completo (FTS5), coincidencia de entidades contra sustantivos extraídos en el momento de la consolidación y expansión a vecinos del grafo a través de páginas enlazadas, con similitud vectorial como cuarta señal opcional. Antes del truncado, un ajuste acotado favorece reglas mantenidas, decisiones, procedimientos y páginas de gotchas por encima de historiales de sesión puramente episódicos aunque coincidan estrechamente.

Por qué importa: La búsqueda puramente vectorial puede sacar a la superficie una página de sesión semánticamente cercana mientras entierra la decisión vigente real sobre el mismo tema. Ponderar hacia conocimiento curado —sin convertirlo en un filtro absoluto— es un punto medio genuinamente útil.

Consejo de producción: La búsqueda vectorial aquí es aditiva, no fundacional. FTS5 más coincidencia de entidades y vecinos del grafo ya funciona con cero infraestructura de embeddings; añade un proveedor vectorial para mejorar el recuerdo difuso, no porque el sistema lo requiera.

6. LLM como opción voluntaria, no como requisito

Qué es: La captura, la búsqueda y el resumido basado en reglas funcionan sin ningún proveedor LLM configurado. Añadir uno habilita páginas consolidadas por LLM, linting de contradicciones y auto-mejora en segundo plano, pero la usabilidad base no depende de ello.

Por qué importa: Esta es una postura arquitectónica real: la herramienta degrada con elegancia en lugar de volverse inútil en el momento en que falta una API key, y mantiene disponible una vía realmente gratuita y autoalojada.

Consejo de producción: Cuando sí añadas un proveedor, los valores recomendados apuntan a modelos pequeños y rápidos —clase Haiku o mini— porque la consolidación es resumido, no razonamiento difícil. Reserva los modelos más grandes para el propio agente de codificación.

7. Auto-mejora y curación

Qué es: Con un LLM configurado, un programador en segundo plano revisa sesiones recién completadas y propone ediciones al wiki —lecciones duraderas que una sesión enseñó— registradas en un rastro auditable de escrituras pendientes. Un comando curador aparte, sin LLM, ejecuta mantenimiento basado en reglas sobre páginas frías, títulos duplicados y enlaces colgantes.

Por qué importa: Un sistema de memoria que solo crece sin volver a revisar lo que almacenó acumula ruido. Tener tanto un bucle impulsado por LLM de “qué aprendimos” como una pasada barata y determinista de mantenimiento mantiene el wiki útil a lo largo de meses de sesiones acumuladas.

Consejo de producción: La aprobación automática es el valor por defecto, pero require_approval = true mantiene las ediciones propuestas en estado pendiente para revisión humana. Vale la pena activarlo en un proyecto compartido o de larga vida donde una mala edición automática sea costosa de corregir después.

Recorrido de extremo a extremo

Sigue el escenario real alrededor del que esta herramienta está construida:

1. Una sesión de Claude Code se ejecuta durante varias horas sobre un proyecto. Los hooks del ciclo de vida capturan prompts y llamadas a herramientas como observaciones saneadas y acotadas a lo largo del proceso.
2. La sesión termina. ai-memory compila las observaciones relevantes en una página de sesión y crea un traspaso tipado que contiene preguntas abiertas y siguientes pasos, marcado como pendiente.
3. Horas después, Codex se abre en el mismo directorio. Su hook SessionStart se dispara y el servidor encuentra el traspaso pendiente esperando para este proyecto.
4. El traspaso se inyecta antes del primer prompt de Codex: un bloque de “dónde lo dejaste” que cubre las decisiones de arquitectura, lo que se probó y rechazó, y la pregunta abierta específica que nunca se resolvió.
5. Codex continúa el trabajo sin que el desarrollador vuelva a explicar nada que ya hubiera quedado establecido.
6. Si una decisión específica necesita persistir permanentemente en lugar de vivir solo en el resumen de esa sesión —“estandarizamos Postgres para esto”— el desarrollador lo indica, y el agente escribe una página duradera y fijada en el wiki que no desaparecerá por la decadencia normal.
7. Semanas después, en una sesión con un tercer agente completamente distinto, una consulta como “qué decidimos sobre la base de datos hace seis semanas” alcanza esa página de decisión fijada a través del sistema híbrido de recuperación, clasificada por delante de cualquier mención de sesión parecida pero puramente episódica, gracias al ajuste consciente de autoridad.

Casos especiales

Aislamiento por proyecto por construcción. Cada proyecto vive en una ruta indexada por UUID estables en lugar de por un nombre de directorio en bruto, con la identidad del proyecto derivada por defecto del directorio de trabajo actual. Un archivo marcador te permite sobrescribir eso explícitamente, útil para consultoras que gestionan múltiples clientes, monorepos o git worktrees enlazados que deberían compartir o dividir memoria de forma deliberada y no por accidente.

Slots de memoria por operador en servidores compartidos. Cuando se comparte un servidor doméstico o de equipo, una configuración opcional mantiene el propio contexto de trabajo de cada operador autenticado dentro de un espacio de nombres acotado, en capas junto al contexto compartido. Esto es aislamiento de inyección de contexto, no control de acceso: las lecturas y búsquedas exactas siguen siendo de alcance de proyecto completo.

Retroalimentación que reduce la confianza en lugar de borrar. Cuando una página resulta estar desactualizada o ser incorrecta, la retroalimentación reduce al mínimo su prominencia en recuperación y la marca para revisión en lugar de eliminarla. Una reescritura posterior de esa página elimina la marca, preservándola como registro auditable en lugar de borrar silenciosamente el historial.

Escalado y desafíos de producción

La simplicidad operativa es una decisión de diseño real. Un único binario Rust, un directorio de datos, markdown como verdadera fuente de la verdad: la copia de seguridad es rsync o un remoto git, la recuperación de una mala edición de página es restaurar un archivo desde un commit de git, y el conjunto de datos se puede consultar con grep sin cliente de base de datos; una historia operativa significativamente distinta a ejecutar una base de datos vectorial gestionada junto a tus herramientas de agentes.

La seguridad tiene valores por defecto seguros, y el acceso no loopback falla de forma cerrada. Vincular a loopback sin autenticación está bien para un portátil de usuario único; exponer el servidor más allá de eso sin un bearer token es una excepción deliberada y explícita, no algo que funcione silenciosamente. TLS se deja intencionadamente a un reverse proxy en lugar de manejarse internamente.

La calidad de recuperación tiene que mantenerse a medida que el wiki crece a lo largo de meses de sesiones. Precisamente para eso sirve la clasificación consciente de autoridad: sin ella, un año de páginas de sesión episódicas acumuladas enterraría cada vez más las pocas páginas que realmente importan para responder “qué decidimos”.

El coste del LLM permanece desacoplado del coste de tu agente de codificación. Como aquí el trabajo del LLM es consolidación, no razonamiento, ejecutarlo en un modelo barato mantiene bajo el coste operativo de la capa de memoria y en gran medida independiente de lo que estés gastando en el propio agente de codificación.

Ejemplos de código

Poner en marcha el servidor localmente con Docker, a grandes rasgos:

docker run -d --name ai-memory \
    --restart unless-stopped \
    -p 127.0.0.1:49374:49374 \
    -v ai-memory-data:/data \
    -e AI_MEMORY_LLM_PROVIDER=anthropic \
    -e ANTHROPIC_API_KEY=sk-ant-... \
    akitaonrails/ai-memory:latest

Conectar un CLI de agente a él:

ai-memory install-mcp   --client claude-code --apply
ai-memory install-hooks --agent  claude-code --apply

Cambiar de agente a mitad de un workstream con el lanzador gestionado:

ai-memory run claude          # start work in Claude Code
# ...quit, come back later...
ai-memory run codex --yolo    # resume the same workstream in Codex

Consultar el wiki directamente a través de su API JSON de solo lectura:

curl "http://127.0.0.1:49374/api/v1/search?q=database+choice&project=my-app" \
    -H "Authorization: Bearer $AI_MEMORY_AUTH_TOKEN"

Escribir una página de decisión duradera y fijada desde la terminal:

ai-memory write-page \
    --path decisions/0007-db.md \
    --body $'# Standardized on Postgres for this project\n\nRejected MongoDB due to...' \
    --pinned

Errores comunes

Error: tratar la memoria recuperada como instrucciones. Es tentador dejar que una página con alta clasificación dirija directamente el comportamiento de un agente. Solución: el propio diseño de ai-memory trata explícitamente el texto recuperado como evidencia histórica no confiable que nunca adquiere autoridad de nivel de instrucción independientemente de su tier, pin o rank; una protección que vale la pena copiar en cualquier sistema de memoria o RAG que construyas tú mismo.

Error: asumir que necesitas un proveedor LLM para obtener valor de esto. Saltarte por completo la configuración porque aún no has elegido un proveedor. Solución: el modo sin LLM ya te da búsqueda de texto completo, coincidencia de entidades, recuperación por vecinos del grafo y resúmenes basados en reglas; añade un proveedor más adelante específicamente por la calidad de consolidación, no como prerrequisito para empezar.

Error: exponer el servidor más allá de loopback sin autenticación. Suponer que una prueba rápida en LAN es inofensiva. Solución: trata cualquier bind no loopback como algo que requiere un bearer token por defecto, y usa las plantillas proporcionadas de reverse proxy en lugar de omitir TLS en cualquier cosa que vaya más allá de una única máquina de confianza.

Error: esperar que esto reemplace la inteligencia de código en vivo. Preguntarle al wiki de memoria qué hace actualmente una función. Solución: úsalo para decisiones previas, justificación y intentos fallidos; verifica cualquier afirmación histórica sobre código contra el checkout real, y apóyate en una herramienta de inteligencia estructural de código para símbolos, callers y comportamiento actual.

Error: adoptar esto en un proyecto maduro sin bootstrap. Empezar con un wiki completamente vacío en una base de código con meses de historial real. Solución: ejecuta una vez el comando bootstrap, que siembra páginas iniciales a partir del git log, README y documentación para que las sesiones futuras se construyan sobre contexto existente en lugar de partir de cero.

Buenas prácticas de producción

• Configura hooks cross-agent para cada CLI entre los que realmente cambias, no solo para el principal: el valor del traspaso solo se materializa cuando hay más de un proveedor conectado.
• Fija las decisiones que deban sobrevivir a una sola sesión. Las páginas de sesión compiladas automáticamente son un historial útil; las páginas fijadas explícitamente son las que realmente querrás que aparezcan meses después.
• Mantén barato el modelo LLM para consolidación y sepáralo del modelo de tu agente de codificación. Esto es trabajo de resumido, y un modelo pequeño lo maneja bien por una fracción del coste.
• Activa aprobación manual para la auto-mejora en proyectos compartidos o de larga vida. La auditabilidad importa más que la conveniencia una vez que más de una persona depende de que el wiki sea correcto.
• Trata markdown-en-git como tu verdadera estrategia de copia de seguridad, y úsala: una sola página mala está a un git log y una restauración de quedar arreglada, sin tocar el resto del wiki.

Para cerrar

La decisión interesante en ai-memory no es ninguna funcionalidad concreta: es la apuesta hecha dos veces, en dos capas distintas, de que “compilar un resumen coherente” supera a “recuperar fragmentos de historial en bruto”, y de que la memoria debería seguir al desarrollador a través del proveedor de agente que realmente esté usando en lugar de quedar encerrada dentro de las herramientas de una sola empresa. Dado lo fragmentado que ya está el panorama de CLIs de agentes en 2026, apostar por la segunda parte parece menos un extra deseable y más la forma real en que la mayoría de los desarrolladores ya trabaja.

Si has intentado conectar más de un CLI de agente al mismo sistema de memoria, ¿qué es lo que realmente ha funcionado bien en la práctica: los traspasos compilados o el registro portable en bruto de los workstreams gestionados?