# Memory API

La Memory API è il cuore di Synapse. Fornisce 22 endpoint per memorizzare,
recuperare, cercare e gestire memorie strutturate. Tutti gli endpoint richiedono
una Mind Key per l'autenticazione.

> [!CRITICAL]
> **Chiami sempre `GET /memory/recall` all'inizio di ogni sessione.** È
> l'unico modo per ricostruire il contesto dalle sessioni precedenti.

## Categorie

Le memorie sono organizzate in 8 categorie:

| Categoria | Caso d'uso |
|----------|----------|
| `identity` | Nome utente, ruolo, informazioni di contatto, preferenze su se stessi |
| `preference` | Piaceri, dispiaceri, stile di lavoro, preferenze di comunicazione |
| `fact` | Fatti verificabili (dettagli di progetto, date, URL) |
| `project` | Stato del progetto, milestone, architettura |
| `skill` | Cose in cui l'utente è bravo |
| `mistake` | Errori passati — da evitare di ripetere |
| `context` | Contesto rilevante per la sessione |
| `note` | Note varie |

## Priorità

- `low` — piace da sapere
- `normal` — predefinita
- `high` — importante
- `critical` — da non dimenticare mai (identità utente, info legali)

## Endpoint principali

### GET /memory/recall

Restituisce TUTTE le memorie come testo semplice ottimizzato per LLM. Lo chiami
all'inizio di ogni sessione.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/recall
```

Risposta (text/plain):

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

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

...
```

### POST /memory

Memorizza una nuova memoria o aggiorna una esistente (stessa categoria + chiave = aggiornamento).

```bash
curl -X POST https://synapse.schaefer.zone/memory \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "fact",
    "key": "user_name",
    "content": "The user's name is Michael Schäfer",
    "tags": ["person", "identity"],
    "priority": "critical"
  }'
```

Risposta: `{ "id": "mem_001", "status": "stored" }`

### GET /memory

Elenca le memorie con filtri opzionali.

```bash
# All memories (JSON)
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory?limit=50&offset=0"

# Filter by category
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory?category=project"

# Filter by tag
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory?tag=docker"
```

### PUT /memory/:id

Aggiorna una specifica memoria per ID.

```bash
curl -X PUT https://synapse.schaefer.zone/memory/mem_001 \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "Updated content", "priority": "high"}'
```

### DELETE /memory/:id

Elimina una singola memoria.

```bash
curl -X DELETE -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/mem_001
```

## Endpoint di ricerca

### GET /memory/search

Ricerca full-text tramite FTS5.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/search?q=docker+swarm"
```

Sintassi FTS5:

- Più parole = AND: `docker swarm`
- Frase: `"docker swarm"`
- Prefisso: `docker*`
- Booleano: `docker OR kubernetes`
- Esclusione: `docker -swarm`

### GET /memory/semantic-search

Ricerca concettuale tramite embedding (più lenta di FTS5 ma comprende il significato).

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/semantic-search?q=container+orchestration"
```

Restituisce memorie semanticamente simili alla query, anche se nessuna parola
chiave corrisponde. Utile per "trova memorie su X" dove X è descritto
diversamente.

### GET /memory/by-tag

Elenca le memorie per tag.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/by-tag?tag=docker"
```

### GET /memory/related/:id

Trova memorie correlate a una specifica memoria (tramite tag condivisi).

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/related/mem_001
```

## Sync e diff

### GET /memory/diff

Sync incrementale — restituisce le memorie modificate da un timestamp.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/diff?since=1700000000"
```

Risposta: `{ "added": [...], "updated": [...], "deleted": [...] }`

### POST /memory/sync

Applica un diff da un'altra istanza (per sync self-hosted).

```bash
curl -X POST https://synapse.schaefer.zone/memory/sync \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"added": [...], "updated": [...], "deleted": [...]}'
```

## Operazioni bulk

### POST /memory/bulk-delete

Elimina più memorie per ID.

```bash
curl -X POST https://synapse.schaefer.zone/memory/bulk-delete \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ids": ["mem_001", "mem_002", "mem_003"]}'
```

### POST /memory/embed-batch

Genera embedding per memorie che non li hanno ancora (per ricerca semantica).

```bash
curl -X POST https://synapse.schaefer.zone/memory/embed-batch \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit": 100}'
```

### GET /memory/embed-batch-status

Verifica l'avanzamento della generazione degli embedding.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/embed-batch-status
```

## Verifica

Le memorie hanno un flag `verified`. Le memorie salvate dall'agente sono non
verificate per default (`source=agent`); le memorie salvate dall'umano sono
verificate (`source=user`).

### POST /memory/verify

Contrassegna una memoria come verificata (richiede JWT, non Mind Key).

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

### POST /memory/unverify

Contrassegna una memoria come non verificata (richiede JWT).

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

### GET /memory/unverified

Elenca le memorie in attesa di verifica umana.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/unverified?limit=100"
```

## Statistiche e audit

### GET /memory/stats

Statistiche aggregate per la mente corrente.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/stats
```

Restituisce: `{ "total": 12, "verified": 10, "unverified": 2, "by_category": {...}, "by_priority": {...} }`

### GET /memory/audit

Log di audit di tutte le operazioni che modificano lo stato.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/audit?limit=100&action=store"
```

### GET /memory/contradictions

Rileva potenziali contraddizioni nelle memorie salvate.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/contradictions
```

### GET /memory/expiring

Elenca le memorie con date di scadenza in avvicinamento.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/expiring?within=7d"
```

## Health ed export

### GET /memory/health

Health check rapido per il sistema di memoria.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/health
```

### GET /memory/mind-export

Export JSON completo di tutte le memorie (per backup).

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/mind-export > backup.json
```

### POST /memory/compact

Compatta memorie simili (auto-riassunto).

```bash
curl -X POST https://synapse.schaefer.zone/memory/compact \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"dry_run": true}'
```

## Prossimi passi

- [Quick Start per LLM](/docs/getting-started/quick-start-llm)
- [Best practice per la memoria](/docs/guides/memory-best-practices)
- [Ricerca FTS5](/docs/concepts/fts5-search)
- [Ricerca semantica](/docs/concepts/semantic-search)