# Spec técnica: Memory layer for agents

**Status:** Draft técnico
**Base:** RFC-memory-layer-agents aprobado
**Owner:** Sebas / personal-agent
**Updated:** 2026-04-22
**Scope:** agents-database + Pi session memory pipeline

## 1. Objetivo

Implementar una capa de memoria jerárquica que:

- capture memoria útil sin inflar ruido
- consolide episodios en conocimiento reusable
- promueva memorias por evidencia y repetición
- recupere por señales híbridas
- mantenga trazabilidad a fuentes originales

## 2. Principios de implementación

1. **No todo se persiste igual.**
2. **La promoción es explícita.**
3. **La evidencia manda sobre la intuición.**
4. **La recencia pesa, pero no decide sola.**
5. **La consolidación es batch, no solo online.**
6. **La memoria de mayor nivel debe ser más escasa y más confiable.**

## 3. Capas de memoria

### 3.1 Raw / episodic
Registro de eventos concretos.

Ejemplos:
- sesiones
- turnos
- tool calls
- resultados
- incidentes

Propósito:
- trazabilidad
- replay
- base para consolidación

### 3.2 Operational
Contexto temporal para ejecución inmediata.

Ejemplos:
- estado de tarea
- últimos N eventos
- variables temporales
- contexto de trabajo actual

Propósito:
- ayudar al agente a seguir la tarea actual
- expirar rápido

### 3.3 Semantic / factual
Hechos estables o semi-estables.

Ejemplos:
- preferencias
- hechos del proyecto
- decisiones
- restricciones

Propósito:
- reutilización en futuras interacciones

### 3.4 Procedural
Cómo ejecutar algo.

Ejemplos:
- runbooks
- comandos
- workflows
- secuencias repetibles

Propósito:
- acelerar ejecución futura
- reducir errores repetidos

### 3.5 Principle / policy
Abstracciones de nivel superior.

Ejemplos:
- reglas de diseño
- principios operativos
- policies

Propósito:
- orientar decisiones futuras
- sintetizar patrones repetidos

## 4. Data model

### 4.1 Campos base obligatorios

- `id`
- `type`
- `scope`
- `title`
- `content`
- `confidence`
- `freshness`
- `source_ref`
- `evidence_ref`
- `metadata`
- `created_at`
- `updated_at`
- `observed_at`
- `status`

### 4.2 Campos recomendados

- `project_id`
- `repo_id`
- `task_id`
- `run_id`
- `url`
- `domain`
- `origin_agent`
- `parent_id`
- `canonical_id`
- `tags`
- `embedding_ref`
- `rank_score`
- `promotion_score`
- `dedup_group_id`
- `expires_at`

### 4.3 Tipos

- `episodic`
- `operational`
- `semantic`
- `procedural`
- `decision`
- `principle`
- `claim`
- `artifact`

### 4.4 Status

- `active`
- `candidate`
- `promoted`
- `merged`
- `superseded`
- `expired`
- `deleted`

### 4.5 Metadata mínima sugerida

```json
{
  "source_kind": "manual|session|job|hook|import",
  "topic": "string",
  "entity_ids": ["..."],
  "signals": {
    "usage_count": 0,
    "dup_count": 0,
    "age_days": 0,
    "evidence_count": 0
  }
}
```

## 5. Scoring model

### 5.1 Scores principales

- `confidence`: qué tan confiable es la memoria
- `freshness`: qué tan vigente es
- `importance`: impacto potencial
- `usage`: frecuencia de uso o recuperación
- `evidence`: cantidad/calidad de respaldo
- `redundancy`: penalización por duplicación

### 5.2 Score de relevancia

Propuesta inicial:

`rank_score = 0.30*semantic_match + 0.20*recency + 0.20*confidence + 0.15*importance + 0.10*usage + 0.05*trust`

Con penalización por redundancia:

`rank_score = rank_score - 0.10*redundancy`

### 5.3 Score de promoción

`promotion_score = 0.30*repetition + 0.20*usage + 0.20*confidence + 0.15*evidence + 0.10*stability + 0.05*impact`

Interpretación:
- si `promotion_score` supera umbral, la memoria pasa a candidata
- si además tiene evidencia y no compite con una memoria canónica, se promueve

## 6. Thresholds iniciales

Valores iniciales para prototipo:

- `candidate_threshold = 0.65`
- `promote_threshold = 0.80`
- `merge_threshold = 0.88`
- `expire_operational_after_hours = 24`
- `expire_raw_after_days = 14`
- `review_principle_after_days = 7`

Notas:
- estos umbrales son arranque, no verdad final
- deben ajustarse con evaluación

## 7. Ingest pipeline

### 7.1 Entrada

Fuentes:
- sesiones
- logs de agente
- tool calls
- notas manuales
- imports de fuentes externas

### 7.2 Normalización

- limpiar texto
- asignar timestamps
- resolver entidades conocidas
- calcular embeddings
- extraer metadata básica

### 7.3 Clasificación

Asignar:
- tipo
- scope
- confidence inicial
- freshness inicial
- source trace

### 7.4 Persistencia

Guardar como:
- episodic si es evento concreto
- operational si sirve al contexto inmediato
- semantic/procedural/decision/principle si ya viene consolidado

## 8. Consolidation jobs

### Job A: TTL sweep

Frecuencia: diaria o cada pocas horas.

Hace:
- expirar operational viejo
- marcar raw vencido si ya fue consolidado
- limpiar basura obvia

Salida:
- `expired`
- `archived`

### Job B: dedup + fusion

Frecuencia: diaria.

Hace:
- agrupar memorias por similitud vectorial
- corroborar con lexical match y metadata
- fusionar duplicados cercanos
- marcar canonical memory

Salida:
- una memoria canónica
- referencias a sus duplicados

### Job C: episodic → semantic consolidation

Frecuencia: diaria o por lote.

Hace:
- detectar episodios repetidos
- extraer patrones estables
- convertirlos en facts, decisions o procedures
- generar candidates

Salida:
- memorias candidatas
- links a evidencia

### Job D: principle extraction

Frecuencia: semanal.

Hace:
- agrupar semantic/procedural/decision memories relacionadas
- sintetizar principios o policies
- exigir evidencia múltiple

Salida:
- principle candidates

### Job E: ranking refresh

Frecuencia: cada consolidación.

Hace:
- recalcular scores
- bajar freshness con tiempo
- ajustar rank por uso y evidencia

## 9. Promotion workflow

### 9.1 States

`active -> candidate -> promoted -> superseded`

### 9.2 Reglas

Una memoria puede promoverse si:
- aparece repetida en más de una fuente confiable
- tiene uso recurrente
- tiene evidencia trazable
- persiste en el tiempo
- no contradice una memoria canónica existente

### 9.3 Superseding

Si una memoria nueva contradice la vieja:
- no reemplazar automáticamente
- crear candidate conflict
- requerir revisión o evidencia superior
- si se confirma, marcar la vieja como `superseded`

### 9.4 Canonicalization

Debe existir un único registro canónico por:
- preferencia estable
- decisión vigente
- principio vigente
- procedimiento vigente

## 10. Retrieval design

Recuperación híbrida con:
- vector search
- lexical/BM25
- filtros de metadata
- recency
- confidence
- importance
- status

Ranking final con prioridad a:
1. exactitud temática
2. canonicidad
3. confianza
4. vigencia
5. evidencia

## 11. Evaluation

### 11.1 Métricas

- precision@k
- recall@k
- duplicate rate
- promotion precision
- stale memory rate
- canonical conflict rate
- usefulness score manual

### 11.2 Tests prácticos

Preguntas de validación:
- ¿la memoria recuperada ayuda a resolver mejor la tarea?
- ¿se recupera menos ruido?
- ¿las decisiones viejas son reemplazadas correctamente?
- ¿hay demasiadas promociones falsas?

### 11.3 Criterio de éxito del prototipo

El prototipo sirve si:
- reduce ruido operativo
- mejora recall de hechos estables
- produce pocas promociones erróneas
- deja trazabilidad clara a fuentes

## 12. Minimal viable implementation

Primer corte:

1. guardar episodios con metadata rica
2. calcular embeddings
3. job batch de dedup
4. job batch de consolidación episodic→semantic
5. ranking simple por score
6. promoción manual asistida por score

No hacer todavía:
- grafo complejo
- abstracción fully automatic sin control
- múltiples subtipos finos por entidad si no agregan valor

## 13. Decisiones asumidas

- La memoria jerárquica vale más que más almacenamiento.
- La promoción necesita evidencia.
- La consolidación debe ser incremental.
- El sistema debe soportar curaduría humana.
- Grafo de entidades queda como extensión, no requisito inicial.

## 14. Open questions para iteración futura

- esquema exacto de índices en agents-database
- mecanismo de embeddings y storage
- UI o API para revisión humana
- grafo sí/no en v1.1
- cómo medir “insight” de forma objetiva

## 15. Next implementation step

Definir el contrato exacto del registro de memoria y el primer job batch:
- shape JSON
- criterio de candidate
- merge rules
- output schema del consolidator