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.