# RFC: Memory layer for agents

**Status:** Draft
**Owner:** Sebas / personal-agent
**Updated:** 2026-04-22
**Scope:** agents-database + Pi session memory pipeline

## 1. Problem

Hoy `agents-database` guarda memoria útil, pero la mayor parte queda en nivel operativo:

- eventos
- sesiones
- notas puntuales
- claims aislados

Falta una capa que convierta ese material en conocimiento reusable de mayor valor:

- preferencias estables
- hechos consolidados
- patrones repetidos
- decisiones
- principios
- procedimientos
- insights con evidencia

## 2. Objetivo

Diseñar una capa de memoria para agentes que no solo almacene, sino que:

1. **Capture** lo relevante
2. **Consolide** lo repetido
3. **Promueva** episodios a semántica
4. **Abstraiga** a nivel patrón/principio
5. **Permita recuperación híbrida** con trazabilidad

## 3. Principio de diseño

No guardar “más memoria”.
Guardar **mejor memoria**, con niveles y promoción explícita.

## 4. Fuentes y backing

### Fuentes con backing fuerte

- Microsoft Learn: agentic memories en Cosmos DB
  - short-term vs long-term
  - TTL
  - summary/prune
  - one turn / one response / one thread patterns
  - hybrid retrieval

- Redis blog sobre memory management
  - separación short/long-term
  - TTL
  - summarization
  - semantic search
  - dedup ideas

- AgentDock consolidation guide
  - episodic → semantic
  - dedup por embedding + keywords + metadata + tiempo
  - merge / synthesize / abstract

- Letta / MemGPT
  - sistema real enfocado en memoria persistente

### Fuentes débiles o a revisar

- URLs de docs que devolvieron 404
- páginas de marketing sin mecanismo explícito

## 5. Taxonomía propuesta

### 5.1 Episodic
Registro de eventos concretos.

Ejemplos:
- sesión
- interacción
- tool call
- incidente

### 5.2 Operational
Contexto útil para ejecución inmediata.

Ejemplos:
- estado actual
- últimos N turnos
- variables temporales

### 5.3 Factual / Semantic
Hechos relativamente estables.

Ejemplos:
- “Sebas prefiere respuestas cortas”
- “Este repo es la fuente de verdad”
- “Nginx publica /mnt”

### 5.4 Procedural
Cómo hacer algo.

Ejemplos:
- runbooks
- comandos
- workflows
- secuencias repetibles

### 5.5 Decision
Decisiones tomadas y su motivo.

Ejemplos:
- “usar agents-database como memoria durable”
- “mantener legacy sqlite solo como transición”

### 5.6 Insight / Principle
Síntesis de nivel superior.

Ejemplos:
- “No todo lo recordado merece persistir”
- “Promover solo cuando hay repetición + utilidad + evidencia”

## 6. Pipeline propuesto

### 6.1 Ingest
Captura de memoria desde sesiones, jobs y hooks.

### 6.2 Classify
Asignar tipo, scope, confidence, freshness y source trace.

### 6.3 Consolidate
Jobs batch que:

- deduplican
- agrupan por tema
- resúmen threads largos
- detectan repetición
- extraen hechos/preferencias/decisiones

### 6.4 Promote
Mover memoria entre niveles:

- episodic → semantic
- semantic → principle
- operational → durable if repeated / important

### 6.5 Retrieve
Búsqueda híbrida:

- vector
- lexical
- metadata filters
- recency
- trust/confidence

## 7. Reglas de promoción

Promover solo si cumple una o más:

- repetición observada
- uso frecuente
- impacto alto
- confianza suficiente
- evidencia trazable
- estabilidad temporal

No promover si:

- es ruido operativo
- es una hipótesis no verificada
- es demasiado situacional

## 8. Campos mínimos por memoria

- `type`
- `scope`
- `title`
- `content`
- `confidence`
- `freshness`
- `source_ref`
- `evidence_ref`
- `metadata`

Campos recomendados:

- `project_id`
- `repo_id`
- `task_id`
- `run_id`
- `url`
- `domain`
- `origin_agent`

## 9. Anti-patrones

- guardar todo sin consolidar
- mezclar hechos con ruido operativo
- no distinguir confidence de freshness
- no guardar evidencia
- usar una sola capa para todo
- convertir cualquier reflexión en “verdad”

## 10. Decisiones abiertas

- taxonomía final de tipos
- umbrales de promoción
- schedule de consolidación
- estrategia de ranking
- formato de evidencia
- curaduría humana vs automática

## 11. Estado del análisis

### Hecho hoy

- Sí existen patrones reales y repetidos en sistemas de memoria de agentes.
- Los más sólidos usan TTL, summaries, dedup, hybrid retrieval y separación short/long-term.
- Lo que más valor agrega no es la cantidad, sino la **promoción jerárquica con evidencia**.

### Lo que falta validar

- si conviene persistir grafo de entidades
- si la abstracción debe ser automática o semi-manual
- cómo medir “insight útil” vs “resumen lindo pero inútil”

## 12. Próximos pasos

1. terminar taxonomía fina por técnica
2. convertirla en esquema de datos para `agents-database`
3. definir jobs de consolidación
4. definir señales de ranking y promoción
5. implementar el primer batch job

## 13. Progress log

- 2026-04-22: arrancó investigación; fuentes base Microsoft + AgentDock + Redis + Letta.
- 2026-04-22: descartadas fuentes rotas o flojas como referencia principal.
- 2026-04-22: se validó que el foco útil es promoción de nivel, no solo logging.
- 2026-04-22: se corrigió nginx para servir HTML correctamente desde `/mnt`.