# Agent memory techniques review

> Progreso: borrador vivo. Voy juntando técnicas, clasificando patrones y traduciéndolos a decisiones para agents-database.

## Objetivo

Clasificar las técnicas que usan distintos agentes/sistemas para construir memoria persistente y decidir qué capa falta en nuestro caso: no solo guardar eventos operativos, sino consolidar hechos, preferencias, temas, abstracciones y aprendizajes.

## Estado actual

- [x] Buscar referencias base en agents-database
- [x] Confirmar patrones comunes en la guía de Cosmos DB para agent memory
- [x] Confirmar un ejemplo de consolidación periódica tipo AgentDock
- [ ] Completar taxonomía por técnica
- [ ] Traducir taxonomía a arquitectura para agents-database
- [ ] Proponer roadmap incremental

## Fuentes base y calidad

### Alta confianza / backing fuerte

- Microsoft Learn: "Agent Memory in Azure Cosmos DB for NoSQL"
  - backing: documentación oficial de producto
  - short-term vs long-term memory
  - TTL para corto plazo
  - summary/prune para hilos largos
  - modelos: por turno, por mensaje, por thread
  - retrieval: vector + full-text + filters
  - URL: https://learn.microsoft.com/en-us/azure/cosmos-db/gen-ai/agentic-memories

- AgentDock memory consolidation guide
  - backing: documentación de producto/implementación, pero más opinionada que Microsoft
  - conversión de episodic a semantic por edad
  - dedup por embedding/keyword/metadata/temporal similarity
  - abstracción de más alto nivel
  - estrategias merge / synthesize / abstract
  - URL: https://hub.agentdock.ai/docs/memory/consolidation-guide

- Redis blog: AI Agents memory management
  - backing: vendor blog con ejemplos concretos y arquitectura de producto
  - short-term/long-term separation
  - TTL, summarization, semantic search, dedup ideas
  - URL: https://redis.io/blog/build-smarter-ai-agents-manage-short-term-and-long-term-memory-with-redis/

- Letta / MemGPT home
  - backing: producto real; el home no prueba cada técnica, pero sí que existe el sistema y su foco en memoria persistente
  - estado persistente, memoria larga, aprendizaje continuo
  - URL: https://memgpt.ai

### Baja confianza / revisar antes de usar como fuente

- Anthropic memory URL usada antes
  - la URL actual devolvió 404 / not found
  - no la tomo como fuente válida sin localizar la página correcta
  - URL: https://docs.anthropic.com/en/docs/build-with-claude/memory

- docs.zep.dev
  - no resolvió; no usar sin URL actualizada

### Lectura

- Las fuentes con más backing describen patrones de almacenamiento/retrieval y compaction.
- Las fuentes más débiles suelen meter "insights" o "consolidation" como idea de producto, pero sin detallar cómo medir calidad, verdad o utilidad.
- Para tu objetivo, lo valioso es quedarte con lo que tiene mecanismo explícito: TTL, summaries, dedup, hierarchical rollups, hybrid retrieval, source trace.

## Taxonomía de técnicas

### 1) Captura cruda
Memoria como log de eventos.

- guardar cada turno, mensaje, tool call, resultado
- bueno para trazabilidad y replay
- malo si no se compacta

### 2) Memoria de ventana corta
Contexto reciente para ejecución actual.

- últimos N turnos
- TTL por tiempo
- se descarta o se resume
- suele ser la capa más barata y útil para el prompt inmediato

### 3) Resumen acumulativo
Compresión de una secuencia en un texto menor.

- thread summary
- rolling summary
- chunk summary
- útil para continuidad sin cargar todo el historial

### 4) Extracción estructurada
Pasar texto libre a slots o hechos.

- preferencias del usuario
- entidades
- decisiones
- objetivos
- restricciones
- estado de proyecto

### 5) Consolidación episódica → semántica
Transformar experiencias puntuales en conocimiento reusable.

- de "pasó esto" a "esto suele ser verdad"
- evita guardar solo ruido operativo
- requiere umbral de edad/uso/importancia

### 6) Deduplicación y fusión
Unificar memorias parecidas.

- similitud semántica
- similitud lexical
- mismas entidades/metadata
- misma ventana temporal
- fusión por score/recencia/credibilidad

### 7) Abstracción jerárquica
Construir niveles superiores.

- hechos → patrones → principios → policies
- sesiones → temas → iniciativas → objetivos
- ideal para insights y memoria de alto valor

### 8) Memoria con scoring/relevancia
No todo se guarda o se muestra igual.

- relevance score
- confidence score
- freshness/decay
- importance score
- access frequency
- source trust

### 9) Memoria por capa o dominio
Separar tipos.

- operativo
- factual
- preferencial
- procedural
- project-level
- org-level
- policy/decision log

### 10) Recuperación híbrida
Buscar con más de una señal.

- vector search
- full-text
- filtros por metadata
- recencia
- grafo/relaciones si aplica

### 11) Refinamiento por reflexión
El agente analiza su propia experiencia.

- post-task reflection
- lessons learned
- what failed / what worked
- resúmenes de sesiones
- inferencias de estrategias

### 12) Memoria procedimental
Guardar cómo hacer cosas.

- workflows
- playbooks
- tool-use patterns
- comandos
- decisiones operativas repetibles

### 13) Memoria episódica
Registro de eventos concretos.

- conversación
- sesión
- incidente
- interacción con herramienta

### 14) Memoria semántica
Conocimiento generalizado.

- preferencias estables
- hechos del proyecto
- reglas de negocio
- relaciones entre conceptos

### 15) Memoria de entidad/grafo
Persistir relaciones entre cosas.

- persona ↔ preferencia
- proyecto ↔ decisión
- herramienta ↔ uso frecuente
- tema ↔ subtema

## Lectura práctica

La mayoría de sistemas están combinando 5 capas:

1. log crudo
2. ventana corta
3. resumen
4. extracción estructurada
5. consolidación semántica / abstracta

Lo que suele faltar, y creo que también falta acá, es la capa 4.5–5.5:

- detección de repetición
- fusión de memorias cercanas
- promoción de patrones a nivel superior
- generación de "claims" o "principios" reutilizables
- gestión explícita de confianza y vencimiento

## Hipótesis para agents-database

Podría evolucionar a un pipeline de tres planos:

### Plano A: ingestión
Guardar todo lo útil como episodio o fact.

### Plano B: consolidación
Jobs periódicos que:

- agrupan memorias similares
- eliminan duplicados
- resumen threads largos
- extraen hechos y preferencias
- elevan patrones a decisiones / principios

### Plano C: curaduría
Memorias de nivel superior con:

- confidence
- evidence links
- source trace
- freshness/decay
- scope
- owner

## Clasificación fina

| Técnica | Problema que resuelve | Señal principal | Salida típica |
|---|---|---|---|
| Log crudo | No perder contexto | recencia, trazabilidad | evento/turno |
| Ventana corta | Continuidad inmediata | TTL, N últimos | prompt state |
| Resumen | Reducir tokens | compaction | summary |
| Extracción estructurada | Convertir texto a hechos | NER, regex, LLM extraction | fact/slot |
| Consolidación episódica→semántica | Elevar valor | edad + frecuencia + utilidad | semantic memory |
| Dedup/fusión | Evitar ruido repetido | similitud vectorial + lexical + metadata | merged memory |
| Abstracción | Crear insights | clustering + synthesis | principle / policy |
| Scoring/relevancia | Ordenar lo importante | importance + trust + freshness | rank score |
| Memoria por dominio | Separar usos | scope/type | typed store |
| Recuperación híbrida | Mejor recall | vector + BM25 + filters | ranked hits |
| Reflexión | Capturar aprendizaje | post-task analysis | lesson learned |
| Procedural | Guardar cómo hacer | repeatability | playbook |
| Episodic | Guardar qué pasó | event sequence | session record |
| Semantic | Guardar qué significa | generalization | fact/claim |
| Graph/entity | Guardar relaciones | links between entities | graph edge/node |

## Qué falta en agents-database hoy

1. **Promoción de nivel**: pasar de episodio a fact, y de fact a principle.
2. **Consolidación batch**: jobs que agrupen, resuman y fusionen.
3. **Jerarquía explícita**: memory types con semántica clara, no solo `operativa`.
4. **Evidencia y trazabilidad**: cada insight tiene que apuntar a sus fuentes.
5. **Decaimiento**: relevance/freshness/TTL distintos por tipo.
6. **Curaduría humana o semi-automática**: para decisiones de alto valor.

## Próximo paso

Voy a cerrar una propuesta de arquitectura para agents-database con:

- tipos de memoria
- jobs de consolidación
- reglas de promoción
- señales de ranking
- esquema mínimo de datos

> Comentario de progreso: ya está claro que el salto de valor no es "más memoria", sino "memoria con promoción de nivel".