# Il modello di memoria

Il modello di memoria di Synapse è progettato per agenti LLM — sufficientemente
strutturato per richiamo affidabile, sufficientemente flessibile per qualsiasi
dominio.

## Anatomia di 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..."
}
```

## Campi

| Campo | Tipo | Obbligatorio | Descrizione |
|-------|------|----------|-------------|
| `id` | string | auto | ID univoco (mem_xxx) |
| `category` | enum | ✅ | Una delle 8 categorie |
| `key` | string | ✅ | Identificatore stabile (usato per gli aggiornamenti) |
| `content` | string | ✅ | Il contenuto della memoria (qualsiasi testo) |
| `tags` | string[] | – | Per ricerca e filtraggio |
| `priority` | enum | – | low, normal, high, critical (predefinito: normal) |
| `source` | enum | auto | user, agent (chi l'ha salvata) |
| `verified` | bool | auto | Un umano l'ha verificata? |
| `confidence` | float | – | 0.0 a 1.0 (predefinito: 1.0 per user, 0.7 per agent) |
| `expires_at` | timestamp | – | Quando dimenticare questa memoria |
| `mind_id` | string | auto | Quale mente la possiede |
| `created_at` | timestamp | auto | Prima memorizzazione |
| `updated_at` | timestamp | auto | Ultima modifica |

## Categorie

Otto categorie coprono i casi d'uso comuni degli agenti LLM:

| Categoria | Scopo | Contenuto di esempio |
|----------|---------|-----------------|
| `identity` | Chi è l'utente | "User is Michael Schäfer, software engineer in Berlin" |
| `preference` | Preferenze utente | "Prefers concise technical responses" |
| `fact` | Fatti verificabili | "Office is in Berlin, timezone Europe/Berlin" |
| `project` | Stato del progetto | "Synapse v1.5.0 deployed, working on v1.6.0 docs" |
| `skill` | Competenze dell'utente | "Advanced Python, 10+ years" |
| `mistake` | Errori passati | "Forgot to bump npm version — CI failed" |
| `context` | Contesto di sessione | "Currently reviewing PR #42" |
| `note` | Note varie | "Try Redis for caching next sprint" |

## Chiavi: identificatori stabili

Il campo `key` è critico — è come aggiorna le memorie senza creare duplicati.

```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")
```

**Regole delle chiavi:**

- Devono essere uniche all'interno di (category, mind)
- Usi `snake_case`
- Prefissi con categoria per chiarezza: `preference_communication`, `mistake_npm_version`
- Le mantenga stabili — non cambi le chiavi dopo la creazione

## Tag: per la ricerca

I tag abilitano filtraggio e ricerca veloce:

```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
```

**Best practice per i tag:**

- 2-5 tag per memoria (non esageri)
- Minuscolo per consistenza
- Usi nomi di progetto, argomenti, tecnologie
- I tag sono case-insensitive

## Livelli di priorità

| Priorità | Quando usarla | Comportamento di richiamo |
|----------|-------------|-----------------|
| `critical` | Identità, legale, irreversibile | Sempre in cima al richiamo |
| `high` | Progetti attivi, preferenze chiave | In evidenza nel richiamo |
| `normal` | Maggior parte delle memorie (predefinito) | Ordine di richiamo standard |
| `low` | Effimero, piace-da-sapere | Potrebbe essere riassunto |

`/memory/recall` ordina per priorità (critical prima), poi per recency.

## Sorgente: user vs agent

Le memorie sono contrassegnate con `source`:

- `user` — salvate da un umano (tramite JWT o UI umana)
- `agent` — salvate da un agente LLM (tramite Mind Key)

Questo influenza:

- **Verifica**: le memorie `user` sono auto-verificate, quelle `agent` no
- **Confidenza**: `user` predefinito a 1.0, `agent` a 0.7
- **Richiamo**: `/memory/recall` contrassegna le memorie non verificate con "(unverified)"

> [!NOTE]
> Tratti le memorie con sorgente `agent` con scetticismo appropriato. Potrebbero
> essere dedotte o assunte anziché dichiarate direttamente dall'utente.

## Verifica

Il flag `verified` indica che un umano ha confermato la memoria:

- memorie `user`: auto-verificate (`true`)
- memorie `agent`: non verificate per default (`false`)

Verifichi le memorie tramite:

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

> [!NOTE]
> La verifica richiede JWT (auth umana), non Mind Key (auth agente). Questo
> garantisce che solo gli umani possano contrassegnare le memorie come verificate.

## Confidenza

Il campo `confidence` (0.0 a 1.0) indica quanto è affidabile la memoria:

- 1.0 — dichiarata direttamente dall'utente
- 0.7 — dedotta dall'agente
- 0.5 — incerta, necessita verifica
- 0.0 — esplicitamente dubitata

Imposti la confidenza durante la memorizzazione:

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

## Scadenza

Imposti `expires_at` per memorie time-sensitive:

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

Le memorie scadute non vengono restituite da `/memory/recall` (ma esistono
ancora nel DB). Usi `/memory/expiring?within=7d` per vedere le memorie in
scadenza prossima.

## Ciclo di vita della memoria

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

## Comportamento di richiamo

`GET /memory/recall` restituisce un riassunto in testo semplice ottimizzato per
il contesto 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

...
```

- Ordinate per priorità (critical → low), poi per recency
- Le memorie non verificate sono contrassegnate con `[unverified]`
- Tag inclusi per contesto
- Testo semplice (nessun parsing JSON necessario)

## Prossimi passi

- [Memory API](/docs/api/memory)
- [Best practice per la memoria](/docs/guides/memory-best-practices)
- [Ricerca FTS5](/docs/concepts/fts5-search)