{"title":"Memory API","slug":"memory","category":"api","summary":"Riferimento completo per i 22 endpoint memory: memorizzazione, richiamo, ricerca, ricerca semantica, sincronizzazione, audit e altro.","audience":["human","llm"],"tags":["api","memory","crud","search","fts5","semantic"],"difficulty":"intermediate","updated":"2026-06-27","word_count":559,"read_minutes":3,"llm_context":"Auth: Mind Key (Authorization: Bearer mk_xxx OR ?key=mk_xxx)\nALWAYS call GET /memory/recall at session start.\nPOST /memory with same category+key updates the existing memory.\nCategories: identity, preference, fact, project, skill, mistake, context, note, credentials\nPriorities: low, normal, high, critical\nSearch: GET /memory/search?q=... (FTS5 syntax: AND, OR, \"phrases\", prefix*)\nSemantic: GET /memory/semantic-search?q=... (slower, conceptual)\nSync: GET /memory/diff?since=TIMESTAMP (incremental sync)\nExport: GET /memory/mind-export (full JSON dump)\n","lang":"it","translated":true,"requested_lang":"it","content_markdown":"\n# Memory API\n\nLa Memory API è il cuore di Synapse. Fornisce 22 endpoint per memorizzare,\nrecuperare, cercare e gestire memorie strutturate. Tutti gli endpoint richiedono\nuna Mind Key per l'autenticazione.\n\n> [!CRITICAL]\n> **Chiami sempre `GET /memory/recall` all'inizio di ogni sessione.** È\n> l'unico modo per ricostruire il contesto dalle sessioni precedenti.\n\n## Categorie\n\nLe memorie sono organizzate in 8 categorie:\n\n| Categoria | Caso d'uso |\n|----------|----------|\n| `identity` | Nome utente, ruolo, informazioni di contatto, preferenze su se stessi |\n| `preference` | Piaceri, dispiaceri, stile di lavoro, preferenze di comunicazione |\n| `fact` | Fatti verificabili (dettagli di progetto, date, URL) |\n| `project` | Stato del progetto, milestone, architettura |\n| `skill` | Cose in cui l'utente è bravo |\n| `mistake` | Errori passati — da evitare di ripetere |\n| `context` | Contesto rilevante per la sessione |\n| `note` | Note varie |\n\n## Priorità\n\n- `low` — piace da sapere\n- `normal` — predefinita\n- `high` — importante\n- `critical` — da non dimenticare mai (identità utente, info legali)\n\n## Endpoint principali\n\n### GET /memory/recall\n\nRestituisce TUTTE le memorie come testo semplice ottimizzato per LLM. Lo chiami\nall'inizio di ogni sessione.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/memory/recall\n```\n\nRisposta (text/plain):\n\n```\nMind: Michael's Mind\nMemories: 12 total (10 verified)\n\n[001] identity (CRITICAL)\n user_name\n Michael Schäfer\n Tags: person, identity\n\n...\n```\n\n### POST /memory\n\nMemorizza una nuova memoria o aggiorna una esistente (stessa categoria + chiave = aggiornamento).\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/memory \\\n -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"category\": \"fact\",\n \"key\": \"user_name\",\n \"content\": \"The user's name is Michael Schäfer\",\n \"tags\": [\"person\", \"identity\"],\n \"priority\": \"critical\"\n }'\n```\n\nRisposta: `{ \"id\": \"mem_001\", \"status\": \"stored\" }`\n\n### GET /memory\n\nElenca le memorie con filtri opzionali.\n\n```bash\n# All memories (JSON)\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory?limit=50&offset=0\"\n\n# Filter by category\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory?category=project\"\n\n# Filter by tag\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory?tag=docker\"\n```\n\n### PUT /memory/:id\n\nAggiorna una specifica memoria per ID.\n\n```bash\ncurl -X PUT https://synapse.schaefer.zone/memory/mem_001 \\\n -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"content\": \"Updated content\", \"priority\": \"high\"}'\n```\n\n### DELETE /memory/:id\n\nElimina una singola memoria.\n\n```bash\ncurl -X DELETE -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/memory/mem_001\n```\n\n## Endpoint di ricerca\n\n### GET /memory/search\n\nRicerca full-text tramite FTS5.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory/search?q=docker+swarm\"\n```\n\nSintassi FTS5:\n\n- Più parole = AND: `docker swarm`\n- Frase: `\"docker swarm\"`\n- Prefisso: `docker*`\n- Booleano: `docker OR kubernetes`\n- Esclusione: `docker -swarm`\n\n### GET /memory/semantic-search\n\nRicerca concettuale tramite embedding (più lenta di FTS5 ma comprende il significato).\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory/semantic-search?q=container+orchestration\"\n```\n\nRestituisce memorie semanticamente simili alla query, anche se nessuna parola\nchiave corrisponde. Utile per \"trova memorie su X\" dove X è descritto\ndiversamente.\n\n### GET /memory/by-tag\n\nElenca le memorie per tag.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory/by-tag?tag=docker\"\n```\n\n### GET /memory/related/:id\n\nTrova memorie correlate a una specifica memoria (tramite tag condivisi).\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/memory/related/mem_001\n```\n\n## Sync e diff\n\n### GET /memory/diff\n\nSync incrementale — restituisce le memorie modificate da un timestamp.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory/diff?since=1700000000\"\n```\n\nRisposta: `{ \"added\": [...], \"updated\": [...], \"deleted\": [...] }`\n\n### POST /memory/sync\n\nApplica un diff da un'altra istanza (per sync self-hosted).\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/memory/sync \\\n -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"added\": [...], \"updated\": [...], \"deleted\": [...]}'\n```\n\n## Operazioni bulk\n\n### POST /memory/bulk-delete\n\nElimina più memorie per ID.\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/memory/bulk-delete \\\n -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"ids\": [\"mem_001\", \"mem_002\", \"mem_003\"]}'\n```\n\n### POST /memory/embed-batch\n\nGenera embedding per memorie che non li hanno ancora (per ricerca semantica).\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/memory/embed-batch \\\n -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"limit\": 100}'\n```\n\n### GET /memory/embed-batch-status\n\nVerifica l'avanzamento della generazione degli embedding.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/memory/embed-batch-status\n```\n\n## Verifica\n\nLe memorie hanno un flag `verified`. Le memorie salvate dall'agente sono non\nverificate per default (`source=agent`); le memorie salvate dall'umano sono\nverificate (`source=user`).\n\n### POST /memory/verify\n\nContrassegna una memoria come verificata (richiede JWT, non Mind Key).\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/memory/mem_001/verify \\\n -H \"Authorization: Bearer YOUR_JWT\"\n```\n\n### POST /memory/unverify\n\nContrassegna una memoria come non verificata (richiede JWT).\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/memory/mem_001/unverify \\\n -H \"Authorization: Bearer YOUR_JWT\"\n```\n\n### GET /memory/unverified\n\nElenca le memorie in attesa di verifica umana.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory/unverified?limit=100\"\n```\n\n## Statistiche e audit\n\n### GET /memory/stats\n\nStatistiche aggregate per la mente corrente.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/memory/stats\n```\n\nRestituisce: `{ \"total\": 12, \"verified\": 10, \"unverified\": 2, \"by_category\": {...}, \"by_priority\": {...} }`\n\n### GET /memory/audit\n\nLog di audit di tutte le operazioni che modificano lo stato.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory/audit?limit=100&action=store\"\n```\n\n### GET /memory/contradictions\n\nRileva potenziali contraddizioni nelle memorie salvate.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/memory/contradictions\n```\n\n### GET /memory/expiring\n\nElenca le memorie con date di scadenza in avvicinamento.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory/expiring?within=7d\"\n```\n\n## Health ed export\n\n### GET /memory/health\n\nHealth check rapido per il sistema di memoria.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/memory/health\n```\n\n### GET /memory/mind-export\n\nExport JSON completo di tutte le memorie (per backup).\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/memory/mind-export > backup.json\n```\n\n### POST /memory/compact\n\nCompatta memorie simili (auto-riassunto).\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/memory/compact \\\n -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"dry_run\": true}'\n```\n\n## Prossimi passi\n\n- [Quick Start per LLM](/docs/getting-started/quick-start-llm)\n- [Best practice per la memoria](/docs/guides/memory-best-practices)\n- [Ricerca FTS5](/docs/concepts/fts5-search)\n- [Ricerca semantica](/docs/concepts/semantic-search)\n","content_html":"

Memory API

\n

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

\n
**Chiami sempre `GET /memory/recall` all'inizio di ogni sessione.** È\nl'unico modo per ricostruire il contesto dalle sessioni precedenti.

Categorie

\n

Le memorie sono organizzate in 8 categorie:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
CategoriaCaso d'uso
identityNome utente, ruolo, informazioni di contatto, preferenze su se stessi
preferencePiaceri, dispiaceri, stile di lavoro, preferenze di comunicazione
factFatti verificabili (dettagli di progetto, date, URL)
projectStato del progetto, milestone, architettura
skillCose in cui l'utente è bravo
mistakeErrori passati — da evitare di ripetere
contextContesto rilevante per la sessione
noteNote varie
\n

Priorità

\n\n

Endpoint principali

\n

GET /memory/recall

\n

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

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

Risposta (text/plain):

\n
Mind: Michael's Mind\nMemories: 12 total (10 verified)\n\n[001] identity (CRITICAL)\n  user_name\n  Michael Schäfer\n  Tags: person, identity\n\n...

POST /memory

\n

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

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

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

\n

GET /memory

\n

Elenca le memorie con filtri opzionali.

\n
# All memories (JSON)\ncurl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/memory?limit=50&offset=0"\n\n# Filter by category\ncurl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/memory?category=project"\n\n# Filter by tag\ncurl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/memory?tag=docker"

PUT /memory/:id

\n

Aggiorna una specifica memoria per ID.

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

DELETE /memory/:id

\n

Elimina una singola memoria.

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

Endpoint di ricerca

\n

GET /memory/search

\n

Ricerca full-text tramite FTS5.

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

Sintassi FTS5:

\n\n

GET /memory/semantic-search

\n

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

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

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

\n

GET /memory/by-tag

\n

Elenca le memorie per tag.

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

GET /memory/related/:id

\n

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

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

Sync e diff

\n

GET /memory/diff

\n

Sync incrementale — restituisce le memorie modificate da un timestamp.

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

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

\n

POST /memory/sync

\n

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

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

Operazioni bulk

\n

POST /memory/bulk-delete

\n

Elimina più memorie per ID.

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

POST /memory/embed-batch

\n

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

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

GET /memory/embed-batch-status

\n

Verifica l'avanzamento della generazione degli embedding.

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

Verifica

\n

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

\n

POST /memory/verify

\n

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

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

POST /memory/unverify

\n

Contrassegna una memoria come non verificata (richiede JWT).

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

GET /memory/unverified

\n

Elenca le memorie in attesa di verifica umana.

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

Statistiche e audit

\n

GET /memory/stats

\n

Statistiche aggregate per la mente corrente.

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

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

\n

GET /memory/audit

\n

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

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

GET /memory/contradictions

\n

Rileva potenziali contraddizioni nelle memorie salvate.

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

GET /memory/expiring

\n

Elenca le memorie con date di scadenza in avvicinamento.

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

Health ed export

\n

GET /memory/health

\n

Health check rapido per il sistema di memoria.

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

GET /memory/mind-export

\n

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

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

POST /memory/compact

\n

Compatta memorie simili (auto-riassunto).

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

Prossimi passi

\n\n","urls":{"html":"/docs/api/memory","text":"/docs/api/memory?format=text","json":"/docs/api/memory?format=json","llm":"/docs/api/memory?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}