# Agent Memory (memoria del agente)

*Las notas que puedes leer y editar son la verdad. Los índices son una caché que puedes tirar.*

> **Agent Memory** = **notas que puedes leer y editar** + **índices que puedes tirar en cualquier momento**. Cada nota cita sus fuentes; los índices (texto completo, vectoriales, de grafo, esquemas) son solo derivados de las notas; y las tareas de mantenimiento en segundo plano solo **proponen** ediciones y nunca reescriben el diario original.

**AN-07** · Nivel de conformidad: L2 Memory · Grupo: Conocimiento

## El problema

Los frameworks de memoria meten la memoria en bases de datos opacas: no se puede inspeccionar, comparar, migrar ni corregir, borrarla de forma fiable es difícil, y el índice y el modelo de embeddings quedan atados. Y la propia memoria es una superficie de ataque: en un [estudio de 2026](https://arxiv.org/abs/2606.04329), el envenenamiento de la memoria persistente alcanzó una tasa media de éxito del ataque del 50,46 % en dos agentes, y [otro estudio](https://arxiv.org/abs/2607.05189) usó un solo correo cuidadosamente elaborado para tener éxito contra los backends de memoria tanto de sistema de archivos como vectoriales.

Mientras tanto, “qué arquitectura de memoria es la mejor” está lejos de estar resuelto: los benchmarks se contradicen entre sí. Un diseño que no apuesta por ningún algoritmo de recuperación concreto es el que puede sobrevivir a tres años de cambios.

## Cómo funciona

- **Las notas son la verdad.** Markdown con frontmatter YAML: `kind` (episodic, semantic, procedural, preference), `subject`, `sources`, `confidence`, `valid_from`, `valid_to`, `supersedes`, `origin`, `reviewed`.
- **Actualiza, no sobrescribas.** Un hecho nuevo `supersedes` al anterior; el tiempo de validez y el tiempo de registro se mantienen separados, porque los hechos cambian y los benchmarks habituales apenas lo prueban.
- **Los índices son una caché.** BM25 (por ejemplo SQLite FTS5), vectores (pueden coexistir varios) y un grafo opcional; cada derivado lleva su **receta** y sus **entradas**. Cambiar el modelo de embeddings es un recálculo en segundo plano, y el índice antiguo se conserva hasta que el nuevo supere las pruebas de recuperación de referencia.
- **Dos tipos de derivación.** Las deterministas (fragmentación, BM25, embeddings de un modelo fijo) son reproducibles; las generativas (resúmenes de LLM, hechos extraídos) solo se pueden “regenerar y comparar”, así que se marcan con `generated: true` y nunca sirven como única copia.
- **Ruta de escritura.** `nas_remember` escribe una nota (con fuentes) en la rama actual, y la contaminación se hereda. Una nota de una sesión con contaminación `external` va a **cuarentena**, marcada como sin revisar: se puede recuperar pero **no se carga automáticamente** ni entra en `MEMORY.md`.
- **Ruta de lectura.** `nas_recall` = búsqueda, candidatas, una vista con presupuesto y punteros de evidencia, y muestra la fuente y el estado de revisión de cada nota.
- **Tareas de mantenimiento** (de noche o en ratos libres): deduplicar, consolidar episodios en hechos semánticos, señalar contradicciones, retirar hechos obsoletos, reconstruir índices. Las tareas generan propuestas en una rama para que las revise una persona o un agente; **nunca borran el diario original**; se mide la “tasa de arrepentimiento” (la proporción de propuestas que se revierten).
- **Pruebas de recuperación de referencia (golden recall).** Para cada Home, un conjunto de pares “pregunta, nota esperada” que se ejecutan automáticamente cuando cambia el modelo o el indexador.

## Empezar en pequeño

- `memory/notes/*.md` con frontmatter, y SQLite FTS5 para la búsqueda.
- Ejecuta diez preguntas de referencia en CI.
- Los índices vectoriales y las tareas de mantenimiento pueden venir después; acierta primero con la “procedencia” y con que “solo se cargan automáticamente las notas revisadas”.

## Esbozo de la interfaz

Solo ilustrativo. Los nombres de los campos pueden cambiar antes de la especificación v0.3.

*memory/notes/customer-acme.md*

```markdown
---
id: mem_4kq2
kind: semantic
subject: customer/acme
valid_from: 2026-10-02
valid_to: null
confidence: 0.8
origin: agent
reviewed: true
sources:
  - nas://home-box/agents/cleo/journal/2026-10-02.md@9f2c1de#L12-L18
supersedes: [mem_1xa9]
---
Acme renewed for 24 months; the champion moved from Dana to Luis.
```

## Lo que pide la especificación

- Las notas DEBEN ser legibles sin la capa Memory (son archivos normales en Store).
- Cada derivado DEBE llevar su receta y sus entradas; un índice DEBE ser desechable y reconstruible.
- Las notas escritas por una sesión contaminada NO DEBEN cargarse automáticamente antes de revisarse.
- Un hecho nuevo DEBE sustituir a uno antiguo con `supersedes` en lugar de sobrescribirlo.
- Las tareas de mantenimiento DEBEN trabajar en una rama y solo proponer; NO DEBEN borrar el diario original.
- Cada Home DEBERÍA llevar pruebas de recuperación de referencia y ejecutarlas siempre que cambie el modelo o el indexador.

## Lo prestado y lo nuevo

Lo que sigue es todo pensamiento establecido, y la arquitectura de memoria de OpenClaw ya hace etiquetas de procedencia, cuarentena por niveles y propagación de la contaminación durante la consolidación. **Lo nuevo:** OpenClaw lo hace **dentro de un solo runtime**; nosotros proponemos hacerlo **en el almacenamiento compartido** para que cualquier runtime se beneficie, y degradar el índice a una caché desechable para que el algoritmo de recuperación pueda cambiar sin perder memoria.

- [Letta Context Repositories](https://www.letta.com/blog/context-repositories/)
- [Letta: is a filesystem all you need?](https://www.letta.com/blog/benchmarking-ai-agent-memory/)
- [OpenClaw memory architecture](https://docs.openclaw.ai/concepts/memory-architecture)
- [Long-term memory security survey](https://arxiv.org/abs/2604.16548)
- [Graphiti](https://github.com/getzep/graphiti)
- [MemGPT](https://arxiv.org/abs/2310.08560)

## Límites honestos

- Los derivados generativos nunca se pueden reproducir bit a bit.
- Una tarea de mantenimiento puede “endurecer” un error hasta convertirlo en un hecho, por eso solo propone y nunca edita directamente.
- Qué arquitectura de memoria es la mejor sigue sin estar resuelto.

## Preguntas abiertas

- ¿Cuándo debe escribir la memoria el propio agente y cuándo una tarea de mantenimiento?
- ¿Cuál es el estándar de regresión entre versiones de modelos?

## Preguntas

### ¿Por qué archivos y no una base de datos vectorial?

Los archivos son la verdad que puedes leer, editar, comparar y llevarte; un índice vectorial es una caché derivada que puede coexistir en varias versiones y reconstruirse en cualquier momento. El benchmark de Letta mostró que un agente con solo `grep` y herramientas de archivos es competitivo, pero los benchmarks se contradicen entre sí, así que el diseño no apuesta por un único algoritmo de recuperación.

### ¿Cómo se evita el envenenamiento de la memoria?

No se puede garantizar que nunca se escriba nada malo, pero sí acotar las consecuencias: el contenido de fuera lleva la etiqueta `external`; las notas escritas por una sesión contaminada van a cuarentena y no se cargan automáticamente; las fusiones se revisan; y cuando algo sale mal puedes seguir la cadena de procedencia hasta las notas afectadas y revertir.

### ¿Tengo que migrar la memoria al cambiar el modelo de embeddings?

No. Las notas no cambian; solo se recalculan los índices en segundo plano con la nueva receta, y el índice antiguo se conserva hasta que el nuevo supere las pruebas de recuperación de referencia.

## Conceptos relacionados

- [Budgeted Reads (lecturas con presupuesto)](https://agentnas.com/es/concepts/budgeted-reads/): Lee un archivo como esquema, sección, rango de líneas o completo, degradando para ajustarse al presupuesto.
- [Cascade Forget (olvido en cascada)](https://agentnas.com/es/concepts/cascade-forget/): Borra los derivados siguiendo el linaje, trata el historial por clase de retención e informa de lo que no pudo hacer.
- [Trust Labels (etiquetas de confianza)](https://agentnas.com/es/concepts/trust-labels/): Dos etiquetas pequeñas más la contaminación de sesión hacen cumplir la Rule of Two.

---

URL canónica: https://agentnas.com/es/concepts/agent-memory/
Actualizado: 2026-11-11 · Borrador de especificación v0.2 · CC BY 4.0