# El modelo de memoria

El modelo de memoria de Synapse está diseñado para agentes LLM — lo
suficientemente estructurado para recall fiable, lo suficientemente flexible
para cualquier dominio.

## Anatomía de una memoria

```json
{
  "id": "mem_abc123",
  "category": "project",
  "key": "project_synapse_status",
  "content": "Synapse v1.5.0 deployed on vps1. CI green.",
  "tags": ["synapse", "deployment", "v1.5.0"],
  "priority": "high",
  "source": "agent",
  "verified": false,
  "confidence": 0.85,
  "expires_at": null,
  "mind_id": "m_xyz789",
  "created_at": "2026-06-27T...",
  "updated_at": "2026-06-27T..."
}
```

## Campos

| Campo | Tipo | Obligatorio | Descripción |
|-------|------|----------|-------------|
| `id` | string | auto | ID único (mem_xxx) |
| `category` | enum | ✅ | Una de 8 categorías |
| `key` | string | ✅ | Identificador estable (usado para actualizaciones) |
| `content` | string | ✅ | El contenido de la memoria (cualquier texto) |
| `tags` | string[] | – | Para búsqueda y filtrado |
| `priority` | enum | – | low, normal, high, critical (predeterminado: normal) |
| `source` | enum | auto | user, agent (quién la almacenó) |
| `verified` | bool | auto | ¿La ha verificado un humano? |
| `confidence` | float | – | 0.0 a 1.0 (predeterminado: 1.0 para user, 0.7 para agent) |
| `expires_at` | timestamp | – | Cuándo olvidar esta memoria |
| `mind_id` | string | auto | A qué mind pertenece |
| `created_at` | timestamp | auto | Primera vez almacenada |
| `updated_at` | timestamp | auto | Última modificación |

## Categorías

Ocho categorías cubren los casos de uso comunes de agentes LLM:

| Categoría | Propósito | Contenido de ejemplo |
|----------|---------|-----------------|
| `identity` | Quién es el usuario | "User is Michael Schäfer, software engineer in Berlin" |
| `preference` | Preferencias del usuario | "Prefers concise technical responses" |
| `fact` | Hechos verificables | "Office is in Berlin, timezone Europe/Berlin" |
| `project` | Estado del proyecto | "Synapse v1.5.0 deployed, working on v1.6.0 docs" |
| `skill` | Habilidades del usuario | "Advanced Python, 10+ years" |
| `mistake` | Errores pasados | "Forgot to bump npm version — CI failed" |
| `context` | Contexto de sesión | "Currently reviewing PR #42" |
| `note` | Notas varias | "Try Redis for caching next sprint" |

## Claves: identificadores estables

El campo `key` es crítico — es la forma de actualizar memorias sin crear
duplicados.

```python
# First store
store("project", "project_synapse_status", "v1.4.0 deployed", priority="high")

# Update with same key (overwrites, doesn't duplicate)
store("project", "project_synapse_status", "v1.5.0 deployed", priority="high")
```

**Reglas de key:**

- Debe ser única dentro de (categoría, mind)
- Use `snake_case`
- Prefije con la categoría para claridad: `preference_communication`, `mistake_npm_version`
- Manténgala estable — no cambie las keys tras la creación

## Etiquetas: para búsqueda

Las etiquetas permiten filtrado y búsqueda rápida:

```bash
# Find all memories with tag "docker"
GET /memory/by-tag?tag=docker

# FTS5 search within tagged subset
GET /memory/search?q=swarm&tag=docker
```

**Mejores prácticas de etiquetado:**

- 2-5 etiquetas por memoria (no etiquete en exceso)
- Minúsculas para consistencia
- Use nombres de proyecto, temas, tecnologías
- Las etiquetas son insensibles a mayúsculas/minúsculas

## Niveles de prioridad

| Prioridad | Cuándo usarla | Comportamiento de recall |
|----------|-------------|-----------------|
| `critical` | Identidad, legal, irreversible | Siempre al inicio del recall |
| `high` | Proyectos activos, preferencias clave | Destacada en el recall |
| `normal` | La mayoría de memorias (predeterminado) | Orden de recall estándar |
| `low` | Efímera, bueno saberlo | Puede resumirse |

`/memory/recall` ordena por prioridad (critical primero), luego por recencia.

## Origen: usuario vs agente

Las memorias se etiquetan con `source`:

- `user` — almacenada por un humano (vía JWT o interfaz humana)
- `agent` — almacenada por un agente LLM (vía Mind Key)

Esto afecta:

- **Verificación**: las memorias `user` se auto-verifican, las `agent` no
- **Confianza**: `user` por defecto a 1.0, `agent` a 0.7
- **Recall**: `/memory/recall` marca las memorias no verificadas con "(unverified)"

> [!NOTE]
> Trate las memorias con origen `agent` con el escepticismo apropiado. Pueden
> estar inferidas o asumidas en lugar de haber sido declaradas directamente por
> el usuario.

## Verificación

El flag `verified` indica que un humano ha confirmado la memoria:

- memorias `user`: auto-verificadas (`true`)
- memorias `agent`: por defecto no verificadas (`false`)

Verifique memorias vía:

```bash
curl -X POST https://synapse.schaefer.zone/memory/mem_001/verify \
  -H "Authorization: Bearer YOUR_JWT"
```

> [!NOTE]
> La verificación requiere JWT (auth humana), no Mind Key (auth de agente).
> Esto garantiza que solo los humanos puedan marcar memorias como verificadas.

## Confianza

El campo `confidence` (0.0 a 1.0) indica cuán fiable es la memoria:

- 1.0 — declarada directamente por el usuario
- 0.7 — inferida por el agente
- 0.5 — incierta, necesita verificación
- 0.0 — explícitamente dudosa

Establezca la confianza al almacenar:

```json
{
  "category": "preference",
  "key": "prefers_dark_mode",
  "content": "User seems to prefer dark mode (based on their IDE screenshots)",
  "confidence": 0.5,
  "source": "agent"
}
```

## Expiración

Establezca `expires_at` para memorias sensibles al tiempo:

```json
{
  "category": "context",
  "key": "current_meeting_topic",
  "content": "Discussing Q3 roadmap",
  "expires_at": "2026-06-28T00:00:00Z"
}
```

Las memorias expiradas no se devuelven en `/memory/recall` (pero siguen
existentes en la BD). Use `/memory/expiring?within=7d` para ver memorias que
expiran pronto.

## Ciclo de vida de una memoria

```
                  ┌─────────────────┐
                  │     Create      │
                  │  POST /memory   │
                  └────────┬────────┘
                           │
                           ▼
                  ┌─────────────────┐
                  │     Active      │ ◀──── PUT /memory/:id (update)
                  │  (in recall)    │
                  └────────┬────────┘
                           │
              ┌────────────┼────────────┐
              │            │            │
              ▼            ▼            ▼
        ┌──────────┐ ┌──────────┐ ┌──────────┐
        │ Expired  │ │ Verified │ │ Deleted  │
        │ (in DB)  │ │ (flag)   │ │ (gone)   │
        └──────────┘ └──────────┘ └──────────┘
```

## Comportamiento de recall

`GET /memory/recall` devuelve un resumen en texto plano optimizado para el
contexto del LLM:

```
Mind: Michael's Mind
Memories: 12 total (10 verified, 2 unverified)

[001] identity (CRITICAL) [verified]
  user_name
  Michael Schäfer
  Tags: person, identity

[002] preference (HIGH) [verified]
  communication_style
  Prefers concise technical responses
  Tags: communication

[003] project (HIGH) [unverified]
  synapse_status
  v1.5.0 deployed, working on v1.6.0 docs
  Tags: synapse, deployment

...
```

- Ordenado por prioridad (critical → low), luego por recencia
- Las memorias no verificadas se marcan con `[unverified]`
- Etiquetas incluidas para contexto
- Texto plano (no se necesita parsing JSON)

## Próximos pasos

- [API de Memory](/docs/api/memory)
- [Mejores prácticas de memoria](/docs/guides/memory-best-practices)
- [Búsqueda FTS5](/docs/concepts/fts5-search)