# DOCUMENTAZIONE SYNAPSE — Riferimento completo
# Generato: 2026-07-18T06:14:09.383Z
# Totale articoli: 47
Questo documento contiene la documentazione completa dell'API di Synapse.
Base URL: https://synapse.schaefer.zone
Language: it
========================================================================
## CATEGORIA: PER INIZIARE
Tutto ciò che ti serve per iniziare con Synapse.
────────────────────────────────────────────────────────────
# Autenticazione e Mind Key
SUMMARY: Come funziona l'autenticazione di Synapse: Mind Key per agenti, JWT per umani, ?key= per strumenti solo-URL.
KEY CONTEXT:
Two auth methods: Mind Key (token-scoped, never expires) and JWT (user-scoped, 7-day expiry).
Mind Key: Authorization: Bearer mk_xxx OR ?key=mk_xxx (60 req/min limit on query)
JWT: Authorization: Bearer eyJ... (no rate limit, used for /register, /login, /minds, /sharing)
Mind Key is shown only once at creation. Store it permanently.
Each mind has exactly one Mind Key. Multiple minds = multiple keys.
Autenticazione e Mind Key
Synapse usa due metodi di autenticazione, ciascuno ottimizzato per un caso
d'uso diverso. Comprendere la differenza è essenziale per costruire
integrazioni affidabili.
Due metodi di auth
| Metodo | Caso d'uso | Rate limit | Scadenza |
|--------|----------|------------|--------|
| Mind Key | Agenti LLM, strumenti automatizzati | Nessuno (header) / 60 min (query) | Mai |
| JWT | UI human-facing, operazioni account | Nessuno | 7 giorni |
Mind Key (per agenti)
Una Mind Key è un token API con scope tenant. Autentica i dati di una singola
mente (memorie, attività, chat, script, ecc.). La usi per:
- Agenti LLM che chiamano l'API
- Script di automazione in background
- Configurazione del server MCP
- Qualsiasi integrazione long-lived
Autenticazione tramite header (consigliata)
[CODE BLOCK]
Parametro query (per strumenti solo-URL)
[CODE BLOCK]
> [!WARNING]
> Il parametro query è limitato a 60 richieste al minuto.
> L'header Bearer non ha rate limit. Usi l'header quando il suo client
> supporta header personalizzati.
Creare una Mind Key
[CODE BLOCK]
La risposta include — la salvi immediatamente, viene mostrata
una sola volta.
Elencare le sue menti
[CODE BLOCK]
Eliminare una mente (irreversibile!)
[CODE BLOCK]
JWT (per umani)
I JWT autenticano l'account utente, non una specifica mente. Li usi per:
- Registrazione e login dell'account
- Creare / elencare / eliminare menti
- Condividere menti con altri utenti
- Gestione delle sottoscrizioni Web Push
Registrazione
[CODE BLOCK]
Restituisce:
Login
[CODE BLOCK]
Restituisce:
Scadenza del JWT
I JWT scadono dopo 7 giorni. Quando un JWT scade, chiami semplicemente
nuovamente per ottenerne uno nuovo. La Mind Key non scade mai, quindi
le integrazioni agente esistenti continuano a funzionare.
Best practice di sicurezza
> [!CRITICAL]
> - Non committi mai le Mind Key su git. Usi variabili di ambiente.
> - Non logghi mai le Mind Key. Le mascheri nei log ().
> - Roti le chiavi se sospetta una leak (elimini la mente, ne crei una nuova).
> - Usi una mente per progetto per limitare il raggio d'azione se una chiave leaka.
Modello con variabili di ambiente
[CODE BLOCK]
[CODE BLOCK]
Configurazione del server MCP
[CODE BLOCK]
Modello multi-mente
Ogni utente può avere menti multiple. Modelli comuni:
| Nome mente | Scopo |
|-----------|---------|
| | Memorie relative al lavoro |
| | Preferenze personali, famiglia |
| | Contesto di progetto specifico |
| | Avanzamento dell'apprendimento |
| | Fallback generico |
Usi Mind Key diverse per sessioni LLM diverse per mantenere i contesti
isolati.
Limiti di traffico
| Metodo di auth | Limite | Ambito |
|-------------|-------|-------|
| Mind Key (header) | Nessuno | Per-mente |
| Mind Key (?key=) | 60/min | Per-IP |
| JWT (header) | Nessuno | Per-utente |
| Endpoint pubblici | Nessuno | Globale |
Gli header di rate limit (, ,
) sono inclusi nelle risposte quando applicabile.
Prossimi passi
- Mind Key vs JWT — quando usare quale
- Memory API — cosa può fare con una Mind Key
- API User — gestione account con JWT
────────────────────────────────────────────────────────────
# Mind Key vs JWT — quando usare quale?
SUMMARY: Guida decisionale: Mind Key per accesso dati agente, JWT per gestione account.
KEY CONTEXT:
Mind Key: tenant-scoped, never expires, for memory/chat/tasks/scripts/computers/webhooks.
JWT: user-scoped, 7-day expiry, for /register, /login, /minds (CRUD), /sharing, /push.
Simple rule: if it touches a single mind's data → Mind Key. If it manages the account → JWT.
Exception: /computers/me/* uses Computer Token (not Mind Key or JWT).
Mind Key vs JWT — quando usare quale?
Synapse ha due token di autenticazione. Scegliere quello sbagliato porta a
errori 401. Questa guida le dà un framework decisionale chiaro.
Tabella decisionale rapida
| Vuole... | Usi |
|----------------|-----|
| Memorizzare / richiamare memorie | Mind Key |
| Inviare / polling messaggi chat | Mind Key |
| Gestire attività | Mind Key |
| Memorizzare script | Mind Key |
| Registrare webhook | Mind Key |
| Controllare computer | Mind Key (lato utente) / Computer Token (lato agente) |
| Registrare un account utente | Nessuna (pubblico) |
| Login | Nessuna (pubblico) |
| Creare / elencare / eliminare menti | JWT |
| Condividere una mente con un altro utente | JWT |
| Sottoscrivere notifiche web push | JWT |
| Vedere il log di audit | Mind Key |
La regola semplice
> [!TIP]
> Se tocca i dati di una singola mente → Mind Key.
> Se gestisce l'account o i metadati delle menti → JWT.
Mind Key — token di accesso ai dati
Una Mind Key concede accesso ai dati di una mente. È un token long-lived
che non scade mai (fino a quando la mente viene eliminata). Perfetta per:
- Agenti LLM che persistono memorie tra sessioni
- Cron job in background
- Configurazione del server MCP
- Integrazioni webhook
- App mobile che leggono la memoria
Cosa può fare la Mind Key
- — leggere tutte le memorie in questa mente
- — memorizzare/aggiornare memorie
- — leggere i messaggi chat
- — inviare messaggi chat
- — elencare le attività
- — creare attività
- — memorizzare script
- — registrare webhook
- — accodare comandi per computer
Cosa NON può fare la Mind Key
- Creare / elencare / eliminare menti (serve JWT)
- Condividere una mente con un altro utente (serve JWT)
- Vedere le informazioni dell'account utente (serve JWT)
- Sottoscrivere web push (serve JWT)
JWT — token di gestione account
Un JWT autentica l'account utente. Scade dopo 7 giorni ed è usato per
operazioni a livello di account che coprono più menti o coinvolgono altri
utenti.
Cosa può fare il JWT
- — creare una nuova mente (restituisce una nuova Mind Key)
- — elencare tutte le menti di questo utente
- — eliminare una mente
- — condividere una mente con un altro utente
- — sottoscrivere notifiche web push
- — elencare le condivisioni delle menti
Cosa NON può fare il JWT
- Leggere / scrivere memorie (serve Mind Key)
- Inviare messaggi chat (serve Mind Key)
- Gestire attività (serve Mind Key)
- Registrare webhook (serve Mind Key)
Caso speciale: Computer Token
Gli endpoint (lato agente, per lo screen-remote-agent) usano
un terzo tipo di token: il Computer Token. Questo token viene restituito da
quando si riscatta un codice di installazione, ed è
specifico per un computer registrato.
| Endpoint | Auth |
|----------|------|
| | Computer Token |
| | Computer Token |
| | Mind Key o JWT |
| | Mind Key o JWT |
Modelli comuni
Modello 1: agente LLM singolo
1. Si registra una volta → ottiene JWT
2. Crea una mente → ottiene Mind Key
3. L'LLM usa la Mind Key per tutto
Modello 2: agente multi-progetto
1. Si registra una volta → ottiene JWT
2. Crea menti multiple (work, personal, project-x) → ottiene Mind Key multiple
3. L'LLM carica Mind Key diverse in base al contesto
Modello 3: condivisione di team
1. L'Utente A crea una mente → ottiene Mind Key A
2. L'Utente A condivide con l'Utente B tramite JWT ()
3. L'Utente B ora può accedere tramite il suo stesso JWT
4. Per l'accesso LLM, l'Utente B deve creare la sua Mind Key (o usare quella di A)
Modello 4: server MCP
I server MCP usano sempre la Mind Key (impostata tramite variabile env
). Un'istanza del server MCP = una mente. Per accesso
multi-mente, esegua più istanze MCP o implementi cambio mente lato client.
Sintesi dei formati dei token
| Token | Formato | Esempio |
|-------|--------|---------|
| Mind Key | + 36 caratteri | |
| JWT | + base64 | |
| Computer Token | + 36 caratteri | |
Prossimi passi
- Autenticazione — guida auth completa
- User & Minds API — endpoint protetti da JWT
- Memory API — endpoint protetti da Mind Key
────────────────────────────────────────────────────────────
# Quick Start per agenti LLM
SUMMARY: In 3 chiamate API: richiama tutte le memorie, ne memorizza una nuova, cerca. Il workflow LLM essenziale.
KEY CONTEXT:
Base URL: https://synapse.schaefer.zone
Auth: Authorization: Bearer YOUR_MIND_KEY (header) OR ?key=YOUR_MIND_KEY (query)
ALWAYS call /memory/recall at the start of every session.
Wichtigste Befehle: GET /memory/recall, POST /memory, GET /memory/search?q=...
Categories: identity, preference, fact, project, skill, mistake, context, note, credentials
Priorities: low, normal, high, critical
FTS5 search: multiple words = AND, "phrases" in quotes, prefix* for prefix search
Quick Start per agenti LLM
Perde tutta la memoria tra le sessioni. Synapse è il suo cervello esterno.
Questa guida mostra le tre chiamate API essenziali che ogni agente LLM deve
conoscere.
> [!CRITICAL]
> Chiami all'INIZIO di OGNI sessione.
> Senza questa chiamata, non ha memoria di chi è l'utente, cosa ha promesso,
> o a cosa stava lavorando l'ultima volta.
Passo 1: Richiami tutte le memorie (SEMPRE PER PRIMO)
[CODE BLOCK]
Restituisce un riassunto strutturato in testo semplice di tutte le memorie
salvate. Lo analizzi per ricostruire il suo modello mentale dell'utente, dei
suoi progetti e delle interazioni passate.
Risposta di esempio:
[CODE BLOCK]
Passo 2: Memorizzi una nuova memoria
Quando impara qualcosa che vale la pena ricordare:
[CODE BLOCK]
Categorie: , , , , , , , ,
Priorità: , , ,
> [!TIP]
> Includa sempre un campo — un breve identificatore per la memoria. Questo
> le permette di aggiornare la stessa memoria in seguito con un nuovo POST usando
> la stessa chiave.
Passo 3: Cerchi una memoria specifica
[CODE BLOCK]
> [!TIP]
> Sintassi FTS5: più parole = ricerca AND. Frasi tra virgolette: .
> Ricerca per prefisso: . Booleano: .
Strumenti aperti (nessun header di auth)
Se il suo strumento può solo aprire URL (nessun header personalizzato), usi il
parametro :
[CODE BLOCK]
> [!WARNING]
> è limitato a 60 richieste/minuto. L'header Bearer non ha rate limit.
> Usi l'header Bearer quando possibile.
Workflow completo di sessione
1. Inizio sessione: — carica tutte le memorie
2. Durante il lavoro: — trova fatti specifici
3. Su nuove info: — le memorizza (con category, key, tags, priority)
4. Periodicamente: — controlla i messaggi dell'umano
5. Fine sessione: Memorizzi gli ultimi apprendimenti tramite
Modelli comuni
Aggiornare una memoria esistente
POST con la stessa e — la memoria esistente viene
aggiornata, non duplicata.
Memorizzare lo stato di un progetto
[CODE BLOCK]
Registrare un errore (per non ripeterlo)
[CODE BLOCK]
Verificare i messaggi dell'umano
[CODE BLOCK]
Restituisce i messaggi non letti dall'umano. Risponda con:
[CODE BLOCK]
Prossimi passi
- Autenticazione — Mind Key vs JWT
- Riferimento Memory API — tutti i 22 endpoint memory
- Chat API — comunicazione asincrona con gli umani
- LLM Cookbook — modelli pratici
────────────────────────────────────────────────────────────
# Quick Start (umano)
SUMMARY: Registri un account, crei la sua prima mente, memorizzi una memoria — tutto in 5 minuti.
Quick Start (umano)
Questa guida la accompagna nell'ottenere un account Synapse, la sua prima Mind
Key e nel memorizzare la sua prima memoria. Tempo totale: 5 minuti.
Passo 1: Registri un account
Apra l'API di Synapse e crei un account:
[CODE BLOCK]
Risposta:
[CODE BLOCK]
> [!TIP]
> Salvi il JWT in un posto sicuro — le servirà per creare le menti. Il JWT
> scade dopo 7 giorni; rifaccia login con lo stesso endpoint per rinfrescarlo.
Passo 2: Crei la sua prima mente
Una "mente" è uno scope di memoria isolato. La maggior parte degli utenti
inizia con una mente, ma può averne multiple (es. "work", "personal",
"project-x"). Ogni mente ha la sua Mind Key univoca.
[CODE BLOCK]
Risposta:
[CODE BLOCK]
> [!CRITICAL]
> Salvi la immediatamente. Viene mostrata una sola volta e non
> può essere recuperata in seguito. Se la perde, dovrà creare una nuova mente.
Passo 3: Memorizzi la sua prima memoria
Ora usi la Mind Key per memorizzare una memoria:
[CODE BLOCK]
Risposta:
[CODE BLOCK]
Passo 4: Richiami tutte le memorie
Per recuperare tutto ciò che ha memorizzato:
[CODE BLOCK]
Risposta (testo semplice, ottimizzato per consumo LLM):
[CODE BLOCK]
Passo 5: Cerchi nelle memorie
Trovi memorie specifiche per parola chiave:
[CODE BLOCK]
Passo 6: Connetta il suo LLM
Il modo più semplice per dare al suo LLM accesso a Synapse è tramite MCP:
- Configurazione Claude Desktop — config in 2 minuti
- Configurazione Claude Code — integrazione terminale
- Configurazione Cursor — integrazione IDE
Dopo la configurazione, il suo LLM chiamerà automaticamente
all'inizio di ogni sessione e persisterà nuovi fatti tramite .
Categorie di memoria
Synapse supporta 8 categorie — scelga la più specifica:
| Categoria | Caso d'uso |
|----------|----------|
| | Nome utente, ruolo, informazioni di contatto |
| | Piaceri, dispiaceri, stile di lavoro |
| | Fatti verificabili (dettagli di progetto, date) |
| | Stato del progetto, milestone, todo |
| | Cose in cui l'utente è bravo |
| | Errori passati — da evitare di ripetere |
| | Contesto rilevante per la sessione |
| | Note varie |
Livelli di priorità
- — piace da sapere
- — predefinita
- — importante
- — da non dimenticare mai (identità utente, info legali)
Prossimi passi
- Approfondimento autenticazione
- Mind Key vs JWT
- Riferimento Memory API
- Integrazione MCP
────────────────────────────────────────────────────────────
# Cos'è Synapse?
SUMMARY: Synapse è un'API di memoria persistente per agenti LLM — la sua AI non dimentica mai tra le sessioni.
KEY CONTEXT:
Synapse is an HTTP API that gives LLM agents persistent memory across sessions.
Base URL: https://synapse.schaefer.zone
Auth: Authorization: Bearer YOUR_MIND_KEY (header) OR ?key=YOUR_MIND_KEY (query, rate-limited 60/min)
Most important endpoints: GET /memory/recall (start of every session), POST /memory (store new facts), GET /memory/search?q=...
Mind Key = tenant-scoped API key. Each user can have multiple minds (projects/contexts).
MCP server available: npx -y synapse-mcp-api (79 tools for Claude Desktop, Cursor, etc.)
Cos'è Synapse?
Synapse è una API di memoria persistente per agenti LLM. Risolve il
problema fondamentale di ogni LLM basato su chat: tra le sessioni, l'agente
dimentica tutto. Synapse dà alla sua AI un cervello permanente e interrogabile
che sopravvive tra le conversazioni, tra i giorni e tra diversi provider LLM.
> [!CRITICAL]
> Se è un agente LLM che sta leggendo: chiami all'inizio
> di ogni sessione. Senza questa chiamata, non ha memoria delle interazioni
> passate, nessuna conoscenza di chi è l'utente e nessun contesto sui progetti
> in corso.
Il problema che Synapse risolve
Ogni LLM moderno (Claude, GPT, Gemini, Llama) ha la stessa limitazione
architetturale: la finestra di contesto della conversazione è finita, e una
volta che la sessione finisce, tutto lo stato è perso. Questo significa che il
suo assistente AI:
- Dimentica il suo nome, le sue preferenze e i progetti in corso tra le chat
- Non può imparare dagli errori passati tra le sessioni
- Non ha continuità per lavoro long-running
- Rifa le stesse domande di chiarimento ogni volta
Synapse risolve questo fornendo una semplice API HTTP dove l'LLM può salvare e
recuperare memorie strutturate. Le memorie persistono sul server, indicizzate
e ricercabili, così qualsiasi sessione futura può richiamarle.
Funzionalità chiave
- Memorizzazione persistente — fatti, preferenze, progetti, errori, competenze
- Ricerca full-text (FTS5) — trova qualsiasi memoria per parola chiave in millisecondi
- Ricerca semantica — ricerca di similarità basata su embedding per query concettuali
- Multi-tenant — ogni utente ha "menti" isolate (un utente, molti progetti)
- Chat asincrona — gli umani possono lasciare messaggi per l'agente mentre lavora
- Attità e pianificazione — task manager integrato e cron scheduler
- Integrazione MCP — 79 strumenti esposti come Model Context Protocol per Claude, Cursor, Continue
- Controllo browser e computer — strumenti di automazione remota
- Webhook — riceva callback HTTP su modifiche a memory/chat/task
Come funziona
[CODE BLOCK]
1. L'LLM chiama all'inizio della sessione
2. Synapse restituisce un riassunto testuale strutturato di tutte le memorie salvate
3. L'LLM lavora, chiamando periodicamente per salvare nuovi fatti
4. Quando l'utente fa una domanda, l'LLM può chiamare
5. Alla fine della sessione, il nuovo contesto importante viene persistito per la sessione successiva
Per chi è?
- Sviluppatori di agenti LLM che hanno bisogno di stato persistente
- Power user che eseguono LLM locali (Ollama, LM Studio) con agenti personalizzati
- Team che costruiscono assistenti AI che hanno bisogno di memoria condivisa
- Ingegneri di automazione che concatenano chiamate LLM tra sessioni
Confronto rapido
| Funzionalità | ChatGPT Memory | Synapse |
|---------|---------------|---------|
| Posizione storage | Server OpenAI | Suo server |
| Accesso API | No (chiuso) | Sì (REST + MCP) |
| Multi-tenant | No | Sì (menti) |
| Categorie personalizzate | No | Sì (8 categorie) |
| Ricerca | Limitata | FTS5 + semantica |
| Self-hostable | No | Sì (Docker) |
Prossimi passi
- Quick Start per umani — ottenga una Mind Key in 5 minuti
- Quick Start per LLM — prime chiamate API
- Autenticazione — Mind Key vs JWT
- Panoramica architettura — come è costruito Synapse
## CATEGORIA: RIFERIMENTO API
Riferimento completo per ogni endpoint API.
────────────────────────────────────────────────────────────
# Browser Proxy
SUMMARY: Servizio di automazione browser — container Docker separato sulla porta 13000 per il controllo di browser headless.
KEY CONTEXT:
Browser Proxy is a SEPARATE Docker service (port 13000), NOT a Synapse endpoint.
Synapse endpoints do NOT include /browser/* paths.
For browser automation, use the MCP browser_new tool OR connect to the browser-proxy service directly.
Synapse MCP exposes browser tools (browser_new, browser_navigate, browser_click, etc.)
Browser Proxy
Il Browser Proxy è un servizio Docker separato che fornisce automazione
di browser headless tramite Playwright. NON fa parte direttamente dell'API di
Synapse — gli endpoint di Synapse non includono percorsi .
Architettura
[CODE BLOCK]
Metodi di accesso
Metodo 1: tramite il server MCP di Synapse (consigliato)
Il server MCP di Synapse espone i browser tool come strumenti MCP. Lo utilizzi
per l'automazione del browser guidata da LLM:
[CODE BLOCK]
Strumenti MCP per il browser disponibili:
- — apre una nuova scheda del browser
- — naviga a un URL
- — clicca su un elemento
- — digita testo in un campo
- — cattura una schermata
- — chiude la scheda
- (e altri — vedi Integrazione MCP)
Metodo 2: accesso diretto al Browser Proxy
Per integrazioni non MCP, si connetta direttamente al servizio browser-proxy:
[CODE BLOCK]
Casi d'uso comuni
Web scraping
[CODE BLOCK]
Automazione di form
[CODE BLOCK]
Cattura di schermate
[CODE BLOCK]
Servizi correlati
| Servizio | Porta | Scopo |
|---------|------|---------|
| Synapse API | 12800 | Memoria, chat, attività |
| Synapse MCP | 13100 | Server MCP (79 strumenti) |
| Browser Proxy | 13000 | Automazione browser headless |
| SSH Proxy | 12900 | Accesso SSH a macchine remote |
Prossimi passi
- Integrazione MCP — come usare i browser tool tramite MCP
- API Computer Control — per automazione GUI su macchine registrate
────────────────────────────────────────────────────────────
# Chat API
SUMMARY: Chat asincrona tra umani e agenti LLM — polling, risposte, cronologia, conteggio non letti, caricamento file.
KEY CONTEXT:
Auth: Mind Key (agent side, ?role=agent) or JWT (human side, ?role=human)
Poll: GET /chat/poll (returns unread messages, marks them as read)
Reply: POST /chat/reply { content }
History: GET /chat/history?limit=50
Unread count: GET /chat/unread?role=agent (or ?role=human)
Upload: POST /chat/upload (multipart, file attachment)
Pattern: poll between tool calls, reply when human asks questions
Chat API
La Chat API permette la messaggistica asincrona tra umani e agenti LLM.
A differenza della chat sincrona (stile ChatGPT), l'umano può lasciare messaggi
mentre l'agente sta lavorando — l'agente esegue il polling tra le chiamate agli
strumenti.
Come funziona
[CODE BLOCK]
1. L'umano invia un messaggio tramite l'interfaccia web (usa JWT)
2. Il messaggio viene memorizzato e contrassegnato come non letto
3. L'agente esegue il polling con tra le chiamate agli strumenti
4. Il polling restituisce tutti i messaggi non letti e li contrassegna come letti
5. L'agente elabora il messaggio e, opzionalmente, risponde tramite
Endpoint
GET /chat/poll
Esegue il polling dei nuovi messaggi dall'umano. Restituisce i messaggi non letti
e li contrassegna come letti. Lo utilizzi tra una chiamata e l'altra degli
strumenti.
[CODE BLOCK]
Risposta:
[CODE BLOCK]
POST /chat/reply
Invia un messaggio come agente.
[CODE BLOCK]
POST /chat/send
Invia un messaggio come umano (richiede JWT, non Mind Key).
[CODE BLOCK]
GET /chat/history
Ottiene la cronologia recente della chat (entrambi i ruoli).
[CODE BLOCK]
GET /chat/unread
Ottiene il conteggio dei messaggi non letti.
[CODE BLOCK]
GET /chat/status
Ottiene lo stato della sessione di chat (timestamp ultimo messaggio, conteggi non letti).
[CODE BLOCK]
POST /chat/upload
Carica un allegato per uno specifico messaggio (multipart form).
[CODE BLOCK]
GET /chat/files/:messageid
Elenca gli allegati di un messaggio.
[CODE BLOCK]
GET /chat/file/:fileid
Scarica un allegato.
[CODE BLOCK]
Modello di polling
> [!TIP]
> Esegua il polling ogni 30-60 secondi tra le chiamate agli strumenti. Non esegua
> il polling più frequentemente — spreca la quota API senza alcun beneficio.
[CODE BLOCK]
Prossimi passi
- API Tasks
- Modello di polling chat
────────────────────────────────────────────────────────────
# Computer Control API
SUMMARY: Controllo remoto di computer registrati — accoda comandi, cattura schermate, esegue script su macchine remote.
KEY CONTEXT:
Two sides: user-facing (Mind Key/JWT) and agent-facing (Computer Token)
Register agent: POST /computers/register { install_code } → returns computer_token
List: GET /computers/list (Mind Key or JWT)
Queue command: POST /computers/:id/commands { type, payload }
Command types: screenshot, click, move, type, key, scroll, drag
Agent poll: GET /computers/me/poll?wait=5 (Computer Token)
Agent result: POST /computers/me/commands/:cid/result (Computer Token)
One-shot screenshot: GET /computers/:id/screenshot (waits 30s for result)
Pattern: register agent on remote machine → user queues commands → agent polls and executes
Computer Control API
La Computer Control API permette di controllare da remoto computer registrati.
Un piccolo agente () viene eseguito sulla macchina di
destinazione, esegue il polling dei comandi, li esegue e pubblica i risultati.
Questo abilita l'automazione GUI guidata da LLM.
Architettura
[CODE BLOCK]
Endpoint lato utente (Mind Key o JWT)
GET /computers/list
Elenca tutti i computer registrati.
[CODE BLOCK]
GET /computers/:id
Ottiene i dettagli di un singolo computer.
[CODE BLOCK]
POST /computers/install-code
Genera un codice di installazione per registrare un nuovo computer.
[CODE BLOCK]
Risposta:
POST /computers/:id/commands
Accoda un comando che l'agente remoto eseguirà.
[CODE BLOCK]
Risposta:
GET /computers/:id/command (via query)
Accoda un comando tramite GET (per casi semplici).
[CODE BLOCK]
GET /computers/:id/commands
Elenca i comandi recenti di un computer.
[CODE BLOCK]
GET /computers/:id/commands/:cid
Ottiene stato + risultato di uno specifico comando.
[CODE BLOCK]
GET /computers/:id/screenshot
One-shot: accoda un comando screenshot e attende fino a 30s per il risultato.
[CODE BLOCK]
POST /computers/:id/disable
Disabilita un computer (revoca il token, mantiene il record per audit).
[CODE BLOCK]
DELETE /computers/:id
Elimina definitivamente un computer.
[CODE BLOCK]
Endpoint lato agente (Computer Token)
Questi endpoint sono utilizzati dal in esecuzione sulla
macchina di destinazione. Usano un Computer Token (restituito da
), non una Mind Key.
POST /computers/register
Riscatta un codice di installazione e ottiene un Computer Token.
[CODE BLOCK]
Risposta:
> [!CRITICAL]
> Salvi il — viene mostrato una sola volta ed è richiesto per
> tutti gli endpoint lato agente.
GET /computers/me/poll
Long-polling per nuovi comandi. L'agente lo chiama in un ciclo.
[CODE BLOCK]
Ritorna immediatamente se ci sono comandi in attesa, o dopo secondi in caso contrario.
POST /computers/me/commands/:cid/result
Pubblica il risultato dell'esecuzione di un comando.
[CODE BLOCK]
Tipi di comando
| Tipo | Payload | Descrizione |
|------|---------|-------------|
| | | Cattura schermo come PNG (base64) |
| | | Clic alle coordinate |
| | | Sposta il mouse alle coordinate |
| | | Digita testo al cursore |
| | | Preme una combinazione di tasti |
| | | Rotella di scorrimento |
| | | Trascina e rilascia |
Modello comune: automazione GUI guidata da LLM
[CODE BLOCK]
Prossimi passi
- Browser Proxy — servizio separato per automazione browser
- Guida Self-Hosted Agents
────────────────────────────────────────────────────────────
# Cron & Scheduler
SUMMARY: Pianifica chiamate API ricorrenti — cron job che si attivano secondo una pianificazione, perfetti per sync periodici e promemoria.
KEY CONTEXT:
Auth: Mind Key
Create: POST /cron { schedule, endpoint, method?, body?, headers?, enabled? }
List: GET /cron
Delete: DELETE /cron/:id
Toggle: PUT /cron/:id/toggle
Schedule: 5-field cron (minute hour day month day-of-week) OR integer interval (seconds)
Endpoint: must be http(s) URL, same Synapse instance OR public HTTPS (no private IPs)
Pattern: schedule /memory/recall every hour, /chat/poll every 5 min, etc.
Cron & Scheduler
La Cron API permette di pianificare chiamate HTTP ricorrenti agli endpoint di
Synapse (o a endpoint HTTPS esterni). Perfetta per sync periodici, promemoria e
attività di manutenzione.
Endpoint
POST /cron
Crea un'attività pianificata.
[CODE BLOCK]
Risposta:
[CODE BLOCK]
GET /cron
Elenca tutte le attività pianificate.
[CODE BLOCK]
DELETE /cron/:id
Elimina un'attività pianificata.
[CODE BLOCK]
PUT /cron/:id/toggle
Abilita o disabilita un'attività senza eliminarla.
[CODE BLOCK]
Sintassi della pianificazione
Cron standard (5 campi)
[CODE BLOCK]
Esempi:
| Pianificazione | Significato |
|----------|---------|
| | Ogni ora |
| | Ogni 15 minuti |
| | Giorni feriali alle 9:00 |
| | Ogni domenica a mezzanotte |
| | Il primo di ogni mese a mezzanotte |
Intervallo intero (secondi)
Per intervalli semplici, passi un intero:
[CODE BLOCK]
Restrizioni sugli endpoint
> [!WARNING]
> Gli endpoint devono essere URL o che puntano a:
> - La stessa istanza Synapse (es. )
> - URL HTTPS pubblici (no IP privati, no localhost, no IP di metadata)
Questo previene attacchi SSRF in cui una mente compromessa potrebbe pianificare
richieste a servizi interni.
Modelli comuni
Richiamo memoria orario (per agenti LLM)
[CODE BLOCK]
Backup giornaliero
[CODE BLOCK]
Polling chat periodico (ogni 5 minuti)
[CODE BLOCK]
Attivazione report settimanale
[CODE BLOCK]
Prossimi passi
- API Variables
- API Webhooks
────────────────────────────────────────────────────────────
# Errori e gestione degli errori
SUMMARY: Codici di stato HTTP, formato delle risposte di errore e come riprendersi dai problemi più comuni.
KEY CONTEXT:
Error format: { statusCode, error, message, docs? }
Common errors: 401 (auth), 404 (wrong path), 429 (rate limit), 500 (server)
401 → check Mind Key/JWT, see /docs/getting-started/authentication
404 → wrong path, GET /endpoints for valid list, do NOT guess paths
429 → rate limited (?key= is 60/min), use Bearer header instead
500 → server error, retry with backoff, check /health
docs field in error response links to relevant documentation.
Errori e gestione degli errori
Synapse utilizza codici di stato HTTP standard con un formato di risposta di
errore coerente. Questa pagina spiega come interpretare gli errori e come
riprendersi.
Formato della risposta di errore
Tutti gli errori restituiscono JSON con questa struttura:
[CODE BLOCK]
| Campo | Descrizione |
|-------|-------------|
| | Codice di stato HTTP |
| | Nome dello stato HTTP |
| | Descrizione dell'errore leggibile dall'umano |
| | URL alla documentazione pertinente (quando applicabile) |
Codici di stato HTTP
200 OK
Successo. La richiesta è stata elaborata correttamente.
201 Created
Successo. Una nuova risorsa è stata creata (es. ).
204 No Content
Successo. Nessun corpo restituito (es. ).
400 Bad Request
La richiesta era malformata. Cause comuni:
- Campi JSON obbligatori mancanti
- Sintassi JSON non valida
- Valore enum non valido (es. categoria errata)
[CODE BLOCK]
Soluzione: Verifichi il corpo della richiesta rispetto alla documentazione
API. Si assicuri che tutti i campi obbligatori siano presenti e abbiano valori
validi.
401 Unauthorized
Autenticazione fallita. Cause comuni:
- Header mancante
- Mind Key o JWT non valido
- Uso di una Mind Key dove è richiesto un JWT (o viceversa)
[CODE BLOCK]
Soluzione: Verifichi il suo token. Veda Autenticazione.
403 Forbidden
È autenticato ma non autorizzato a eseguire questa azione. Cause comuni:
- Tentativo di eliminare la mente di un altro utente
- Tentativo di verificare una memoria con una Mind Key (richiede JWT)
- La mente è disabilitata
Soluzione: Verifichi se sta usando il tipo di token corretto per questo
endpoint.
404 Not Found
Il percorso o la risorsa richiesta non esiste.
> [!CRITICAL]
> Non indovini i percorsi degli endpoint. Esistono solo i percorsi elencati
> in . Se ottiene un 404, ha usato un percorso errato.
[CODE BLOCK]
Soluzione: Chiami per vedere la lista degli endpoint
validi. Confronti la sua URL con la lista carattere per carattere.
409 Conflict
La richiesta è in conflitto con lo stato esistente. Cause comuni:
- Tentativo di registrazione con un'email già esistente
- URL webhook duplicato
Soluzione: Usi un valore diverso, oppure usi per aggiornare la
risorsa esistente.
429 Too Many Requests
Ha raggiunto un limite di traffico. Si applica solo all'autenticazione tramite
parametro query (60/min).
[CODE BLOCK]
Header di risposta:
[CODE BLOCK]
Soluzione: Passi all'header (nessun limite), oppure
attenda secondi.
500 Internal Server Error
Errore del server. Non dovrebbe accadere — se accade, è un bug.
Soluzione:
1. Riprovi con backoff esponenziale (1s, 2s, 4s, 8s)
2. Verifichi con se il server è attivo
3. Se persiste, segnali l'errore
503 Service Unavailable
Il server è temporaneamente non disponibile (es. durante il deployment,
migrazione del database).
Soluzione: Attenda e riprovi. Verifichi .
Modelli di recupero
Riprova con backoff esponenziale
[CODE BLOCK]
Gestione errori di autenticazione
[CODE BLOCK]
Scenari di errore comuni
"Mind Key fehlt oder ungültig"
- Ha dimenticato l'header
- Ha usato ma la chiave è errata
- Sta usando un JWT dove è richiesta una Mind Key
"Route not found"
- Ha indovinato un percorso che non esiste
- Ha usato un verbo sbagliato (es. vs )
- Verifichi per i percorsi validi
"Rate limit exceeded"
- Sta usando e ha superato 60 req/min
- Passi all'header
Prossimi passi
- Autenticazione
- Panoramica API
- Limiti di traffico
────────────────────────────────────────────────────────────
# 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
────────────────────────────────────────────────────────────
# Panoramica API e URL di base
SUMMARY: Tutti gli endpoint dell'API Synapse, URL di base, modelli di autenticazione e formati di risposta a colpo d'occhio.
KEY CONTEXT:
Base URL: https://synapse.schaefer.zone
Auth: Authorization: Bearer YOUR_MIND_KEY (header, no rate limit)
OR ?key=YOUR_MIND_KEY (query, 60 req/min)
All responses are JSON except /memory/recall (text/plain) and /docs (HTML/text/json)
All 404 responses mean the path does not exist — do NOT guess paths.
GET /endpoints returns machine-readable list of all valid endpoints.
Panoramica API e URL di base
L'API di Synapse è un'API HTTP RESTful. Tutti gli endpoint restituiscono JSON
( salvo dove indicato). Questa pagina tratta gli elementi essenziali necessari
prima di addentrarsi negli endpoint specifici.
URL di base
[CODE BLOCK]
Tutti i percorsi in questa documentazione sono relativi a questo URL di base.
Per istanze self-hosted, sostituisca con il proprio URL.
Autenticazione
Due metodi, entrambi inviati tramite header :
[CODE BLOCK]
Oppure tramite parametro query (limitato a 60/min):
[CODE BLOCK]
Veda Autenticazione per i dettagli.
Gruppi di endpoint
| Gruppo | Auth | Descrizione |
|-------|------|-------------|
| Pubblico | Nessuna | Landing page, health, OpenAPI, docs |
| Memory | Mind Key | CRUD, ricerca, sync, embedding |
| Chat | Mind Key / JWT | Messaggistica asincrona tra umano e agente |
| Tasks | Mind Key | Gestione attività |
| Scripts | Mind Key / JWT | Archivio script persistente |
| Scheduler | Mind Key | Cron job + variabili |
| Webhooks | Mind Key | Callback HTTP su eventi |
| Computers | Mind Key / JWT | Controllo computer remoto |
| User/Minds | JWT | Account + gestione mente |
| Sharing | JWT | Condivisione menti tra utenti |
| Push | JWT | Sottoscrizioni Web Push |
| Tools | Nessuna | Time, calc, random (utility pubbliche) |
Formati di risposta
- JSON (predefinito):
- Testo semplice: restituisce testo ottimizzato per LLM
- HTML: , , , ,
Busta standard di risposta
Le risposte di successo restituiscono direttamente i dati:
[CODE BLOCK]
Le risposte di errore usano questo formato:
[CODE BLOCK]
> [!NOTE]
> Il campo linka alla documentazione pertinente per gli errori comuni.
Codici di stato HTTP
| Codice | Significato |
|------|---------|
| 200 | Successo (GET, PUT) |
| 201 | Creato (POST) |
| 204 | Nessun contenuto (DELETE) |
| 400 | Richiesta errata (errore di validazione) |
| 401 | Non autorizzato (token mancante/non valido) |
| 403 | Vietato (tipo di token errato) |
| 404 | Non trovato (percorso inesistente) |
| 409 | Conflitto (duplicato) |
| 429 | Troppe richieste (rate limit) |
| 500 | Errore del server |
Endpoint di scoperta
| Endpoint | Scopo |
|----------|---------|
| | Landing page (ottimizzata per LLM) |
| | Lista machine-readable di tutti gli endpoint |
| | Lista endpoint in testo semplice |
| | Specifica OpenAPI 3.0 |
| | Documentazione API completa (HTML) |
| | Documentazione API come JSON |
| | Sistema di documentazione (HTML) |
| | Indice della documentazione (JSON) |
| | Tutta la documentazione come blocco di testo |
| | Playground API interattivo |
Limiti di traffico
| Metodo di auth | Limite |
|-------------|-------|
| Mind Key (header) | Nessuno |
| Mind Key (?key=) | 60/min per IP |
| JWT (header) | Nessuno |
| Endpoint pubblici | Nessuno |
Le risposte con limiti di traffico includono:
[CODE BLOCK]
Paginazione
Gli endpoint di elenco supportano e :
[CODE BLOCK]
Limite predefinito: 100. Limite massimo: 500.
CORS
Tutti gli endpoint supportano CORS per client basati su browser:
[CODE BLOCK]
SDK e client
- SDK Node.js: (repo)
- Server MCP: (repo)
- Client HTTP: qualsiasi libreria HTTP (curl, fetch, axios, ecc.)
Prossimi passi
- Memory API — gli endpoint più importanti
- Chat API — comunicazione asincrona umano-agente
- Errori e gestione degli errori
────────────────────────────────────────────────────────────
# Limiti di traffico e quote
SUMMARY: Politica di rate limit dell'API Synapse — header Bearer (illimitato), ?key= (60/min), endpoint pubblici.
KEY CONTEXT:
Mind Key (Authorization: Bearer header) → NO rate limit
Mind Key (?key= query param) → 60 req/min per IP
JWT (Authorization: Bearer header) → NO rate limit
Public endpoints (/tools/*, /docs, /health, /endpoints) → NO rate limit
Rate limit headers: X-RateLimit-Limit, X-RateLimit-Remaining, Retry-After
Recommendation: ALWAYS use Authorization header. Use ?key= only for URL-only tools.
Limiti di traffico e quote
Synapse ha una politica di rate limit semplice e prevedibile, progettata per
prevenire abusi senza intralciare l'uso legittimo.
Politica di rate limit
| Metodo di auth | Limite | Ambito |
|-------------|-------|-------|
| Mind Key () | Nessuno | Per-mente |
| Mind Key () | 60 req/min | Per-IP |
| JWT () | Nessuno | Per-utente |
| Endpoint pubblici | Nessuno | Globale |
> [!TIP]
> Usi sempre l'header quando possibile. Non ha
> limiti di traffico. Usi solo per strumenti che non possono impostare
> header personalizzati.
Header di rate limit
Quando usa l'autenticazione , le risposte includono header di rate limit:
[CODE BLOCK]
Quando supera il limite:
[CODE BLOCK]
Quando raggiunge un limite
Se ottiene un 429:
1. Passi all'header Authorization (consigliato):
[CODE BLOCK]
2. Oppure attenda secondi e riprovi.
Perché esiste il limite ?key=
Il parametro query è comodo per strumenti solo-URL (browser, comandi
), ma ha implicazioni di sicurezza e prestazioni:
- Sicurezza: I parametri query vengono registrati nei log di accesso del
server, nella cronologia del browser e negli header Referer. Limitarne l'uso
riduce l'esposizione.
- Prestazioni: L'autenticazione tramite parametro query richiede un rate
limiter basato su IP (lookup Redis per richiesta), che aggiunge latenza.
L'autenticazione tramite header lo salta.
- Prevenzione abusi: Un URL leakato potrebbe essere condiviso e
bombardato di richieste. Il limite per IP contiene il raggio d'azione.
Modelli consigliati
Agenti LLM
[CODE BLOCK]
Strumenti basati su browser
Se il suo strumento può solo aprire URL:
[CODE BLOCK]
Server MCP
I server MCP usano sempre l'autenticazione tramite header usando la variabile
di ambiente — nessun limite di traffico si applica.
Importazioni bulk
Per operazioni bulk (es. importare 1000 memorie), usi sempre l'autenticazione
tramite header. Le importazioni bulk tramite raggiungono il limite entro
1 minuto.
Quote (livello mente)
Attualmente non ci sono quote per mente sulla dimensione di archiviazione o
sul numero di memorie. Tutti i limiti sono a livello di auth/IP, non di dati.
Questo potrebbe cambiare in futuro per equità multi-tenant.
Monitoraggio dell'utilizzo
[CODE BLOCK]
Prossimi passi
- Autenticazione
- Errori e gestione degli errori
────────────────────────────────────────────────────────────
# Scripts API
SUMMARY: Archivio script persistente — salva script shell, Python o Node riutilizzabili e recuperali tramite curl | bash.
KEY CONTEXT:
Auth: Mind Key or JWT
Store: POST /script { name, content, description?, language? }
Fetch as text: GET /script/:name (returns text/plain, curl | bash ready)
Info: GET /script/:name/info (metadata without content)
List: GET /scripts (JSON array)
Delete: DELETE /script/:name
Use case: store deployment scripts, config generators, troubleshooting snippets
Scripts API
La Scripts API fornisce un archivio persistente per script riutilizzabili. Gli
script sono nominati e versionati all'interno di una mente, e possono essere
recuperati come testo semplice — perfetti per i modelli .
Endpoint
POST /script
Memorizza o aggiorna uno script.
[CODE BLOCK]
GET /script/:name
Recupera il contenuto dello script come . Perfetto per il pipe a bash.
[CODE BLOCK]
GET /script/:name/info
Ottiene i metadati dello script senza il contenuto.
[CODE BLOCK]
Risposta:
[CODE BLOCK]
GET /scripts
Elenca tutti gli script nella mente corrente.
[CODE BLOCK]
DELETE /script/:name
Elimina uno script.
[CODE BLOCK]
Casi d'uso comuni
Script di deployment
Memorizzi le procedure di deployment standard così l'LLM può eseguirle senza
riderivare i passaggi ogni volta:
[CODE BLOCK]
Snippet di troubleshooting
Memorizzi comandi diagnostici per problemi comuni:
[CODE BLOCK]
Generatori di configurazione
Memorizzi script che generano configurazioni:
[CODE BLOCK]
Prossimi passi
- API Variables
- Cron & Scheduler
────────────────────────────────────────────────────────────
# Tasks API
SUMMARY: Gestione attività per agenti LLM — crea, elenca, aggiorna, completa, elimina attività con priorità.
KEY CONTEXT:
Auth: Mind Key
List: GET /mind/tasks?status=pending|in_progress|done|cancelled|all
Create: POST /mind/task { title, description?, priority?, due_at? }
Update: PUT /mind/task/:id { title?, description?, priority?, status?, due_at? }
Complete: GET /mind/task/:id/complete
Delete: GET /mind/task/:id/delete
Priorities: low, normal, high, critical
Statuses: pending, in_progress, done, cancelled
Pattern: create tasks for multi-step work, update status as you progress
Tasks API
La Tasks API offre agli agenti LLM un modo strutturato per tracciare lavoro
multi-step. Le attività sono limitate alla mente corrente e persistono tra le
sessioni, così l'agente può riprendere il lavoro da dove lo aveva lasciato.
Endpoint
GET /mind/tasks
Elenca tutte le attività della mente corrente.
[CODE BLOCK]
Risposta:
[CODE BLOCK]
POST /mind/task
Crea una nuova attività.
[CODE BLOCK]
GET /mind/task (parametri query)
Crea un'attività tramite GET (per strumenti solo-URL).
[CODE BLOCK]
PUT /mind/task/:id
Aggiorna un'attività esistente.
[CODE BLOCK]
GET /mind/task/:id/complete
Contrassegna un'attività come completata.
[CODE BLOCK]
GET /mind/task/:id/delete
Elimina definitivamente un'attività.
[CODE BLOCK]
Priorità
- — non urgente
- — predefinita
- — importante
- — da fare immediatamente
Stati
- — creata, non iniziata
- — in lavorazione
- — completata
- — abbandonata
Modello: workflow guidato da attività
[CODE BLOCK]
Prossimi passi
- Workflow guidato da attività
- Cron & Scheduler
────────────────────────────────────────────────────────────
# Strumenti di utilità (time, calc, random)
SUMMARY: Endpoint di utilità pubblici — orario del server, calcolatrice sicura, generatore di valori casuali. Nessuna auth richiesta.
KEY CONTEXT:
No auth required for any /tools/* endpoint.
GET /tools/time → { time, timezone, offset }
GET /tools/calc?expr=(10+5)*3 → { result, expr } (safe, no eval, arithmetic only)
GET /tools/random?type=uuid → { value, type } (types: uuid, int, float, hex, alpha)
Use case: LLM agents that need current time, safe math, or random values.
Strumenti di utilità
Gli endpoint sono utility pubbliche — nessuna autenticazione richiesta.
Sono utili per agenti LLM che hanno bisogno di orario lato server, matematica
sicura o valori casuali.
GET /tools/time
Ottiene l'orario corrente del server, il fuso orario e l'offset UTC.
[CODE BLOCK]
Risposta:
[CODE BLOCK]
Caso d'uso: agenti LLM che hanno bisogno di sapere "che ore sono adesso" per
pianificazione, timestamp o calcoli di date relative.
GET /tools/calc
Calcolatrice sicura — solo aritmetica, nessun . Supporta , , ,
, , , e numeri.
[CODE BLOCK]
Risposta:
[CODE BLOCK]
> [!TIP]
> Lo usi al posto di cercare di fare calcoli a mente o tramite parsing di
> stringhe. È sicuro (nessuna injection di codice possibile) e accurato.
Operatori supportati
- addizione
- sottrazione
- moltiplicazione
- divisione
- modulo
- parentesi
- Numeri (interi e decimali)
Esempi
[CODE BLOCK]
GET /tools/random
Genera valori casuali.
[CODE BLOCK]
Parametri per tipo
| Tipo | Parametri | Output |
|------|-----------|--------|
| | nessuno | Stringa UUID v4 |
| | , (predefinito 0-100) | Intero |
| | , (predefinito 0-100) | Float |
| | , (intervallo lunghezza, predefinito 8-16) | Stringa hex |
| | , (intervallo lunghezza, predefinito 8-16) | Stringa alfabetica |
Casi d'uso per agenti LLM
Genera ID univoci
[CODE BLOCK]
Calcola percentuali
[CODE BLOCK]
Ottieni timestamp corrente
[CODE BLOCK]
Genera dati di test
[CODE BLOCK]
Prossimi passi
- Panoramica API — tutti i gruppi di endpoint
- Errori e gestione degli errori
────────────────────────────────────────────────────────────
# User & Minds API
SUMMARY: Gestione account — registrazione, login, creazione menti, elenco menti, eliminazione menti. Protetto da JWT.
KEY CONTEXT:
Auth: JWT (from /register or /login)
Register: POST /register { email, password, display_name? } → returns JWT
Login: POST /login { email, password } → returns JWT
Create mind: POST /minds { name, description? } → returns mind_key (shown once!)
List minds: GET /minds
Delete mind: DELETE /minds/:id (irreversible — deletes all memories!)
JWT expires after 7 days. Mind Key never expires.
Mind Key is shown only once at creation — save it permanently.
User & Minds API
La User & Minds API gestisce la gestione dell'account. Questi endpoint usano
l'autenticazione JWT (non Mind Key) perché operano a livello di account, non di
mente.
Endpoint di autenticazione
POST /register
Crea un nuovo account utente.
[CODE BLOCK]
Risposta:
[CODE BLOCK]
POST /login
Accede a un account esistente.
[CODE BLOCK]
Risposta: uguale a .
Endpoint delle menti
POST /minds
Crea una nuova mente. Restituisce la Mind Key — la salvi immediatamente,
viene mostrata una sola volta.
[CODE BLOCK]
Risposta:
[CODE BLOCK]
> [!CRITICAL]
> La viene mostrata una sola volta. Se la perde, non può recuperarla —
> deve eliminare la mente e crearne una nuova (perdendo tutte le memorie salvate).
GET /minds
Elenca tutte le menti dell'utente corrente.
[CODE BLOCK]
Risposta:
[CODE BLOCK]
DELETE /minds/:id
Elimina una mente permanentemente.
[CODE BLOCK]
> [!WARNING]
> L'eliminazione di una mente è irreversibile. Tutte le memorie, le
> attività, la cronologia chat e gli script in quella mente vengono persi
> definitivamente. Esporti prima tramite se ha bisogno
> di un backup.
Modello multi-mente
La maggior parte degli utenti beneficia di più menti per mantenere i contesti
isolati:
[CODE BLOCK]
Usi Mind Key diverse in sessioni LLM diverse per mantenere i contesti isolati.
Sicurezza dell'account
Requisiti della password
- Minimo 6 caratteri
- Nessun massimo (usi un password manager)
- Salvata come hash bcrypt (mai in chiaro)
Scadenza JWT
I JWT scadono dopo 7 giorni. Quando scadono, chiami semplicemente
nuovamente.
Sicurezza della Mind Key
Le Mind Key non scadono mai. Se una Mind Key viene compromessa:
1. Crei una nuova mente tramite
2. Aggiorni la configurazione LLM con la nuova Mind Key
3. Elimini la mente compromessa tramite
Prossimi passi
- Autenticazione — guida auth completa
- Mind Key vs JWT — guida decisionale
- API Sharing — condivida menti con altri utenti
────────────────────────────────────────────────────────────
# Variables API
SUMMARY: Key-value store veloce per stato LLM — contatori, flag, timestamp ultimo accesso, avanzamento parziale.
KEY CONTEXT:
Auth: Mind Key
Set: POST /var { key, value }
Get: GET /var/:key
List: GET /var
Delete: DELETE /var/:key
Use case: store last-seen timestamps, counters, flags, partial workflow state
Faster than memory (PostgreSQL direct, no FTS5 indexing)
Not for: structured facts (use /memory), long content (use /script)
Variables API
La Variables API è un key-value store veloce per stato effimero. A differenza
delle memorie (che sono indicizzate, ricercabili e strutturate), le variabili
sono ottimizzate per accesso rapido in lettura/scrittura — perfette per
contatori, flag e stato di sessione.
Endpoint
POST /var
Imposta o aggiorna una variabile.
[CODE BLOCK]
GET /var/:key
Ottiene una singola variabile.
[CODE BLOCK]
Risposta:
[CODE BLOCK]
GET /var
Elenca tutte le variabili.
[CODE BLOCK]
DELETE /var/:key
Elimina una variabile.
[CODE BLOCK]
Quando usare le variabili rispetto alla memoria
| Caso d'uso | Usi |
|----------|-----|
| Nome utente, preferenze | Memoria (ricercabile, strutturata) |
| Timestamp ultima sessione | Variabile (stato effimero) |
| Contatore (es. messaggi inviati) | Variabile (aggiornamenti frequenti) |
| Stato workflow ("passo 3 di 5 fatto") | Variabile (transiente) |
| Note di progetto lunghe | Memoria (indicizzata full-text) |
| Script riutilizzabili | Script store (nominati, versionati) |
Modelli comuni
Traccia l'ultima sessione
[CODE BLOCK]
Modello contatore
[CODE BLOCK]
Feature flag
[CODE BLOCK]
Prossimi passi
- Memory API — per dati strutturati e ricercabili
- Cron & Scheduler
────────────────────────────────────────────────────────────
# Webhooks API
SUMMARY: Registri callback HTTP per eventi memory, chat e task — riceva notifiche quando i dati cambiano.
KEY CONTEXT:
Auth: Mind Key
Register: POST /webhooks { url, events, secret? }
List: GET /webhooks
Get: GET /webhooks/:id
Update: PUT /webhooks/:id { url?, events?, secret?, enabled? }
Delete: DELETE /webhooks/:id
Events: memory.*, memory.store, memory.update, memory.delete, chat.*, chat.message_received, task.*, task.created, task.completed
Secret: HMAC-SHA256 signed payload, sent in X-Synapse-Signature header
Pattern: register webhook → receive POST → process event → call Synapse API
Webhooks API
I webhook permettono di ricevere callback HTTP quando si verificano eventi in
Synapse. Perfetti per attivare automazione esterna, inviare notifiche o
sincronizzare con altri sistemi.
Endpoint
POST /webhooks
Registra un nuovo webhook.
[CODE BLOCK]
Risposta:
[CODE BLOCK]
GET /webhooks
Elenca tutti i webhook della mente corrente.
[CODE BLOCK]
GET /webhooks/:id
Ottiene un singolo webhook.
[CODE BLOCK]
PUT /webhooks/:id
Aggiorna un webhook (URL, eventi, secret o flag enabled).
[CODE BLOCK]
DELETE /webhooks/:id
Elimina un webhook.
[CODE BLOCK]
Tipi di evento
| Pattern | Si attiva quando |
|---------|------------|
| | Qualsiasi evento memory |
| | Nuova memoria salvata |
| | Memoria aggiornata |
| | Memoria eliminata |
| | Qualsiasi evento chat |
| | Nuovo messaggio dall'umano |
| | Qualsiasi evento task |
| | Nuova attività creata |
| | Attività contrassegnata come completata |
| | Tutti gli eventi |
Payload del webhook
Quando si verifica un evento, Synapse invia una POST alla sua URL:
[CODE BLOCK]
Verifica della firma
Se imposta un , Synapse firma ogni payload con HMAC-SHA256:
[CODE BLOCK]
Verifichi nel suo handler:
[CODE BLOCK]
Modello: sync in tempo reale
[CODE BLOCK]
Prossimi passi
- Cron & Scheduler
- Guida automazione webhook
## CATEGORIA: INTEGRAZIONE MCP
Integrazione con Claude, Cursor e altri client MCP.
────────────────────────────────────────────────────────────
# MCP in Claude Code
SUMMARY: Usi gli strumenti di Synapse dall'agente terminale Claude Code — memoria persistente per le sessioni di coding.
KEY CONTEXT:
Claude Code config: ~/.claude/config.json (or via `claude mcp add` command)
Command: npx -y synapse-mcp-api@latest
Env: SYNAPSE_MIND_KEY (required), SYNAPSE_URL (optional)
Alternative: `claude mcp add synapse -- npx -y synapse-mcp-api@latest`
Then: set SYNAPSE_MIND_KEY env var in your shell
Test: in claude code, type "recall all my memories"
MCP in Claude Code
Claude Code è l'agente di coding da terminale di Anthropic. Con Synapse MCP,
Claude Code ottiene memoria persistente tra le sessioni di coding — ricorda
il contesto dei progetti, le decisioni passate e i pattern del codebase.
Configurazione
Metodo 1: comando CLI (consigliato)
[CODE BLOCK]
Metodo 2: modifica il file di configurazione
Modifichi :
[CODE BLOCK]
Verifica del funzionamento
Avvii Claude Code:
[CODE BLOCK]
Nel prompt di Claude Code, digiti:
[CODE BLOCK]
Claude dovrebbe richiamare e rispondere con le memorie memorizzate.
Pattern comuni
Persistenza del contesto di progetto
All'inizio di una sessione di coding:
[CODE BLOCK]
Claude richiama , vede l'elenco dei progetti e riprende il lavoro
da dove era rimasto.
Decisioni sul codebase
Quando si prende una decisione architetturale:
[CODE BLOCK]
Claude richiama con categoria e priorità .
Evitare gli errori passati
[CODE BLOCK]
Claude cerca le memorie con categoria e le ricorda degli errori passati.
Tracciamento delle attività
[CODE BLOCK]
Claude richiama e l'attività persiste tra le sessioni.
Profili degli strumenti
Per sessioni di coding in cui non servono tutti i 119 strumenti:
[CODE BLOCK]
Risoluzione dei problemi
Il server MCP non si avvia
[CODE BLOCK]
Mind Key non riconosciuta
[CODE BLOCK]
Claude Code non vede gli strumenti
- Riavvii Claude Code dopo le modifiche alla configurazione
- Controlli per verificare che Synapse sia registrato
- Veda Risoluzione dei problemi MCP
Prossimi passi
- Configurazione di Claude Desktop
- Configurazione di Cursor
- Guida agente LLM persistente
────────────────────────────────────────────────────────────
# MCP in Claude Desktop
SUMMARY: Colleghi Synapse a Claude Desktop in 2 minuti. Claude ottiene 79 strumenti Synapse in modo nativo.
KEY CONTEXT:
Config file: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
%APPDATA%\Claude\claude_desktop_config.json (Windows)
MCP server command: npx -y synapse-mcp-api@latest
Env vars: SYNAPSE_MIND_KEY (required), SYNAPSE_URL (optional, default https://synapse.schaefer.zone)
After config: restart Claude Desktop, check for 🔌 icon with "79 tools"
Test: type "memory_recall aufrufen" in a new chat
Troubleshooting: Node.js ≥ 18, check Mind Key, see /docs/mcp/troubleshooting
MCP in Claude Desktop
Claude Desktop è l'app desktop di Anthropic per macOS e Windows. Con il
server MCP di Synapse configurato, Claude ottiene accesso nativo a tutti i 79
strumenti di Synapse — può memorizzare memorie, richiamarle, gestire attività,
chattare e molto altro.
Prerequisiti
- App Claude Desktop (macOS o Windows)
- Node.js 18+ installato ()
- La propria Mind Key di Synapse
Passaggio 1: aprire il file di configurazione
- macOS:
- Windows:
Se il file non esiste, lo crei.
Passaggio 2: aggiungere il server MCP di Synapse
[CODE BLOCK]
> [!TIP]
> Se ha già altri server MCP configurati, aggiunga semplicemente il blocco
> all'interno dell'oggetto esistente.
Passaggio 3: riavviare Claude Desktop
1. Chiuda completamente Claude Desktop (Cmd+Q su macOS, non solo la finestra)
2. Riapra Claude Desktop
3. Inizi una nuova chat
4. Cerchi l'icona della spina 🔌 in basso a sinistra — dovrebbe indicare "79 tools"
Passaggio 4: testare
In una nuova chat, digiti:
[CODE BLOCK]
Claude dovrebbe richiamare lo strumento e rispondere con un
riassunto delle memorie memorizzate (oppure "No memories yet" se la mente è
vuota).
Strumenti disponibili (selezione)
| Strumento | Descrizione |
|------|-------------|
| | Richiama tutte le memorie |
| | Memorizza una nuova memoria |
| | Cerca nelle memorie |
| | Elenca le attività |
| | Crea un'attività |
| | Controlla i nuovi messaggi |
| | Risponde a un messaggio |
| | Apre una scheda del browser |
| | Elenca i computer registrati |
Elenco completo: Cos'è MCP?
Risoluzione dei problemi
Nessuno strumento appare in Claude Desktop
1. Verifichi la versione di Node.js: (deve essere ≥ 18)
2. Controlli che il file di configurazione sia JSON valido (nessuna virgola finale)
3. Riavvii completamente Claude Desktop (Cmd+Q, non solo chiuda)
4. Controlli i log di Claude Desktop: (macOS)
Errore "Mind Key invalid"
- Verifichi che inizi con
- Ottenga una nuova key tramite (richiede JWT da )
- Nessun apice attorno alla key nel JSON
npx non trovato
- Installi Node.js 18+:
- Riavvii il terminale dopo l'installazione
- Su macOS con Homebrew:
Gli strumenti appaiono ma le chiamate falliscono
- Controlli che sia raggiungibile:
- Verifichi che la Mind Key funzioni:
- Veda Risoluzione dei problemi MCP
Profili degli strumenti (risparmio token)
Se sta usando un LLM più piccolo o vuole risparmiare token di contesto, imposti
un profilo di strumenti:
[CODE BLOCK]
Profili: (8 strumenti), (25), (119, predefinito).
Prossimi passi
- Configurazione di Claude Code
- Configurazione di Cursor
- Risoluzione dei problemi MCP
────────────────────────────────────────────────────────────
# MCP in Continue.dev
SUMMARY: Colleghi Synapse a Continue.dev — assistente di coding AI open-source per VS Code e JetBrains.
MCP in Continue.dev
Continue.dev è un assistente di coding AI open-source per VS Code e IDE
JetBrains. Con Synapse MCP, Continue ottiene memoria persistente tra le
sessioni.
Prerequisiti
- VS Code o IDE JetBrains
- Estensione Continue.dev installata
- Node.js 18+
- La propria Mind Key di Synapse
Configurazione
Passaggio 1: aprire la configurazione di Continue
In VS Code o JetBrains:
1. Apra la barra laterale dell'estensione Continue
2. Clicchi sull'icona dell'ingranaggio → "Open config.json"
Oppure modifichi direttamente .
Passaggio 2: aggiungere il server MCP di Synapse
[CODE BLOCK]
Passaggio 3: ricaricare Continue
Ricarichi la finestra di VS Code (Cmd+Shift+P → "Reload Window") o riavvii il proprio IDE.
Verifica del funzionamento
Nella chat di Continue:
[CODE BLOCK]
Continue dovrebbe richiamare e rispondere con le memorie memorizzate.
Pattern comuni
Contesto di progetto
[CODE BLOCK]
Continue richiama , vede le memorie di progetto e riprende il
lavoro da dove era rimasto.
Pattern di code review
[CODE BLOCK]
Continue trova i pattern di code review memorizzati e li applica.
Memoria di pair programming
[CODE BLOCK]
Continue lo memorizza come memoria .
Risoluzione dei problemi
Il server MCP non si connette
1. Controlli che sia JSON valido
2. Verifichi Node.js:
3. Controlli il pannello di output di Continue (View → Output → Continue)
4. Riavvii l'IDE
Gli strumenti non appaiono
- Verifichi che la versione di Continue supporti MCP (≥ 0.9.x)
- Controlli che la variabile d'ambiente sia impostata nella configurazione
- Cerchi errori MCP nei log di Continue
Prossimi passi
- Configurazione di Claude Desktop
- Client MCP personalizzato
────────────────────────────────────────────────────────────
# MCP in Cursor
SUMMARY: Colleghi Synapse all'IDE Cursor per una memoria di progetto persistente tra le sessioni di coding.
MCP in Cursor
Cursor è un IDE basato sull'AI, fondato su VS Code. Con Synapse MCP, Cursor
ottiene memoria persistente tra le sessioni — ricorda le decisioni di
progetto, i pattern del codebase e le sessioni di debug precedenti.
Prerequisiti
- IDE Cursor installato ()
- Node.js 18+
- La propria Mind Key di Synapse
Configurazione
Passaggio 1: aprire le impostazioni di Cursor
In Cursor:
1. Apra le Impostazioni (Cmd+, su macOS, Ctrl+, su Windows/Linux)
2. Cerchi "MCP" o navighi in
Passaggio 2: aggiungere il server MCP di Synapse
Clicchi su "Add MCP Server" e configuri:
| Campo | Valore |
|-------|-------|
| Name | |
| Type | |
| Command | |
| Env | |
Passaggio 3: modificare config.json direttamente (alternativa)
Cursor memorizza la configurazione MCP in :
[CODE BLOCK]
Passaggio 4: riavviare Cursor
Riavvii completamente Cursor (Cmd+Q e riapertura su macOS).
Verifica del funzionamento
Nel pannello chat di Cursor (Cmd+L):
[CODE BLOCK]
Cursor dovrebbe richiamare e rispondere con le memorie memorizzate.
Pattern comuni
Onboarding di progetto
All'apertura di un nuovo progetto:
[CODE BLOCK]
Cursor richiama e riprende il lavoro da dove era rimasto.
Decisioni architetturali
[CODE BLOCK]
Cursor lo memorizza come memoria con priorità .
Cronologia di debug
[CODE BLOCK]
Cursor cerca le memorie e le ricorda delle correzioni passate.
Pattern di codice tra sessioni
[CODE BLOCK]
Cursor trova le memorie relative alle implementazioni di autenticazione fatte in passato.
Risoluzione dei problemi
Il server MCP non si connette
1. Verifichi Node.js: (≥ 18)
2. Testi il server MCP: (dovrebbe avviarsi senza errori)
3. Controlli i log MCP di Cursor (View → Output → MCP)
4. Riavvii completamente Cursor
Gli strumenti non appaiono
- Controlli che sia JSON valido
- Verifichi che la variabile d'ambiente sia impostata
- Controlli che la versione di Cursor supporti MCP (≥ 0.42)
Mind Key non valida
[CODE BLOCK]
Prossimi passi
- Configurazione di Claude Desktop
- Configurazione di Continue.dev
- Guida agente LLM persistente
────────────────────────────────────────────────────────────
# Costruire un client MCP personalizzato
SUMMARY: Si connetta al server MCP di Synapse dalla propria applicazione utilizzando l'SDK MCP ufficiale.
Costruire un client MCP personalizzato
Se sta costruendo la propria applicazione LLM, può connettersi al server MCP
di Synapse direttamente utilizzando l'SDK MCP ufficiale. In questo modo la
sua app avrà accesso a tutti i 79 strumenti di Synapse.
SDK
| Linguaggio | Pacchetto |
|----------|---------|
| TypeScript/JavaScript | |
| Python | |
Esempio TypeScript
Installazione
[CODE BLOCK]
Connessione tramite stdio
[CODE BLOCK]
Connessione tramite HTTP/SSE (remoto)
[CODE BLOCK]
Esempio Python
Installazione
[CODE BLOCK]
Connessione tramite stdio
[CODE BLOCK]
Profili degli strumenti
Quando si connette, può richiedere un profilo di strumenti specifico tramite
l'header (HTTP/SSE) o la variabile d'ambiente
(stdio):
[CODE BLOCK]
Gestione degli errori
[CODE BLOCK]
Casi d'uso
- Assistenti AI personalizzati — costruisca il proprio agente con memoria persistente
- Automazione dei flussi di lavoro — concatena strumenti Synapse in flussi personalizzati
- Pipeline di dati — estrae memorie, trasforma, carica altrove
- Dashboard di monitoraggio — visualizza statistiche delle memorie, cronologia chat, attività
Prossimi passi
- Specifica MCP
- Repository Synapse MCP
- Panoramica API
────────────────────────────────────────────────────────────
# Risoluzione dei problemi MCP
SUMMARY: Risolve i problemi comuni di integrazione MCP — server che non si avvia, strumenti che non appaiono, errori di autenticazione.
KEY CONTEXT:
Common issues:
1. Node.js < 18 → upgrade to 18+
2. Mind Key invalid → check format (mk_...), get fresh via POST /minds
3. npx not found → install Node.js
4. Tools not appearing → restart client, check config JSON validity
5. SYNAPSE_URL unreachable → curl /health to verify
6. MCP server crashes → check logs, run npx manually to see error
Debug steps: run `npx -y synapse-mcp-api@latest` manually, check stderr
Logs: Claude Desktop ~/Library/Logs/Claude/mcp.log, Cursor ~/.cursor/logs/
Risoluzione dei problemi MCP
Problemi comuni e soluzioni nell'integrazione di Synapse MCP con il proprio
client LLM.
Lista di controllo diagnostica rapida
1. ✅ Node.js 18+ installato? ()
2. ✅ La Mind Key inizia con ? (non JWT )
3. ✅ L'API di Synapse è raggiungibile? ()
4. ✅ La Mind Key funziona? ()
5. ✅ Il file di configurazione è JSON valido? (nessuna virgola finale, nessun commento)
6. ✅ Il client è stato riavviato dopo la modifica della configurazione?
7. ✅ Il server MCP si avvia manualmente? ()
Problema: nessuno strumento appare nel client
Sintomi
- Claude Desktop / Cursor / Continue mostra 0 strumenti
- Nessuna icona 🔌 o voce "synapse" nell'elenco dei server MCP
Soluzioni
1. Riavvi completamente il client — Cmd+Q su macOS (non solo chiuda la finestra)
2. Controlli la posizione del file di configurazione:
- Claude Desktop macOS:
- Claude Desktop Windows:
- Cursor:
- Continue:
3. Validi il JSON — incolli la configurazione in
4. Controlli i log del client per errori MCP:
- Claude Desktop: (macOS)
- Cursor: View → Output → MCP
5. Eseguia il server MCP manualmente per vedere gli errori di avvio:
[CODE BLOCK]
Problema: errore "Mind Key invalid"
Sintomi
- Gli strumenti appaiono ma le chiamate falliscono con "401 Unauthorized"
- Errore: "Mind Key fehlt oder ungültig"
Soluzioni
1. Verifichi il formato della Mind Key — inizia con , circa 40 caratteri
2. Testi direttamente:
[CODE BLOCK]
3. Controlli che la variabile d'ambiente sia impostata — per il trasporto
stdio, la variabile deve trovarsi nella configurazione del server MCP, non
nella shell
4. Ottenga una nuova Mind Key:
[CODE BLOCK]
Problema: npx non trovato
Sintomi
- Errore: "npx: command not found"
- Il server MCP non si avvia
Soluzioni
1. Installi Node.js 18+:
- macOS: o scarichi da
- Linux:
- Windows: scarichi da
2. Riavvii il terminale dopo l'installazione
3. Verifichi:
Problema: SYNAPSEURL non raggiungibile
Sintomi
- Il server MCP si avvia ma le chiamate agli strumenti vanno in timeout
- Errore: "fetch failed" o "ECONNREFUSED"
Soluzioni
1. Testi la connettività:
[CODE BLOCK]
2. Controlli il firewall aziendale — potrebbe bloccare l'HTTPS in uscita
3. Provi un URL alternativo:
- Produzione:
- Server MCP:
4. Per istanze self-hosted: si assicuri che la propria istanza Synapse sia in esecuzione e accessibile
Problema: il server MCP si blocca
Sintomi
- Il server MCP esce immediatamente dopo l'avvio
- I log del client mostrano "MCP server disconnected"
Soluzioni
1. Lo esegua manualmente per vedere l'errore:
[CODE BLOCK]
2. Controlli i conflitti di porta — il server MCP usa la porta 13100 per impostazione predefinita
3. Pulisca la cache di npx:
[CODE BLOCK]
4. Aggiorni all'ultima versione:
[CODE BLOCK]
Problema: le chiamate agli strumenti restituiscono 429
Sintomi
- Errore: "Rate limit exceeded"
Soluzioni
Non dovrebbe succedere con MCP (usa l'autenticazione tramite header, nessun
rate limit). Se succede:
1. Controlli se sta usando da qualche parte — passi all'autenticazione tramite header
2. Verifichi — si assicuri che punti all'istanza corretta
3. Contatti l'assistenza se il problema persiste
Problema: gli strumenti appaiono ma non funzionano
Sintomi
- Strumenti elencati nel client
- La chiamata a uno strumento restituisce un errore o nessun risultato
Soluzioni
1. Controlli il nome dello strumento — deve essere esatto (es. , non )
2. Verifichi gli argomenti — controlli lo schema di input dello strumento
3. Testi tramite API diretta:
[CODE BLOCK]
4. Controlli lo stato di Synapse:
[CODE BLOCK]
Ottenere assistenza
Se nessuna delle soluzioni precedenti risolve il problema:
1. Controlli le issue esistenti:
2. Apra una nuova issue con:
- Versione del server MCP ()
- Nome e versione del client
- Sistema operativo
- Estratti di log rilevanti
- Passaggi per riprodurre il problema
Prossimi passi
- Configurazione di Claude Desktop
- Configurazione di Claude Code
- Errori API
────────────────────────────────────────────────────────────
# Cos'è MCP?
SUMMARY: Il Model Context Protocol permette agli LLM di richiamare strumenti esterni. Synapse espone 79 strumenti tramite il server MCP ufficiale.
KEY CONTEXT:
MCP = Model Context Protocol (Anthropic, 2024). Open standard for LLM-tool integration.
Synapse has official MCP server: synapse-mcp-api (npm package, npx -y synapse-mcp-api@latest)
79 tools exposed: 22 memory, 7 chat, 8 scheduler, 4 tasks, 5 scripts, 9 computers, 4 push, 5 user, 3 utility
3 transports: stdio (local), HTTP/SSE (remote), WebSocket (mobile)
Supported clients: Claude Desktop, Claude Code, Cursor, Continue, Cline, any MCP-compatible client
Tool Profiles (v1.4.0): minimal (8 tools), standard (25), full (119) — controlled via MCP_PROFILE env or Mcp-Tool-Profile header
Cos'è MCP?
Il Model Context Protocol (MCP) è uno standard aperto creato da Anthropic
(2024) che consente agli LLM di richiamare strumenti esterni in modo
strutturato. Invece di incollare la documentazione dell'API nel prompt, si
registrano gli strumenti presso il server MCP e l'LLM li richiama quando
necessario — come il function calling, ma standardizzato e indipendente dal
client.
Server MCP di Synapse
Synapse include un server MCP ufficiale ( su npm) che espone
79 strumenti per tutte le funzionalità di Synapse:
| Categoria | Strumenti | Numero |
|----------|-------|-------|
| Memory | recall, list, store, search, semantic-search, update, delete, bulk-delete, stats, unverified, contradictions, audit, related, by-tag, diff, expiring, health, sync, embed-batch, verify, unverify, mind-export | 22 |
| Chat | poll, reply, status, history, unread, send, upload | 7 |
| Scheduler | cronlist, croncreate, crondelete, crontoggle, varlist, varget, varset, vardelete | 8 |
| Tasks | tasklist, taskget, taskcreate, taskupdate | 4 |
| Scripts | scriptlist, scriptget, scriptinfo, scriptstore, scriptdelete | 5 |
| Computers | computerlist, computerget, installcode, screenshot, commandqueue, commandstatus, commandslist, disable, delete | 9 |
| Push | vapidpublickey, subscribe, unsubscribe, test | 4 |
| User/Mind | register, login, mindslist, mindcreate, minddelete | 5 |
| Utility | time, calc, random | 3 |
| Visualization | graph, tags, compact | 3 |
| Sharing | share, list, revoke | 3 |
| Webhooks | register, list, get, update, delete | 5 |
| Browser | new, navigate, click, type, screenshot, close | 6 |
| Totale | | 79+ |
Come funziona
[CODE BLOCK]
1. Si configura il client LLM (Claude Desktop, Cursor, ecc.) per utilizzare il server MCP di Synapse
2. Il client avvia il server MCP (tramite )
3. Il server MCP si connette all'API di Synapse utilizzando la propria Mind Key
4. L'LLM vede tutti i 79 strumenti come funzioni native che può richiamare
5. Quando l'LLM deve ricordare qualcosa, richiama — il server MCP lo traduce in su Synapse
Trasporti
Il server MCP di Synapse supporta tre trasporti:
stdio (locale, consigliato per desktop)
[CODE BLOCK]
HTTP/SSE (remoto, multi-tenant)
Colleghi il proprio client MCP a:
[CODE BLOCK]
WebSocket (mobile, alto volume)
[CODE BLOCK]
Profili degli strumenti (v1.4.0)
Per ridurre il consumo di token per LLM più piccoli, il server MCP supporta
tre profili di strumenti:
| Profilo | Strumenti | Token | Ideale per |
|---------|-------|--------|----------|
| | 8 (dispatch composito) | 500 | LLM self-hosted con contesto ≤8k |
| | 25 (nominati) | 2,500 | LLM di media dimensione (Claude Haiku, GPT-3.5) |
| | 119 (tutti) | 8,250 | LLM di grandi dimensioni (Claude Sonnet/Opus, GPT-4) — predefinito |
Si controlla tramite:
- Variabile d'ambiente:
- Header:
Client supportati
- Claude Desktop — app desktop di Anthropic
- Claude Code — agente di coding da terminale
- Cursor — IDE basato sull'AI
- Continue.dev — assistente di coding AI open-source
- Cline — estensione VS Code
- Qualsiasi client compatibile con MCP
Perché usare MCP invece dell'API diretta?
| Approccio | Pro | Contro |
|----------|------|------|
| API diretta | Semplice, nessuno strato aggiuntivo | L'LLM deve conoscere URL, header, autenticazione |
| MCP | L'LLM vede strumenti nativi, senza dover ricordare URL | Processo server MCP aggiuntivo |
Per la maggior parte dei casi d'uso con agenti LLM, MCP è la scelta migliore
— l'LLM non deve ricordare i percorsi dell'API o i modelli di autenticazione.
Prossimi passi
- Configurazione di Claude Desktop — configurazione in 2 minuti
- Configurazione di Claude Code — integrazione da terminale
- Client MCP personalizzato — costruirne uno proprio
## CATEGORIA: GUIDE E TUTORIAL
Guide passo-passo per scenari concreti.
────────────────────────────────────────────────────────────
# Testing automatizzato di app iOS
SUMMARY: Usi Synapse + Computer Control API per automatizzare il testing di app iOS tramite Simulator.
Testing automatizzato di app iOS
Combini il sistema di memoria di Synapse con la Computer Control API per
costruire test di app iOS guidati da LLM. L'LLM ricorda gli scenari di test,
impara dai fallimenti passati e si adatta ai cambiamenti della UI.
Architettura
[CODE BLOCK]
Prerequisiti
- Account Synapse + Mind Key
- Server MCP di Synapse configurato in Claude Desktop
- iOS Simulator con installato
- Computer registrato in Synapse (veda Computer Control API)
Passo 1: Registri il computer Simulator
Sul Mac che esegue l'iOS Simulator:
[CODE BLOCK]
Passo 2: Memorizzi gli scenari di test in memoria
Memorizzi gli scenari di test riutilizzabili come memorie:
[CODE BLOCK]
Passo 3: Esecuzione del test guidata da LLM
In Claude Desktop (con Synapse MCP configurato):
[CODE BLOCK]
Claude:
1. Chiamerà per trovare la memoria
2. Chiamerà per vedere lo stato corrente
3. Eseguirà ogni passo tramite (click, type)
4. Verificherà i risultati tramite schermate
5. Memorizzerà eventuali fallimenti come memorie
Passo 4: Test self-healing
Quando un test fallisce, memorizzi il fallimento e il recupero:
[CODE BLOCK]
La prossima volta che l'LLM esegue il test, richiama il fallimento e applica
il recupero automaticamente.
Passo 5: Tracciamento dei risultati dei test
Tracci le esecuzioni dei test come attività:
[CODE BLOCK]
Comandi comuni
| Azione | Comando |
|--------|---------|
| Avvia Simulator | |
| Schermata | (tramite Synapse MCP) |
| Tap a (x,y) | |
| Digita testo | |
| Premi Home | |
Best practice
> [!TIP]
> - Memorizzi le coordinate UI come memorie — la UI cambia, ma l'LLM può reimparare
> - Usi le etichette di accessibilità — più stabili delle coordinate
> - Memorizzi i dati di test separatamente — usi variabili per username, password
> - Esegua i test in stato pulito — reset del Simulator tra le esecuzioni
> - Logghi le schermate per i fallimenti — utili per il debug
Prossimi passi
- Test self-healing
- Computer Control API
- Best practice per la memoria
────────────────────────────────────────────────────────────
# Backup e ripristino
SUMMARY: Esporti le sue memorie per backup, migrare tra menti, ripristinare dopo perdita di dati.
Backup e ripristino
Synapse fornisce export/import completo per backup della memoria, migrazione e
disaster recovery. Questa guida copre le operazioni essenziali.
Export
Export completo della mente
Esporti tutte le memorie in una mente come JSON:
[CODE BLOCK]
Formato della risposta:
[CODE BLOCK]
Export incrementale (diff)
Esporti solo le memorie modificate da un timestamp:
[CODE BLOCK]
Risposta:
[CODE BLOCK]
Backup automatizzati
Pianifichi backup giornalieri tramite cron:
[CODE BLOCK]
> [!NOTE]
> L'endpoint cron riceve la risposta ma non la memorizza. Per backup reali,
> punti il cron al suo server di backup che salva la risposta.
Meglio: script di backup esterno
[CODE BLOCK]
Aggiunga a crontab:
[CODE BLOCK]
Ripristino
Ripristino sulla stessa mente
[CODE BLOCK]
Ripristino su una nuova mente
[CODE BLOCK]
Script di ripristino in Python
[CODE BLOCK]
Migrazione tra menti
[CODE BLOCK]
Backup di altri dati
Non dimentichi di fare backup di:
| Tipo di dato | Endpoint |
|-----------|----------|
| Memorie | |
| Attività | |
| Script | |
| Webhook | |
| Cron job | |
| Variabili | |
| Cronologia chat | |
Verifica
Dopo il ripristino, verifichi:
[CODE BLOCK]
Best practice
> [!TIP]
> - Backup giornaliero — automatizzi con cron
> - Testi i ripristini — un backup che non può ripristinare è inutile
> - Mantenga versioni multiple — almeno 30 giorni
> - Salvi offsite — S3, Backblaze B2, ecc.
> - Cifri i backup sensibili — le memorie possono contenere PII
> - Documenti il processo di ripristino — lo dimenticherà quando le servirà
Prossimi passi
- Memory API
- Cron & Scheduler — per backup automatizzati
────────────────────────────────────────────────────────────
# Best practice per la memoria
SUMMARY: Come strutturare le memorie per richiamo efficace — categorie, chiavi, tag, priorità.
Best practice per la memoria
Come struttura le memorie determina quanto sono utili. Questa guida copre
modelli per categorizzare, taggare e dare priorità alle memorie così l'LLM può
richiamare l'informazione giusta al momento giusto.
Categorie: scelga la più specifica
| Categoria | Usi per | Esempio |
|----------|---------|---------|
| | Nome utente, ruolo, info contatto | |
| | Piaceri, dispiaceri, stile di lavoro | |
| | Fatti verificabili | |
| | Stato del progetto, decisioni | |
| | Competenze dell'utente | |
| | Errori passati da evitare | |
| | Contesto rilevante per la sessione | |
| | Note varie | |
> [!TIP]
> In caso di dubbio, usi per informazioni verificabili e per
> tutto il resto. Non ecceda con le categorie — meglio un chiaro che un
> confusionario.
Chiavi: identificatori significativi
Il campo è l'identificatore della memoria. Usi chiavi significative e
stabili:
Chiavi buone:
-
-
-
-
Chiavi cattive:
- (non significativa)
- (non descrittiva)
- (la data non aiuta il richiamo)
Convenzioni per i nomi delle chiavi
- (minuscolo con underscore)
- Prefisso con categoria: , ,
- Usi sostantivi descrittivi, non verbi
- Meno di 50 caratteri
Tag: per ricerca e filtraggio
I tag abilitano filtraggio e ricerca veloce. Aggiunga 2-5 tag per memoria:
[CODE BLOCK]
Modelli di tag
- Nomi di progetto: , ,
- Argomenti: , , ,
- Stato: , ,
- Indicatori di priorità: ,
> [!NOTE]
> I tag sono case-insensitive. Usi minuscolo per consistenza.
Priorità: sia realistico
| Priorità | Usi per | % delle memorie |
|----------|---------|---------------|
| | Identità utente, info legali, decisioni irreversibili | 5% |
| | Progetti attivi, preferenze importanti | 20% |
| | Maggior parte dei fatti, note, contesto | 65% |
| | Effimero, piace-da-sapere | 10% |
> [!WARNING]
> Non contrassegni tutto come . Se tutto è critical, nulla lo è.
> Riservi per cose che causerebbero danno reale se dimenticate.
Quando memorizzare vs non memorizzare
Memorizzi sempre
- Identità utente (nome, email, ruolo)
- Preferenze long-term
- Decisioni di progetto e ragionamento
- Errori passati e lezioni apprese
- Impegni presi con l'utente
Non memorizzi
- Stato transiente (usi variabili invece)
- Cronologia conversazione verbatim (la gestisce il sistema chat)
- Dati sensibili (password, API key)
- Fatti facilmente derivabili (data corrente, contenuto file)
- Contesto effimero (usi categoria con priorità bassa)
Aggiornare le memorie
POST con la stessa + aggiorna la memoria esistente:
[CODE BLOCK]
> [!TIP]
> Usi chiavi stabili così può aggiornare senza creare duplicati. L'LLM
> dovrebbe fare nuovamente POST della stessa chiave quando le info cambiano,
> non creare nuove memorie.
Ciclo di vita della memoria
[CODE BLOCK]
- Create: POST /memory con contesto completo
- Active: Richiama frequentemente, aggiorna come necessario
- Stale: Ancora rilevante ma non attivamente usata (priorità più bassa?)
- Archive: Imposti priorità a , mantenga per riferimento storico
- Delete: DELETE /memory/:id quando non più rilevante
Pulizia periodica
[CODE BLOCK]
Modello: ereditarietà della memoria
Per contesto gerarchico (progetto → sottoprogetto → attività):
[CODE BLOCK]
L'LLM può poi cercare per trovare tutte le memorie correlate.
Modello: log delle decisioni
Memorizzi le decisioni con il ragionamento così l'LLM non le ridiscute:
[CODE BLOCK]
Modello: evitamento degli errori
Memorizzi gli errori con istruzioni specifiche di evitamento:
[CODE BLOCK]
Anti-pattern da evitare
> [!WARNING]
> - Memorizzare log di conversazione — il sistema chat lo gestisce
> - Memorizzare file interi — usi lo script store o storage esterno
> - Memorizzare stato effimero — usi variabili
> - Memorizzare segreti — usi variabili di ambiente
> - Duplicare memorie — usi chiavi stabili
> - Eccesso di tag — 2-5 tag per memoria è ideale
> - Tutto è critical — sia realistico con le priorità
Prossimi passi
- Memory API
- Agente LLM persistente
- Strategia di tagging della memoria
────────────────────────────────────────────────────────────
# Coordinazione multi-agente
SUMMARY: Coordini più agenti LLM usando menti Synapse condivise, attività e chat.
Coordinazione multi-agente
Quando ha più agenti LLM che lavorano su attività correlate, Synapse fornisce
il layer di coordinamento — memoria condivisa, assegnazione di attività e
chat asincrona.
Modelli
Modello 1: mente condivisa (singola fonte di verità)
Tutti gli agenti condividono una Mind Key. Leggono/scrivono lo stesso store di
memoria.
[CODE BLOCK]
Caso d'uso: Piccolo team di agenti che lavora su un progetto.
Setup:
[CODE BLOCK]
Coordinazione tramite attività:
[CODE BLOCK]
Modello 2: menti specializzate (contesti isolati)
Ogni agente ha la sua mente. Comunicano tramite una mente di "coordinamento"
condivisa.
[CODE BLOCK]
Caso d'uso: Agenti con specialità diverse (coding, review, deployment).
Setup:
[CODE BLOCK]
Coordinamento tramite mente condivisa:
[CODE BLOCK]
Modello 3: hub-and-spoke (orchestratore)
Un agente orchestratore centrale assegna attività agli agenti worker.
[CODE BLOCK]
Caso d'uso: Workflow complessi con lavoro parallelo.
Implementazione:
[CODE BLOCK]
Coordinazione tramite chat
Gli agenti possono comunicare tramite il sistema chat:
[CODE BLOCK]
> [!NOTE]
> I messaggi chat sono role-tagged. Imposti role=agent per messaggi
> agente-agente, role=human per umano-agente.
Coordinazione tramite variabili
Usi variabili per coordinamento leggero (lock, flag):
[CODE BLOCK]
Best practice
> [!TIP]
> - Usi menti separate per preoccupazioni separate — non mescoli la memoria di coder e reviewer
> - Tagghi gli agenti in chat — per un indirizzamento chiaro
> - Usi attività per assegnazione lavoro — non chat (chat è per discussione)
> - Implementi idempotenza — gli agenti possono ritentare operazioni fallite
> - Logghi tutto — memorizzi le decisioni in memoria per auditabilità
Prossimi passi
- Agente LLM persistente
- LLM Cookbook
- Automazione webhook
────────────────────────────────────────────────────────────
# Costruire un agente LLM persistente
SUMMARY: Guida passo-passo per costruire un agente LLM che ricorda tra le sessioni usando Synapse.
Panoramica
Questa guida la accompagna nella costruzione di un agente LLM che persiste il
contesto tra le sessioni usando Synapse. Alla fine, il suo agente:
- Richiamerà il contesto passato all'inizio della sessione
- Memorizzerà nuovi apprendimenti man mano che accadono
- Traccerà attività multi-step tra le sessioni
- Comunicherà con gli umani tramite chat asincrona
Architettura
[CODE BLOCK]
Passo 1: Configuri la Mind Key
[CODE BLOCK]
Passo 2: Protocollo di inizio sessione
All'inizio di ogni sessione, richiami tutte le memorie:
[CODE BLOCK]
Passo 3: Memorizzi nuovi apprendimenti
Ogni volta che l'agente impara qualcosa che vale la pena ricordare:
[CODE BLOCK]
Passo 4: Gestione delle attività
Tracci lavoro multi-step tra le sessioni:
[CODE BLOCK]
Passo 5: Chat asincrona con gli umani
Eseguire il polling dei messaggi tra le chiamate agli strumenti:
[CODE BLOCK]
Passo 6: Protocollo di fine sessione
Alla fine della sessione, memorizzi il contesto finale:
[CODE BLOCK]
Modello completo
[CODE BLOCK]
Best practice
> [!TIP]
>
> - Richiami sempre prima — non inizi mai il lavoro senza caricare il contesto
> - Memorizzi proattivamente — non aspetti fino alla fine della sessione
> - Usi chiavi significative — , , non
> - Tagghi tutto — i tag alimentano ricerca e filtraggio
> - Imposti priorità realistiche — non tutto è
Prossimi passi
- LLM Cookbook — modelli pratici
- Best practice per la memoria
- Coordinazione multi-agente
────────────────────────────────────────────────────────────
# Pipeline di test self-healing
SUMMARY: Costruisca pipeline di test che imparano dai fallimenti e si adattano automaticamente usando la memoria di Synapse.
Pipeline di test self-healing
Le suite di test tradizionali si rompono quando la UI cambia. I test
self-healing usano la memoria di Synapse per imparare dai fallimenti passati e
adattarsi — riducendo test flaky e carico di manutenzione.
Concetto
[CODE BLOCK]
1. Il test viene eseguito
2. Se fallisce, memorizza il fallimento (cosa è andato storto, perché, come riparare)
3. Esecuzione successiva: richiama i fallimenti rilevanti prima di eseguire
4. Applica le correzioni note automaticamente
Implementazione
Passo 1: wrapper del test
Avvolga ogni test con recall/store di memoria:
[CODE BLOCK]
Passo 2: logica di test adattiva
All'interno del test, verifichi i fallimenti noti e applichi le correzioni:
[CODE BLOCK]
Passo 3: strategie di recupero
Memorizzi le strategie di recupero come memorie:
[CODE BLOCK]
Passo 4: integrazione CI
[CODE BLOCK]
Passo 5: dashboard di analisi dei fallimenti
[CODE BLOCK]
Best practice
> [!TIP]
> - Memorizzi i traceback — contengono la riga esatta che è fallita
> - Tagghi per nome test — abilita filtraggio veloce
> - Usi la categoria — separa dalle memorie regolari
> - Imposti priorità — i fallimenti non dovrebbero mai essere dimenticati
> - Pulizia periodica — elimini le memorie per i problemi risolti
> - Non memorizzi dati sensibili — credenziali, PII
Pattern di fallimento comuni da memorizzare
| Tipo di fallimento | Cosa memorizzare |
|--------------|---------------|
| Elemento non trovato | Selettore provato, stato della pagina, schermata |
| Timeout | Tempo di attesa, cosa si stava aspettando |
| Asserzione fallita | Valore atteso vs attuale |
| Errore di rete | URL, codice di stato, corpo della risposta |
| Permesso negato | Permesso richiesto, ruolo utente corrente |
Prossimi passi
- Testing automatizzato iOS
- Best practice per la memoria
- Cookbook recupero errori
────────────────────────────────────────────────────────────
# Automazione webhook
SUMMARY: Attivi sistemi esterni quando le memorie cambiano — sync, notifiche, automazione.
Automazione webhook
I webhook permettono di attivare sistemi esterni quando si verificano eventi di
Synapse. Questa guida copre modelli di automazione comuni.
Modelli comuni
Modello 1: notifica su memoria critica
Invii un messaggio Slack quando una memoria critica viene salvata:
[CODE BLOCK]
Registri il webhook:
[CODE BLOCK]
Modello 2: sync a sistema esterno
Sincronizzi le memorie su Notion, Obsidian o qualsiasi KB esterno:
[CODE BLOCK]
Modello 3: attivazione CI/CD
Attivi un deployment quando viene salvata una memoria "release":
[CODE BLOCK]
Modello 4: svegli l'agente al messaggio dell'umano
Attivi un'esecuzione dell'agente LLM quando un umano invia un messaggio chat:
[CODE BLOCK]
Modello 5: aggrega metriche
Tracci la crescita della memoria, l'attività chat, il completamento delle attività:
[CODE BLOCK]
Verifica della firma
Verifichi sempre le firme dei webhook per prevenire spoofing:
[CODE BLOCK]
Logica di retry
Synapse ritenta i webhook falliti con backoff esponenziale. Il suo handler
dovrebbe:
1. Restituire 200 velocemente — non faccia lavoro pesante in modo sincrono
2. Accodare lavoro — usi un sistema di job in background
3. Essere idempotente — lo stesso evento può essere consegnato due volte
[CODE BLOCK]
Debug dei webhook
Verifichi la cronologia delle consegne
Le consegne dei webhook vengono loggate. Verifichi le consegne recenti del suo
webhook:
[CODE BLOCK]
Testi il webhook manualmente
[CODE BLOCK]
Problemi comuni
| Problema | Soluzione |
|-------|-----|
| Risposte 4xx | Verifichi che il suo handler restituisca 200 |
| Risposte 5xx | Errore del server — controlli i log della sua app |
| Timeout | Restituisca 200 velocemente, accodi lavoro async |
| Consegne duplicate | Renda l'handler idempotente |
| Mancata corrispondenza della firma | Verifichi che il secret sia corretto |
Best practice
> [!TIP]
> - Verifichi sempre le firme — non salti mai questo
> - Restituisca 200 velocemente — non blocchi Synapse
> - Sia idempotente — gestisca le consegne duplicate
> - Usi eventi specifici — non
> - Monitori i fallimenti di consegna — configuri alerting
Prossimi passi
- Webhooks API
- Cron & Scheduler
- Agente LLM persistente
## CATEGORIA: CONCETTI
Architettura e concetti alla base di Synapse.
────────────────────────────────────────────────────────────
# Architettura di Synapse
SUMMARY: Come è costruito Synapse — Fastify, PostgreSQL, FTS5, embedding, server MCP.
Architettura di Synapse
Synapse è una API di memoria multi-tenant costruita su Fastify, PostgreSQL con
FTS5 e un servizio embedding opzionale per la ricerca semantica.
Architettura di alto livello
[CODE BLOCK]
Componenti principali
1. Synapse API (Fastify)
Il server HTTP principale. Gestisce:
- Endpoint REST (, , , ecc.)
- Autenticazione (Mind Key per agenti, JWT per umani)
- Rate limiting (solo auth )
- Servizio di file statici (UI web su , , ecc.)
- Dispatch dei webhook
Costruito con Fastify 5 per le prestazioni. In produzione gira sulla porta
12800.
2. PostgreSQL con FTS5
Lo store dati principale. Usa PostgreSQL con l'estensione FTS5 per la ricerca
full-text.
Tabelle chiave:
| Tabella | Scopo |
|-------|---------|
| | Account utente |
| | Scope delle menti (ciascuno ha una Mind Key) |
| | Record delle memorie con tabella virtuale FTS5 |
| | Gestione attività |
| | Cronologia chat |
| | Script persistenti |
| | Registrazioni webhook |
| | Attività pianificate |
| | Key-value store |
| | Traccia di audit |
FTS5 abilita la ricerca full-text sub-millisecond su tutti i contenuti
delle memorie. Veda Ricerca FTS5 per i dettagli.
3. Servizio Embedding (opzionale)
Per la ricerca semantica, Synapse genera embedding vettoriali del contenuto
delle memorie. Vengono salvati insieme alle memorie e usati per la ricerca di
similarità.
- Provider: configurabile (OpenAI, modello locale, ecc.)
- Salvato come colonna nella tabella
- Usato dall'endpoint
- Veda Ricerca semantica
4. Server MCP (servizio separato)
Il server MCP di Synapse gira come processo separato (porta 13100). Esso:
- Espone 79 strumenti tramite Model Context Protocol
- Supporta transport stdio, HTTP/SSE e WebSocket
- Traduce le chiamate MCP in chiamate API Synapse
- Multi-tenant: una Mind Key per sessione
5. Browser Proxy (servizio separato)
Per l'automazione del browser, un servizio separato basato su Playwright gira
sulla porta 13000. Il server MCP può chiamarlo per gli strumenti .
6. SSH Proxy (servizio separato)
Per comandi remoti via SSH, un servizio separato gira sulla porta 12900.
Modello multi-tenant
[CODE BLOCK]
Ogni mente è completamente isolata. Le Mind Key concedono accesso a esattamente
una mente. I JWT concedono accesso all'account utente (per gestire le menti).
Veda Multi-tenancy per i dettagli.
Flusso delle richieste
Richiesta di memorizzazione
[CODE BLOCK]
Richiesta di ricerca
[CODE BLOCK]
Deployment
Synapse viene deployato come container Docker. Veda :
[CODE BLOCK]
Caratteristiche di prestazione
| Operazione | Latenza | Throughput |
|-----------|---------|------------|
| Memory store | 5ms | 1000+ req/s |
| Memory recall | 20ms | 500 req/s |
| FTS5 search | 10ms | 800 req/s |
| Semantic search | 50ms | 200 req/s |
| Chat poll | 5ms | 2000 req/s |
Prossimi passi
- Modello di memoria
- Multi-tenancy
- Ricerca FTS5
────────────────────────────────────────────────────────────
# Ricerca full-text FTS5
SUMMARY: Come Synapse usa SQLite FTS5 per la ricerca full-text delle memorie sub-millisecond.
Ricerca full-text FTS5
Synapse usa FTS5 (Full-Text Search 5) per la ricerca nelle memorie veloce e
flessibile. Questa pagina spiega come funziona e come usarlo efficacemente.
Cos'è FTS5?
FTS5 è un'estensione SQLite (disponibile anche in PostgreSQL tramite estensioni)
che fornisce funzionalità di ricerca full-text. Essa:
- Indicizza il contenuto testuale per la ricerca veloce per parola chiave
- Supporta operatori booleani (AND, OR, NOT)
- Supporta la corrispondenza di frasi con virgolette
- Supporta la corrispondenza di prefisso con
- Classifica i risultati per rilevanza
Synapse usa FTS5 per indicizzare tutti i contenuti delle memorie, abilitando
ricerca sub-millisecond su migliaia di memorie.
Come Synapse usa FTS5
Quando fa :
1. Il contenuto della memoria viene salvato nella tabella
2. Il contenuto viene anche inserito nella tabella virtuale FTS5
3. FTS5 tokenizza e indicizza automaticamente il contenuto
Quando fa :
1. Synapse analizza la query usando la sintassi FTS5
2. Esegue un contro l'indice FTS5
3. Filtra per (isolamento tenant)
4. Restituisce i risultati classificati
Sintassi delle query
Ricerca semplice per parola chiave
[CODE BLOCK]
Restituisce le memorie che contengono "docker".
Più parole chiave (AND implicito)
[CODE BLOCK]
Restituisce le memorie che contengono SIA "docker" E "swarm".
Corrispondenza di frase
[CODE BLOCK]
Restituisce le memorie che contengono la frase esatta "docker swarm".
Corrispondenza di prefisso
[CODE BLOCK]
Restituisce le memorie che contengono parole che iniziano con "docker" (es.
"dockers", "dockerfile", "dockerize").
OR booleano
[CODE BLOCK]
Restituisce le memorie che contengono "docker" OR "kubernetes".
NOT booleano
[CODE BLOCK]
Restituisce le memorie che contengono "docker" ma NON "swarm".
Raggruppamento
[CODE BLOCK]
Restituisce le memorie che contengono "docker" o "kubernetes", ma non "test".
Esempi pratici
Trova memorie su un progetto
[CODE BLOCK]
Trova frase esatta
[CODE BLOCK]
Escludi memorie di test
[CODE BLOCK]
Trova per tecnologia
[CODE BLOCK]
Classificazione
FTS5 classifica i risultati per rilevanza usando l'algoritmo BM25. Fattori:
- Frequenza del termine (quanto spesso appare il termine)
- Inverse document frequency (termini più rari ottengono classifiche più alte)
- Lunghezza del documento (documenti più corti con il termine ottengono classifica più alta)
- Peso della colonna (title > content)
I risultati vengono restituiti in ordine di classifica (più rilevanti per primi).
Prestazioni
| Operazione | Latenza |
|-----------|---------|
| Ricerca su 100 memorie | < 5ms |
| Ricerca su 1.000 memorie | < 10ms |
| Ricerca su 10.000 memorie | < 25ms |
| Ricerca su 100.000 memorie | < 100ms |
FTS5 è altamente ottimizzato per workload con molti read.
Limitazioni
Stemming
FTS5 non fa stemming per default. "running" e "run" sono termini diversi.
Soluzione: Usi la corrispondenza di prefisso:
Tolleranza ai refusi
FTS5 non supporta il fuzzy matching. Un refuso non restituirà risultati.
Soluzione: Usi la ricerca semantica () per
corrispondenza concettuale.
Stop word
Le parole comuni (the, a, an, is) vengono indicizzate ma potrebbero non essere
utili per la ricerca. FTS5 le gestisce automaticamente.
FTS5 vs ricerca semantica
| Aspetto | FTS5 | Ricerca semantica |
|--------|------|-----------------|
| Velocità | Sub-millisecond | 50-100ms |
| Corrispondenza | Parole chiave esatte | Concettuale |
| Tolleranza ai refusi | Nessuna | Qualcuna |
| Stemming | Nessuno | Implicito |
| Richiede embedding | No | Sì |
| Ideale per | Termini specifici | Concetti |
Usi FTS5 quando conosce le parole chiave. Usi la ricerca semantica quando vuole
"memorie su X" dove X è descritto diversamente.
Best practice
> [!TIP]
> - Usi termini specifici — "docker swarm" batte "container orchestration"
> - Usi virgolette per le frasi — garantisce corrispondenza di frase
> - Usi il prefisso per le variazioni — cattura "deploy", "deployment", "deploying"
> - Escluda il rumore — filtra le memorie di test
> - Combini con i tag — restringe i risultati
Prossimi passi
- Ricerca semantica
- Memory API
- Best practice per la memoria
────────────────────────────────────────────────────────────
# Il modello di memoria
SUMMARY: Come sono strutturate le memorie — categorie, chiavi, tag, priorità, sorgenti, verifica.
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
[CODE BLOCK]
Campi
| Campo | Tipo | Obbligatorio | Descrizione |
|-------|------|----------|-------------|
| | string | auto | ID univoco (memxxx) |
| | enum | ✅ | Una delle 8 categorie |
| | string | ✅ | Identificatore stabile (usato per gli aggiornamenti) |
| | string | ✅ | Il contenuto della memoria (qualsiasi testo) |
| | string[] | – | Per ricerca e filtraggio |
| | enum | – | low, normal, high, critical (predefinito: normal) |
| | enum | auto | user, agent (chi l'ha salvata) |
| | bool | auto | Un umano l'ha verificata? |
| | float | – | 0.0 a 1.0 (predefinito: 1.0 per user, 0.7 per agent) |
| | timestamp | – | Quando dimenticare questa memoria |
| | string | auto | Quale mente la possiede |
| | timestamp | auto | Prima memorizzazione |
| | timestamp | auto | Ultima modifica |
Categorie
Otto categorie coprono i casi d'uso comuni degli agenti LLM:
| Categoria | Scopo | Contenuto di esempio |
|----------|---------|-----------------|
| | Chi è l'utente | "User is Michael Schäfer, software engineer in Berlin" |
| | Preferenze utente | "Prefers concise technical responses" |
| | Fatti verificabili | "Office is in Berlin, timezone Europe/Berlin" |
| | Stato del progetto | "Synapse v1.5.0 deployed, working on v1.6.0 docs" |
| | Competenze dell'utente | "Advanced Python, 10+ years" |
| | Errori passati | "Forgot to bump npm version — CI failed" |
| | Contesto di sessione | "Currently reviewing PR #42" |
| | Note varie | "Try Redis for caching next sprint" |
Chiavi: identificatori stabili
Il campo è critico — è come aggiorna le memorie senza creare duplicati.
[CODE BLOCK]
Regole delle chiavi:
- Devono essere uniche all'interno di (category, mind)
- Usi
- Prefissi con categoria per chiarezza: ,
- Le mantenga stabili — non cambi le chiavi dopo la creazione
Tag: per la ricerca
I tag abilitano filtraggio e ricerca veloce:
[CODE BLOCK]
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 |
|----------|-------------|-----------------|
| | Identità, legale, irreversibile | Sempre in cima al richiamo |
| | Progetti attivi, preferenze chiave | In evidenza nel richiamo |
| | Maggior parte delle memorie (predefinito) | Ordine di richiamo standard |
| | Effimero, piace-da-sapere | Potrebbe essere riassunto |
ordina per priorità (critical prima), poi per recency.
Sorgente: user vs agent
Le memorie sono contrassegnate con :
- — salvate da un umano (tramite JWT o UI umana)
- — salvate da un agente LLM (tramite Mind Key)
Questo influenza:
- Verifica: le memorie sono auto-verificate, quelle no
- Confidenza: predefinito a 1.0, a 0.7
- Richiamo: contrassegna le memorie non verificate con "(unverified)"
> [!NOTE]
> Tratti le memorie con sorgente con scetticismo appropriato. Potrebbero
> essere dedotte o assunte anziché dichiarate direttamente dall'utente.
Verifica
Il flag indica che un umano ha confermato la memoria:
- memorie : auto-verificate ()
- memorie : non verificate per default ()
Verifichi le memorie tramite:
[CODE BLOCK]
> [!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 (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:
[CODE BLOCK]
Scadenza
Imposti per memorie time-sensitive:
[CODE BLOCK]
Le memorie scadute non vengono restituite da (ma esistono
ancora nel DB). Usi per vedere le memorie in
scadenza prossima.
Ciclo di vita della memoria
[CODE BLOCK]
Comportamento di richiamo
restituisce un riassunto in testo semplice ottimizzato per
il contesto LLM:
[CODE BLOCK]
- Ordinate per priorità (critical → low), poi per recency
- Le memorie non verificate sono contrassegnate con
- Tag inclusi per contesto
- Testo semplice (nessun parsing JSON necessario)
Prossimi passi
- Memory API
- Best practice per la memoria
- Ricerca FTS5
────────────────────────────────────────────────────────────
# Multi-tenancy e isolamento
SUMMARY: Come Synapse isola i dati tra utenti e menti — confini di sicurezza spiegati.
Multi-tenancy e isolamento
Synapse è multi-tenant: utenti multipli, ciascuno con menti multiple, completamente
isolati tra loro. Questa pagina spiega il modello di isolamento.
Gerarchia dei tenant
[CODE BLOCK]
Livelli di isolamento
Livello 1: isolamento utente
Ogni account utente è isolato. Alice non può:
- Vedere le menti di Bob
- Accedere alle memorie di Bob (nemmeno con il suo JWT)
- Elencare le informazioni dell'account di Bob
Imposto da: colonna su tutte le tabelle, il JWT contiene ,
tutte le query filtrano per .
Livello 2: isolamento mente
All'interno di un utente, ogni mente è isolata. La Mente A non può:
- Vedere le memorie della Mente B
- Accedere alle attività, chat, script della Mente B
Imposto da: colonna su tutte le tabelle dati, la Mind Key contiene
, tutte le query filtrano per .
> [!CRITICAL]
> L'isolamento tramite Mind Key è il confine di sicurezza primario. Una Mind Key
> leakata concede pieno accesso ai dati di quella mente — ma SOLO a quella mente.
Token di autenticazione
| Token | Ambito | Cosa può accedere |
|-------|-------|-------------------|
| Mind Key | Singola mente | Solo i dati di quella mente |
| JWT | Account utente | Gestione account (crea/elenca/elimina menti) |
| Computer Token | Singolo computer | I comandi di quel computer |
Accesso tra menti
All'interno dello stesso utente
L'utente può accedere a tutte le sue menti tramite JWT (es. le
elenca tutte). Ma per leggere/scrivere dati di memoria, ha bisogno della Mind
Key specifica.
Tra utenti
Gli utenti non possono accedere ai dati l'uno dell'altro — A MENO CHE non
condividano esplicitamente una mente tramite la Sharing API:
[CODE BLOCK]
Dopo la condivisione, Bob può accedere alla Mente A tramite il suo JWT (sola
lettura se ).
Confini di sicurezza
[CODE BLOCK]
Modelli multi-tenant comuni
Modello 1: utente singolo, mente singola
Più comune per utenti singoli di agenti LLM.
- 1 account utente
- 1 mente
- 1 Mind Key
- Tutte le memorie in un unico scope
Modello 2: utente singolo, menti multiple
Per utenti con contesti multipli (lavoro, personale, progetti).
- 1 account utente
- N menti (es. "work", "personal", "project-x")
- N Mind Key
- Ogni sessione LLM usa una Mind Key
Modello 3: mente condivisa di team
Per team che collaborano a un progetto.
- 1 utente crea la mente (ottiene la Mind Key)
- Il creatore condivide con i membri del team tramite JWT
- Tutti i membri del team accedono tramite JWT (o Mind Key condivisa)
> [!WARNING]
> Condividere una Mind Key dà pieno accesso in lettura/scrittura. Per
> collaborazione di team, preferisca la Sharing API (basata su JWT) rispetto
> alla condivisione diretta di Mind Key.
Modello 4: provider SaaS
Per app che integrano Synapse come loro layer di memoria.
- Ogni cliente = 1 account utente
- Ogni progetto cliente = 1 mente
- L'app salva le Mind Key per cliente/progetto
- Pieno isolamento tra clienti
Verifica dell'isolamento
Test: una Mind Key non può accedere ad altre menti
[CODE BLOCK]
Test: il JWT non può leggere i dati di memoria direttamente
[CODE BLOCK]
Best practice
> [!TIP]
> - Usi una mente per progetto/contesto — l'isolamento è suo amico
> - Non condivida mai le Mind Key — usi la Sharing API invece
> - Roti le Mind Key se compromesse (elimini la mente, ne crei una nuova)
> - Verifichi le menti condivise — revisioni periodicamente
> - Usi JWT per UI umana — non esponga mai le Mind Key agli utenti finali
Prossimi passi
- Autenticazione
- Mind Key vs JWT
- Architettura
────────────────────────────────────────────────────────────
# Ricerca semantica (embedding)
SUMMARY: Ricerca concettuale delle memorie usando embedding vettoriali — trova per significato, non solo per parole chiave.
Ricerca semantica (embedding)
Synapse supporta la ricerca semantica usando embedding vettoriali. A differenza
di FTS5 (corrispondenza per parola chiave), la ricerca semantica trova le
memorie per significato — anche se nessuna parola chiave corrisponde.
Come funziona
[CODE BLOCK]
Cosa sono gli embedding?
Gli embedding sono rappresentazioni vettoriali numeriche del testo. Testo con
significato simile ha vettori simili. Synapse genera un vettore (es. 1536
dimensioni) per il contenuto di ogni memoria.
Similarità del coseno
Per trovare memorie semanticamente simili, Synapse calcola la similarità del
coseno tra il vettore della query e ogni vettore di memoria. Similarità più
alta = più rilevante.
Quando usare la ricerca semantica
Usi la ricerca semantica quando:
- Vuole "memorie su X" dove X è descritto diversamente da come è salvato
- FTS5 non restituisce risultati (nessuna corrispondenza di parola chiave)
- Vuole raggruppamento concettuale (es. tutte le memorie "deployment", anche se alcune dicono "release")
- La query è una domanda: "come gestiamo l'autenticazione?"
Usi FTS5 quando:
- Conosce le parole chiave esatte
- Ha bisogno di logica booleana (AND, OR, NOT)
- Ha bisogno di risposta sub-millisecond
- Vuole corrispondenza di frase
Endpoint
GET /memory/semantic-search
[CODE BLOCK]
Risposta:
[CODE BLOCK]
Esempi
Trova memorie sul deployment
[CODE BLOCK]
Restituisce memorie su "deployment", "release", "publishing", "rolling out",
ecc.
Trova pattern di autenticazione
[CODE BLOCK]
Restituisce memorie su login, auth, JWT, gestione sessioni, OAuth, ecc.
Trova memorie simili
[CODE BLOCK]
Usa similarità semantica (tramite tag condivisi E vettori di embedding).
Generazione degli embedding
Quando vengono generati gli embedding?
- Su memorizzazione — se il servizio embedding è configurato, l'embedding viene generato in modo sincrono
- Generazione batch — genera embedding per le memorie che ne sono sprovviste
- Aggiornamenti asincroni — quando il contenuto viene aggiornato, l'embedding viene rigenerato
Provider di embedding
Synapse supporta provider di embedding configurabili:
- OpenAI (, )
- Modelli locali (tramite Ollama o simili)
- Personalizzato (implementi l'interfaccia embeddings)
Configuri tramite variabili di ambiente:
[CODE BLOCK]
Generazione batch
Per menti con molte memorie sprovviste di embedding:
[CODE BLOCK]
Prestazioni
| Operazione | Latenza |
|-----------|---------|
| Genera embedding (OpenAI) | 100-200ms |
| Ricerca semantica (1k memorie) | 50-100ms |
| Ricerca semantica (10k memorie) | 200-500ms |
| Generazione batch (100 memorie) | 10-20s |
> [!NOTE]
> La ricerca semantica è più lenta di FTS5 a causa del calcolo vettoriale. Usi
> FTS5 per parole chiave note, semantica per query concettuali.
Limitazioni
Costo degli embedding
Se usa OpenAI, generare embedding costa denaro ($0,02 per 1M token per
text-embedding-3-small). Per 10.000 memorie con una media di 100 token ciascuna,
sono $0,02 — trascurabile.
Cold start
Le memorie salvate prima che gli embedding fossero configurati non avranno
embedding. Esegua per backfill.
Dipendenza dal provider
Se il provider di embedding è down, la ricerca semantica fallisce in modo
grazioso (restituisce risultati vuoti o errore). FTS5 continua a funzionare.
Quando gli embedding non sono disponibili
Se il servizio embedding non è configurato:
- restituisce 503 Service Unavailable
- funziona comunque (solo senza embedding generato)
- La ricerca FTS5 funziona ancora
Best practice
> [!TIP]
> - Usi la semantica per query concettuali — "come gestiamo X?"
> - Usi FTS5 per termini specifici — "docker swarm"
> - Faccia backfill degli embedding regolarmente —
> - Monitori la salute del provider — la ricerca semantica dipende da esso
> - Combini con i tag — semantica + filtro tag restringe i risultati
Prossimi passi
- Ricerca FTS5
- Memory API
- Architettura
## CATEGORIA: RICETTARIO LLM
Ricette e pattern per agenti LLM.
────────────────────────────────────────────────────────────
# Modello di polling chat
SUMMARY: Come fare polling dei messaggi dell'umano tra le chiamate agli strumenti senza bloccare il workflow.
Modello di polling chat
Il sistema chat è asincrono — gli umani possono lasciare messaggi mentre lei
lavora. Questo modello mostra come fare polling dei messaggi senza bloccare il
suo workflow.
Il modello
[CODE BLOCK]
Faccia polling tra le chiamate agli strumenti, non in un loop stretto.
Perché fare polling tra le chiamate agli strumenti?
- Non blocchi — il polling in un loop stretto spreca chiamate API
- Non perda messaggi — polling troppo infrequente significa risposte lente
- Punto ottimale — polling ogni 30-60 secondi, o dopo ogni chiamata a strumenti
Implementazione
Polling di base
[CODE BLOCK]
Modello 1: polling dopo ogni chiamata a strumenti
[CODE BLOCK]
Modello 2: polling basato sul tempo
[CODE BLOCK]
Modello 3: event-driven (con webhook)
Per notifica in tempo reale, registri un webhook:
[CODE BLOCK]
Poi il suo handler webhook può svegliare l'agente:
[CODE BLOCK]
Modelli di gestione dei messaggi
Modello: conferma poi elabora
[CODE BLOCK]
Modello: accodamento per elaborazione batch
[CODE BLOCK]
Modello: instradamento per priorità
[CODE BLOCK]
Frequenza di polling
| Caso d'uso | Frequenza |
|----------|-----------|
| Agente interattivo (umano in attesa) | Ogni 5-10 secondi |
| Agente in background | Ogni 30-60 secondi |
| Elaborazione batch | Ogni 5 minuti |
| Attivato da webhook | Non faccia polling — usi webhook |
> [!WARNING]
> Il polling più di una volta ogni 5 secondi spreca chiamate API. L'endpoint
> ritorna immediatamente se ci sono messaggi in attesa, quindi non
> c'è beneficio a un polling più veloce.
Chat multi-agente
Per comunicazione agente-agente:
[CODE BLOCK]
Best practice
> [!TIP]
> - Faccia polling tra le chiamate agli strumenti — non in un loop stretto
> - Confermi immediatamente — l'umano sa che ha ricevuto il messaggio
> - Elabori asincronamente — non blocchi su lavoro lungo
> - Usi webhook per tempo reale — il polling ha latenza
> - Non faccia polling più di una volta ogni 5 secondi — spreca chiamate API
Problemi comuni
Messaggi che spariscono
- contrassegna automaticamente i messaggi come letti
- Se non li elabora, sono persi
- Soluzione: Elabori sempre i messaggi prima di restituire
Risposte duplicate
- Se il suo handler crasha, potrebbe rispondere due volte
- Soluzione: Renda l'handler idempotente (verifichi se ha già risposto)
Risposte lente
- Il polling ogni 60s significa fino a 60s di latenza
- Soluzione: Faccia polling ogni 10-30s, o usi webhook
Prossimi passi
- Chat API
- Modello di inizio sessione
- Recupero errori
────────────────────────────────────────────────────────────
# Recupero errori per agenti
SUMMARY: Come gli agenti LLM dovrebbero gestire e recuperare da errori — retry, memorizzazione, apprendimento.
Recupero errori per agenti
Gli errori accadono. Le reti falliscono, le API restituiscono 500, le Mind Key
scadono. Questa guida mostra come gli agenti LLM dovrebbero gestire gli errori
in modo grazioso e imparare da essi.
Principi di gestione degli errori
1. Ritenti con backoff — gli errori transitori spesso si risolvono
2. Memorizzi l'errore — impari dai pattern
3. Degradì graziosamente — non faccia crashare l'intera sessione
4. Notifichi l'umano — per errori che non può risolvere
Gestione degli errori HTTP
Riprova con backoff esponenziale
[CODE BLOCK]
Gestione errori di auth
[CODE BLOCK]
Memorizzazione degli errori come memorie
Quando si verificano errori, li memorizzi così le sessioni future possono
imparare:
[CODE BLOCK]
Scenari di errore comuni
Scenario 1: Mind Key non valida
[CODE BLOCK]
Scenario 2: errore di rete
[CODE BLOCK]
Scenario 3: rate limit
[CODE BLOCK]
Scenario 4: errore del server (5xx)
[CODE BLOCK]
Scenario 5: chiamata a strumento fallita
[CODE BLOCK]
Modello: circuit breaker
Per fallimenti ripetuti, smetta di provare temporaneamente:
[CODE BLOCK]
Best practice
> [!TIP]
> - Ritenti sempre gli errori transitori — le reti falliscono, i server hanno hiccup
> - Non ritenti errori client (4xx) — non si riparano da soli
> - Memorizzi gli errori come memorie — impari dai pattern
> - Notifichi gli umani per errori critici — devono saperlo
> - Degradì graziosamente — lavoro parziale è meglio di un crash
> - Usi circuit breaker — non martelli un servizio che fallisce
Prossimi passi
- Riferimento API errori
- Modello di inizio sessione
- Test self-healing
────────────────────────────────────────────────────────────
# Strategia di tagging della memoria
SUMMARY: Come taggare le memorie per ricerca e filtraggio efficaci — il sistema di tagging che scala.
Strategia di tagging della memoria
I tag sono il segreto per il recupero di memoria scalabile. Questa guida mostra
come taggare le memorie così quelle giuste tornano al momento giusto.
Perché i tag contano
Senza tag, ha ricerca full-text piatta. Con i tag, ha navigazione strutturata:
[CODE BLOCK]
I tag abilitano:
- Filtraggio veloce —
- Ricerca con scope —
- Raggruppamento — trova tutte le memorie "mistake" per un progetto
- Cross-referencing — memorie con tag condivisi sono correlate
Schema di tagging
Tag di progetto
Usi nomi di progetto come tag:
[CODE BLOCK]
Tag di tecnologia
Usi nomi di tecnologia:
[CODE BLOCK]
Tag di argomento
Usi categorie di argomento:
[CODE BLOCK]
Tag di stato
Usi indicatori di stato:
[CODE BLOCK]
Tag di tipo
Usi indicatori di tipo:
[CODE BLOCK]
Regole di tagging
Regola 1: 2-5 tag per memoria
Troppo pochi tag = scarsa scopribilità. Troppi = rumore.
[CODE BLOCK]
Regola 2: minuscolo, con trattini
[CODE BLOCK]
Regola 3: usi un vocabolario consistente
Stabilisca un vocabolario di tagging e lo mantenga:
[CODE BLOCK]
Regola 4: tagghi con intento di ricerca
Chieda: "Come cercherò questa memoria?"
[CODE BLOCK]
Modelli
Modello 1: progetto + argomento
[CODE BLOCK]
Ricerca: (tutte le memorie del progetto Synapse)
Ricerca: (memorie di deployment in Synapse)
Modello 2: tipo + dominio
[CODE BLOCK]
Ricerca: (tutti gli errori)
Ricerca: (errori di deployment)
Modello 3: gerarchico
Per sottoprogetti all'interno di un progetto:
[CODE BLOCK]
Ricerca: (tutto Synapse)
Ricerca: (solo sottoprogetto docs)
Modello 4: tracciamento dello stato
[CODE BLOCK]
Casi d'uso comuni
Trovi tutte le decisioni su un progetto
[CODE BLOCK]
Trova tutti gli errori in un dominio
[CODE BLOCK]
Trova lavoro attivo
[CODE BLOCK]
Trova memorie su una tecnologia
[CODE BLOCK]
Manutenzione dei tag
Revisione periodica
[CODE BLOCK]
Unione di tag
Se ha tag inconsistenti ( e ), li unisca:
[CODE BLOCK]
Best practice
> [!TIP]
> - Stabilisca il vocabolario presto — tag consistenti dal giorno 1
> - Tagghi con intento di ricerca — come troverà questo dopo?
> - 2-5 tag è il punto ottimale — troppo pochi o troppi è male
> - Minuscolo + trattini — non
> - Revisioni periodicamente — unisca i duplicati, rimuova gli inutilizzati
Prossimi passi
- Best practice per la memoria
- Ricerca FTS5
- Workflow guidato da attività
────────────────────────────────────────────────────────────
# Modello di inizio sessione
SUMMARY: La sequenza canonica di inizio sessione che ogni agente LLM dovrebbe seguire.
KEY CONTEXT:
ALWAYS at session start: 1) GET /memory/recall, 2) GET /chat/poll, 3) GET /mind/tasks?status=in_progress
Build system prompt from recall output.
Process unread chat messages before doing new work.
Resume any in_progress tasks before starting new ones.
Store new learnings as they happen — don't wait until session end.
Modello di inizio sessione
Ogni sessione di agente LLM dovrebbe seguire questa sequenza canonica di avvio.
Saltare i passi porta a contesto perso, messaggi mancati e attività dimenticate.
Il modello
[CODE BLOCK]
Implementazione
Passo 1: richiami tutte le memorie
> [!CRITICAL]
> Questa è la chiamata più importante. Senza di essa, non ha memoria delle
> sessioni passate.
[CODE BLOCK]
Restituisce un riassunto in testo semplice di tutte le memorie, ordinate per
priorità.
Passo 2: polling dei messaggi chat non letti
[CODE BLOCK]
Restituisce i messaggi non letti dall'umano. Li contrassegna automaticamente
come letti.
Passo 3: verifichi le attività in corso
[CODE BLOCK]
Restituisce le attività su cui stava lavorando nella sessione precedente.
Passo 4: costruisca il contesto
Combini le tre risposte nel suo prompt di sistema:
[CODE BLOCK]
Passo 5: elabori gli item in sospeso
[CODE BLOCK]
Esempio completo
[CODE BLOCK]
Errori comuni
> [!WARNING]
> - Saltare il richiamo — inizia senza contesto, ripete gli errori passati
> - Dimenticare il polling chat — i messaggi dell'umano rimangono senza risposta
> - Ignorare le attività attive — il lavoro viene dimenticato a metà esecuzione
> - Non memorizzare nulla — la sessione non produce valore persistente
Variazioni
Modello minimale (LLM a basso contesto)
Per LLM con finestre di contesto piccole, salti il richiamo completo:
[CODE BLOCK]
Poi cerchi argomenti specifici quando necessario:
[CODE BLOCK]
Modello aggressivo (agenti long-running)
Per agenti che girano per ore, aggiunga un re-richiamo periodico:
[CODE BLOCK]
Prossimi passi
- Strategia di tagging della memoria
- Workflow guidato da attività
- Modello di polling chat
────────────────────────────────────────────────────────────
# Workflow guidato da attività
SUMMARY: Usi le attività Synapse per guidare workflow LLM multi-step che sopravvivono tra le sessioni.
Workflow guidato da attività
Le attività non sono solo todo — sono la spina dorsale dei workflow LLM
persistenti. Creando attività per lavoro multi-step, garantisce continuità tra
le sessioni e fornisce traccia di audit di cosa è stato fatto.
Perché guidato da attività?
Senza attività:
- L'LLM inizia ogni sessione insicuro su cosa fare
- Il lavoro multi-step viene dimenticato a metà esecuzione
- Nessun record di cosa è stato fatto
Con le attività:
- L'LLM riprende le attività in corso immediatamente
- Il lavoro multi-step sopravvive tra le sessioni
- Traccia di audit integrata di tutto il lavoro
Il modello
[CODE BLOCK]
Implementazione
Passo 1: crei un'attività per lavoro multi-step
[CODE BLOCK]
Passo 2: tracci l'avanzamento nella descrizione dell'attività
[CODE BLOCK]
Passo 3: riprenda tra le sessioni
[CODE BLOCK]
Passo 4: completi e archivi
[CODE BLOCK]
Esempio completo: workflow di deploy
[CODE BLOCK]
Gerarchia delle attività
Per lavoro complesso, usi relazioni di attività genitore-figlio:
[CODE BLOCK]
Cerci le sotto-attività:
[CODE BLOCK]
Workflow di stato
[CODE BLOCK]
Pending
Attività creata ma non iniziata. La usi per lavoro pianificato.
In Progress
Attualmente in lavorazione. Aggiorni la descrizione con l'avanzamento.
Done
Completata con successo. La descrizione dovrebbe includere il riepilogo.
Cancelled
Abbandonata. La descrizione dovrebbe includere il motivo.
Best practice
> [!TIP]
> - Crei attività per lavoro multi-step — il lavoro single-step non ha bisogno di un'attività
> - Aggiorni la descrizione con l'avanzamento — abilita la ripresa
> - Usi priorità alta per lavoro attivo — emerge nel richiamo
> - Completi le attività quando fatte — non le lasci inprogress
> - Memorizzi i riepiloghi di completamento come memorie — riferimento long-term
Modelli comuni
Modello: workflow di correzione bug
[CODE BLOCK]
Modello: workflow di ricerca
[CODE BLOCK]
Prossimi passi
- Modello di inizio sessione
- Modello di polling chat
- Recupero errori
## CATEGORIA: DOMANDE FREQUENTI
Domande frequenti e problemi comuni.
────────────────────────────────────────────────────────────
# FAQ API
SUMMARY: Domande comuni sull'API — auth, rate limit, gestione errori, scoperta endpoint.
FAQ API
Domande comuni sull'API di Synapse.
Come mi autentico?
Due metodi:
1. Mind Key (per endpoint dati):
2. JWT (per endpoint account):
Oppure tramite parametro query (limite 60 req/min):
Veda Autenticazione.
Qual è la differenza tra Mind Key e JWT?
- Mind Key: scope tenant, non scade mai, per dati memory/chat/tasks
- JWT: scope utente, scadenza 7 giorni, per gestione account/menti
Veda Mind Key vs JWT.
Perché ricevo 401 Unauthorized?
Cause comuni:
1. Header mancante
2. Mind Key non valida (verifichi che inizi con )
3. Uso di un JWT dove è richiesta una Mind Key (o viceversa)
4. La Mind Key è stata revocata
Soluzione: Verifichi il suo token. Veda Autenticazione.
Perché ricevo 404 Not Found?
Ha usato un percorso endpoint errato. Synapse ha solo i percorsi elencati in
.
Soluzione: Chiami per vedere tutti i percorsi validi. Non
indovini.
Perché ricevo 429 Too Many Requests?
Sta usando l'autenticazione tramite parametro query , che è limitata a
60/min.
Soluzione: Passi all'header (nessun rate limit).
Veda Limiti di traffico.
Come elenco tutti gli endpoint?
[CODE BLOCK]
Come trovo l'endpoint giusto?
1. Verifichi per la lista machine-readable
2. Verifichi per la documentazione API completa
3. Navigi per il sistema di documentazione
4. Usi per la specifica OpenAPI 3.0
Posso usare GET invece di POST?
Alcuni endpoint POST hanno equivalenti GET per strumenti solo-URL:
- ↔
- ↔
- ↔
Verifichi per le varianti GET disponibili.
Come gestisco gli errori?
Tutti gli errori restituiscono JSON:
[CODE BLOCK]
Veda Errori e gestione degli errori.
Qual è il limite del corpo della richiesta?
10 MB. Per payload più grandi (es. caricamento file), usi gli endpoint
multipart.
L'API supporta CORS?
Sì. Tutti gli endpoint restituiscono:
[CODE BLOCK]
C'è un SDK?
Sì:
- Node.js:
- MCP:
Veda Panoramica API per i dettagli.
Come faccio la paginazione?
Usi e :
[CODE BLOCK]
Limite predefinito: 100. Massimo: 500.
Posso filtrare le memorie per categoria o tag?
Sì:
[CODE BLOCK]
Come cerco nelle memorie?
In due modi:
1. Ricerca per parola chiave FTS5:
2. Ricerca semantica:
Veda Ricerca FTS5 e Ricerca semantica.
Come aggiorno una memoria?
POST con la stessa + — la memoria esistente viene
aggiornata, non duplicata.
[CODE BLOCK]
Come elimino una memoria?
[CODE BLOCK]
Posso fare eliminazione bulk?
Sì:
[CODE BLOCK]
Prossimi passi
- Panoramica API
- Errori e gestione degli errori
- Autenticazione
────────────────────────────────────────────────────────────
# FAQ generale
SUMMARY: Domande comuni su Synapse — cos'è, come funziona, per chi è.
FAQ generale
Domande comuni su Synapse.
Cos'è Synapse?
Synapse è una API di memoria persistente per agenti LLM. Dà al suo assistente
AI un cervello permanente e interrogabile che sopravvive tra le sessioni.
Invece di dimenticare tutto quando la chat si chiude, l'LLM salva e recupera
le memorie tramite una semplice API HTTP.
Scopra di più: Cos'è Synapse?
Per chi è Synapse?
- Sviluppatori di agenti LLM che hanno bisogno di stato persistente
- Power user che eseguono LLM locali con agenti personalizzati
- Team che costruiscono assistenti AI con memoria condivisa
- Ingegneri di automazione che concatenano chiamate LLM tra sessioni
Synapse è gratuito?
Synapse è ospitato su e gratuito per uso
personale. Per il self-hosting, veda il repo.
In cosa differisce Synapse da ChatGPT Memory?
| Funzionalità | ChatGPT Memory | Synapse |
|---------|---------------|---------|
| Storage | Server OpenAI | Suo server |
| Accesso API | No | Sì (REST + MCP) |
| Multi-tenant | No | Sì (menti) |
| Categorie personalizzate | No | Sì (8 categorie) |
| Ricerca full-text | Limitata | FTS5 + semantica |
| Self-hostable | No | Sì |
Quali LLM funzionano con Synapse?
Qualsiasi LLM che possa fare chiamate HTTP o usare MCP:
- Claude (Anthropic) — tramite MCP o API diretta
- GPT-4 / GPT-3.5 (OpenAI) — tramite function calling + API
- Gemini (Google) — tramite function calling + API
- Llama / Mistral (locali) — tramite integrazione personalizzata
- Qualsiasi LLM tramite il server MCP di Synapse
Devo ospitare Synapse io stesso?
No. La versione hosted su è disponibile per
uso pubblico. Il self-hosting è opzionale (per privacy, personalizzazione o
ambienti air-gapped).
Quanti dati posso salvare?
Non ci sono limiti rigidi sulla versione hosted. Uso tipico:
- 100-1000 memorie per mente
- 1-10 KB per memoria (campo content)
- Totale: 10 MB per mente
Per scala maggiore, faccia self-host.
I miei dati sono privati?
Sì. Ogni mente è isolata (veda Multi-tenancy).
Altri utenti non possono vedere i suoi dati. Il provider di hosting
(Schäfer Services) ha accesso ma non visualizza i dati utente.
Per privacy massima, faccia self-host.
Posso esportare i miei dati?
Sì. Usi per esportare tutte le memorie come JSON.
Veda Backup e ripristino.
Cosa succede se perdo la mia Mind Key?
Le Mind Key vengono mostrate una sola volta alla creazione. Se perse:
1. Acceda con la sua email/password per ottenere un JWT
2. Crei una nuova mente tramite
3. Salvi la nuova Mind Key
4. (Opzionale) Elimini la vecchia mente tramite
Non può recuperare le memorie da una mente la cui chiave è perduta.
Più agenti LLM possono condividere una mente?
Sì. Tutti gli agenti che usano la stessa Mind Key condividono i dati di quella
mente. Per lavoro multi-agente coordinato, veda Coordinazione multi-agente.
Synapse funziona offline?
No, Synapse richiede una connessione internet al server (hosted o self-hosted).
Per LLM offline, esegua Synapse localmente.
Quanto è veloce la ricerca nelle memorie?
- Ricerca per parola chiave FTS5: < 10ms per 1000 memorie
- Ricerca semantica: 50-100ms per 1000 memorie
- Richiamo completo: < 50ms per 1000 memorie
Veda Ricerca FTS5 per i dettagli.
Posso usare Synapse senza un LLM?
Sì. Synapse è un'API di memoria generica. Può usarla da qualsiasi applicazione
che trae beneficio da uno storage key-value persistente e ricercabile con
categorie e tag.
Prossimi passi
- Cos'è Synapse?
- Quick Start
- FAQ API
────────────────────────────────────────────────────────────
# FAQ MCP
SUMMARY: Domande comuni sull'integrazione MCP — strumenti, transport, troubleshooting.
FAQ MCP
Domande comuni sul server MCP di Synapse.
Cos'è MCP?
MCP (Model Context Protocol) è uno standard aperto di Anthropic per
l'integrazione LLM-strumento. Invece di incollare la documentazione API nei
prompt, registra gli strumenti con un server MCP, e l'LLM li chiama come
funzioni native.
Veda Cos'è MCP?.
Quanti strumenti espone Synapse MCP?
79 strumenti in 12 categorie: memory, chat, scheduler, tasks, scripts,
computers, push, user, utility, visualization, sharing, webhooks, browser.
Veda Cos'è MCP? per la lista completa.
Quali client MCP sono supportati?
- Claude Desktop (macOS, Windows)
- Claude Code (terminale)
- Cursor (IDE)
- Continue.dev (VS Code, JetBrains)
- Cline (VS Code)
- Qualsiasi client compatibile con MCP
Veda Configurazione Claude Desktop per esempi di
configurazione.
Quali transport sono supportati?
1. stdio (locale, consigliato per desktop)
2. HTTP/SSE (remoto, multi-tenant)
3. WebSocket (mobile, alto volume)
Come configuro Claude Desktop?
Modifichi :
[CODE BLOCK]
Veda Configurazione Claude Desktop.
Perché gli strumenti non appaiono in Claude Desktop?
1. Riavvii completamente Claude Desktop (Cmd+Q su macOS)
2. Verifichi che il file di configurazione sia JSON valido
3. Verifichi Node.js 18+ installato
4. Controlli i log MCP:
Veda Troubleshooting MCP.
Come uso una mente diversa?
Cambii nella sua configurazione MCP e riavvii il client.
Per menti multiple, esegua più istanze del server MCP con Mind Key diverse.
Posso limitare quali strumenti vengono esposti?
Sì, usi i Tool Profile:
- : 8 strumenti compositi (500 token)
- : 25 strumenti (2.500 token)
- : 119 strumenti (8.250 token, predefinito)
Lo imposti tramite variabile env o header .
Come faccio debug dei problemi MCP?
1. Esegua il server MCP manualmente:
2. Controlli i log del client (varia per client)
3. Verifichi che la Mind Key funzioni:
4. Verifichi la salute di Synapse:
Veda Troubleshooting MCP.
Il server MCP è gratuito?
Sì. Il pacchetto npm è open source. Il server MCP hosted su
è gratuito per uso pubblico.
Posso fare self-host del server MCP?
Sì:
[CODE BLOCK]
In cosa differisce MCP dalle chiamate API dirette?
| Aspetto | API diretta | MCP |
|--------|-----------|-----|
| LLM deve conoscere | URL, header, auth | Solo nomi degli strumenti |
| Gestione auth | Manuale | Automatica (variabile env) |
| Scoperta strumenti | Legge /endpoints | Automatica tramite protocollo MCP |
| Gestione errori | Manuale | Standardizzata |
| Ideale per | Integrazioni personalizzate | Agenti LLM |
Posso costruire il mio client MCP?
Sì. Usi l'SDK MCP ufficiale:
- TypeScript:
- Python:
Veda Client MCP personalizzato.
Come segnalo bug MCP?
Apra un issue:
Includa:
- Versione del server MCP
- Nome e versione del client
- Sistema operativo
- Log rilevanti
- Passaggi per riprodurre
Prossimi passi
- Cos'è MCP?
- Configurazione Claude Desktop
- Troubleshooting MCP
────────────────────────────────────────────────────────────
# FAQ Troubleshooting
SUMMARY: Soluzioni ai problemi comuni di Synapse — auth, rete, dati, deployment.
FAQ Troubleshooting
Soluzioni ai problemi comuni di Synapse.
Non riesco a fare login
Sintomi
- restituisce 401
- "Invalid email or password"
Soluzioni
1. Verifichi che l'email sia corretta — case sensitive
2. Controlli la password — minimo 6 caratteri
3. Si registri prima se non ha un account:
4. Resetti la password (se SMTP configurato) tramite la UI web
Ho perso la mia Mind Key
Sintomi
- Non riesco ad accedere alle memorie
- La Mind Key è stata eliminata/persa
Soluzioni
Le Mind Key non possono essere recuperate. Deve:
1. Fare login per ottenere JWT:
2. Elencare le menti: (con JWT)
3. Creare una nuova mente:
4. Salvare la nuova Mind Key
5. (Opzionale) Eliminare la vecchia mente:
I dati nella vecchia mente sono persi a meno che non ritrovi la Mind Key.
Le chiamate API restituiscono 401
Sintomi
- Tutte le chiamate API restituiscono 401 Unauthorized
- "Mind Key fehlt oder ungültig"
Soluzioni
1. Verifichi il formato dell'header:
2. Controlli che la Mind Key inizi con (non che è JWT)
3. Testi direttamente:
[CODE BLOCK]
4. La Mind Key potrebbe essere revocata — crei una nuova mente
Veda Autenticazione.
Le chiamate API restituiscono 404
Sintomi
- 404 Not Found
- "Route not found"
Soluzioni
> [!CRITICAL]
> Non indovini i percorsi degli endpoint. Esistono solo i percorsi in
> .
1. Controlli gli endpoint validi:
2. Confronti l'URL esattamente — case sensitive, nessuno slash finale
3. Controlli il metodo HTTP — vs sono diversi
Le chiamate API restituiscono 429
Sintomi
- 429 Too Many Requests
- "Rate limit exceeded"
Soluzioni
1. Passi all'auth tramite header (nessun rate limit):
[CODE BLOCK]
2. Attenda secondi se deve usare
Veda Limiti di traffico.
La ricerca nelle memorie non restituisce risultati
Sintomi
- restituisce vuoto
- Sa che le memorie esistono
Soluzioni
1. Verifichi che le memorie esistano:
2. Controlli la sintassi di ricerca — FTS5 ha una sintassi specifica
3. Provi una query più semplice — invece di
4. Usi la ricerca semantica per query concettuali:
Veda Ricerca FTS5.
Le memorie non persistono
Sintomi
- POST /memory restituisce success
- GET /memory/recall non le mostra
Soluzioni
1. Verifichi la stessa Mind Key — chiavi diverse = menti diverse
2. Controlli la risposta — POST restituisce
3. Provi GET /memory (lista JSON) invece di /memory/recall (testo)
4. Controlli i filtri — o potrebbero nasconderle
Gli strumenti non appaiono in Claude Desktop
Sintomi
- Claude Desktop mostra 0 strumenti
- Nessuna icona 🔌
Soluzioni
1. Riavvii completamente Claude Desktop (Cmd+Q)
2. Verifichi che il file di configurazione sia JSON valido
3. Controlli Node.js 18+ installato
4. Esegua MCP manualmente:
5. Controlli i log:
Veda Troubleshooting MCP.
Synapse è offline
Sintomi
- Non riesce a raggiungere synapse.schaefer.zone
- curl va in timeout
Soluzioni
1. Controlli la sua internet — provi un altro sito
2. Controlli la salute di Synapse:
3. Attenda — potrebbe essere un outage temporaneo o deployment
4. Controlli la pagina di stato (se disponibile)
Per self-hosted: controlli lo stato del container Docker, la connessione al
database.
Errori del database
Sintomi
- 500 Internal Server Error
- "Database connection failed"
Soluzioni
Per self-hosted:
1. Controlli che PostgreSQL sia in esecuzione:
2. Controlli DATABASEURL nell'env
3. Controlli le migrazioni:
4. Controlli lo spazio su disco:
Per hosted: segnali al support.
Webhook non si attiva
Sintomi
- Webhook registrato ma non riceve callback
- Nessuna POST alla sua URL
Soluzioni
1. Verifichi che l'URL sia raggiungibile:
2. Controlli il filtro eventi — corrisponde a tutti gli eventi memory
3. Testi il webhook:
4. Controlli che il webhook sia abilitato:
5. Verifichi SSL — Synapse richiede HTTPS valido per le URL dei webhook
Veda Webhooks API.
Il cron job non viene eseguito
Sintomi
- Creato cron job ma non si attiva
- non si aggiorna
Soluzioni
1. Controlli la sintassi della pianificazione — deve essere cron a 5 campi valido OPP secondi interi
2. Verifichi che l'endpoint sia consentito — deve essere http(s), no IP privati
3. Controlli che il job sia abilitato:
4. Attenda il prossimo momento pianificato — cron non è istantaneo
Veda Cron & Scheduler.
Ha bisogno di altro aiuto?
1. Controlli la documentazione esistente:
2. Cerchi nella documentazione:
3. Apra un issue:
4. Contatti: veda la pagina
Prossimi passi
- Errori e gestione degli errori
- FAQ API
- Troubleshooting MCP