Skip to main content

Memory API

intermediate 🤖 Compatibile con LLM 3 min · 559 parole Aggiornato: 2026-06-27 Italiano

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

Leggi questo articolo come: 📄 Testo semplice ⚡ JSON 🤖 Formato LLM
Lingua: English中文हिन्दीEspañolFrançaisالعربيةPortuguêsРусский日本語DeutschItaliano한국어NederlandsPolskiTürkçeSvenskaTiếng ViệtไทยBahasa IndonesiaУкраїнська

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.

**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.

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).

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.

# 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.

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.

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.

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).

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.

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).

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.

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).

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.

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).

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.

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).

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).

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.

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.

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.

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.

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.

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.

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).

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

POST /memory/compact

Compatta memorie simili (auto-riassunto).

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

← Torna a Riferimento API