# Memory API
SUMMARY: Riferimento completo per i 22 endpoint memory: memorizzazione, richiamo, ricerca, ricerca semantica, sincronizzazione, audit e altro.

KEY CONTEXT:
Auth: Mind Key (Authorization: Bearer mk_xxx OR ?key=mk_xxx)
ALWAYS call GET /memory/recall at session start.
POST /memory with same category+key updates the existing memory.
Categories: identity, preference, fact, project, skill, mistake, context, note, credentials
Priorities: low, normal, high, critical
Search: GET /memory/search?q=... (FTS5 syntax: AND, OR, "phrases", prefix*)
Semantic: GET /memory/semantic-search?q=... (slower, conceptual)
Sync: GET /memory/diff?since=TIMESTAMP (incremental sync)
Export: GET /memory/mind-export (full JSON dump)

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  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 |
|----------|----------|
|  | Nome utente, ruolo, informazioni di contatto, preferenze su se stessi |
|  | Piaceri, dispiaceri, stile di lavoro, preferenze di comunicazione |
|  | Fatti verificabili (dettagli di progetto, date, URL) |
|  | Stato del progetto, milestone, architettura |
|  | Cose in cui l'utente è bravo |
|  | Errori passati — da evitare di ripetere |
|  | Contesto rilevante per la sessione |
|  | Note varie |
Priorità
-  — piace da sapere
-  — predefinita
-  — importante
-  — 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.
[CODE BLOCK]
Risposta (text/plain):
[CODE BLOCK]
POST /memory
Memorizza una nuova memoria o aggiorna una esistente (stessa categoria + chiave = aggiornamento).
[CODE BLOCK]
Risposta: 
GET /memory
Elenca le memorie con filtri opzionali.
[CODE BLOCK]
PUT /memory/:id
Aggiorna una specifica memoria per ID.
[CODE BLOCK]
DELETE /memory/:id
Elimina una singola memoria.
[CODE BLOCK]
Endpoint di ricerca
GET /memory/search
Ricerca full-text tramite FTS5.
[CODE BLOCK]
Sintassi FTS5:
- Più parole = AND: 
- Frase: 
- Prefisso: 
- Booleano: 
- Esclusione: 
GET /memory/semantic-search
Ricerca concettuale tramite embedding (più lenta di FTS5 ma comprende il significato).
[CODE BLOCK]
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.
[CODE BLOCK]
GET /memory/related/:id
Trova memorie correlate a una specifica memoria (tramite tag condivisi).
[CODE BLOCK]
Sync e diff
GET /memory/diff
Sync incrementale — restituisce le memorie modificate da un timestamp.
[CODE BLOCK]
Risposta: 
POST /memory/sync
Applica un diff da un'altra istanza (per sync self-hosted).
[CODE BLOCK]
Operazioni bulk
POST /memory/bulk-delete
Elimina più memorie per ID.
[CODE BLOCK]
POST /memory/embed-batch
Genera embedding per memorie che non li hanno ancora (per ricerca semantica).
[CODE BLOCK]
GET /memory/embed-batch-status
Verifica l'avanzamento della generazione degli embedding.
[CODE BLOCK]
Verifica
Le memorie hanno un flag . Le memorie salvate dall'agente sono non
verificate per default (); le memorie salvate dall'umano sono
verificate ().
POST /memory/verify
Contrassegna una memoria come verificata (richiede JWT, non Mind Key).
[CODE BLOCK]
POST /memory/unverify
Contrassegna una memoria come non verificata (richiede JWT).
[CODE BLOCK]
GET /memory/unverified
Elenca le memorie in attesa di verifica umana.
[CODE BLOCK]
Statistiche e audit
GET /memory/stats
Statistiche aggregate per la mente corrente.
[CODE BLOCK]
Restituisce: 
GET /memory/audit
Log di audit di tutte le operazioni che modificano lo stato.
[CODE BLOCK]
GET /memory/contradictions
Rileva potenziali contraddizioni nelle memorie salvate.
[CODE BLOCK]
GET /memory/expiring
Elenca le memorie con date di scadenza in avvicinamento.
[CODE BLOCK]
Health ed export
GET /memory/health
Health check rapido per il sistema di memoria.
[CODE BLOCK]
GET /memory/mind-export
Export JSON completo di tutte le memorie (per backup).
[CODE BLOCK]
POST /memory/compact
Compatta memorie simili (auto-riassunto).
[CODE BLOCK]
Prossimi passi
- Quick Start per LLM
- Best practice per la memoria
- Ricerca FTS5
- Ricerca semantica