# SYNAPSE DOCUMENTATIE — Volledige referentie
# Gegenereerd: 2026-07-18T06:15:34.067Z
# Totaal aantal artikelen: 47
Dit document bevat de volledige Synapse API-documentatie.
Base URL: https://synapse.schaefer.zone
Language: nl
========================================================================
## CATEGORIE: AAN DE SLAG
Alles wat je nodig hebt om met Synapse te beginnen.
────────────────────────────────────────────────────────────
# Authenticatie & Mind Keys
SUMMARY: Hoe Synapse-authenticatie werkt: Mind Keys voor agents, JWT's voor mensen, ?key= voor URL-only tools.
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.
Authenticatie & Mind Keys
Synapse gebruikt twee authenticatiemethoden, elk geoptimaliseerd voor een ander doel.
Het verschil begrijpen is essentieel voor het bouwen van betrouwbare integraties.
Twee auth-methoden
| Methode | Gebruik | Ratelimit | Verval |
|---------|---------|-----------|--------|
| Mind Key | LLM-agents, geautomatiseerde tools | Geen (header) / 60 per min (query) | Nooit |
| JWT | Mensgerichte UI, account-operaties | Geen | 7 dagen |
Mind Key (voor agents)
Een Mind Key is een tenant-scoped API-token. Het authenticeert de data van één mind
(herinneringen, taken, chat, scripts, enz.). Gebruik het voor:
- LLM-agents die de API aanroepen
- Achtergrond-automatiseringsscripts
- MCP-server-configuratie
- Elke langlevende integratie
Header-authenticatie (aanbevolen)
[CODE BLOCK]
Queryparameter (voor URL-only tools)
[CODE BLOCK]
> [!WARNING]
> De -queryparameter is gelimiteerd tot 60 verzoeken per minuut.
> De Bearer-header heeft geen ratelimit. Gebruik de header wanneer uw client
> aangepaste headers ondersteunt.
Een Mind Key aanmaken
[CODE BLOCK]
De respons bevat — sla deze onmiddellijk op, deze wordt slechts één keer getoond.
Uw minds tonen
[CODE BLOCK]
Een mind verwijderen (onomkeerbaar!)
[CODE BLOCK]
JWT (voor mensen)
JWT's authenticeren het gebruikersaccount, niet een specifieke mind. Gebruik ze voor:
- Accountregistratie en login
- Minds aanmaken/tonen/verwijderen
- Minds delen met andere gebruikers
- Web Push-abonnementsbeheer
Registreren
[CODE BLOCK]
Retourneert:
Inloggen
[CODE BLOCK]
Retourneert:
JWT-verval
JWT's vervallen na 7 dagen. Wanneer een JWT vervalt, roept u gewoon opnieuw
aan om een verse te krijgen. De Mind Key vervalt nooit, dus bestaande agent-integraties
blijven werken.
Beveiligings-best-practices
> [!CRITICAL]
> - Commit Mind Keys nooit naar git. Gebruik omgevingsvariabelen.
> - Log Mind Keys nooit. Maskeer ze in logs ().
> - Roteer sleutels bij vermoeden van een lek (verwijder de mind, maak een nieuwe aan).
> - Gebruik één mind per project om de schade bij een lek te beperken.
Omgevingsvariabele-patroon
[CODE BLOCK]
[CODE BLOCK]
MCP-server-config
[CODE BLOCK]
Multi-mind-patroon
Elke gebruiker kan meerdere minds hebben. Veelvoorkomende patronen:
| Mind-naam | Doel |
|-----------|------|
| | Werkgerelateerde herinneringen |
| | Persoonlijke voorkeuren, familie |
| | Specifieke projectcontext |
| | Leervoortgang |
| | Algemene fallback |
Gebruik verschillende Mind Keys voor verschillende LLM-sessies om contexten gescheiden te houden.
Ratelimits
| Auth-methode | Limiet | Bereik |
|--------------|--------|--------|
| Mind Key (header) | Geen | Per-mind |
| Mind Key (?key=) | 60/min | Per-IP |
| JWT (header) | Geen | Per-gebruiker |
| Openbare eindpunten | Geen | Globaal |
Ratelimit-headers (, , )
worden in responsen opgenomen waar van toepassing.
Volgende stappen
- Mind Key vs JWT — wanneer welke gebruiken
- Memory API — wat u kunt doen met een Mind Key
- User API — accountbeheer met JWT's
────────────────────────────────────────────────────────────
# Mind Key vs JWT — Wanneer welke?
SUMMARY: Keuzehandleiding: Mind Key voor agent-data-toegang, JWT voor accountbeheer.
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 — Wanneer welke?
Synapse heeft twee authenticatie-tokens. De verkeerde kiezen leidt tot 401-fouten.
Deze handleiding geeft u een helder beslissingskader.
Snelle beslissingstabel
| U wilt... | Gebruik |
|-----------|---------|
| Herinneringen opslaan / ophalen | Mind Key |
| Chatberichten sturen / pollen | Mind Key |
| Taken beheren | Mind Key |
| Scripts opslaan | Mind Key |
| Webhooks registreren | Mind Key |
| Computers bedienen | Mind Key (gebruikerskant) / Computer Token (agent-kant) |
| Gebruikersaccount registreren | Geen (publiek) |
| Inloggen | Geen (publiek) |
| Minds aanmaken / tonen / verwijderen | JWT |
| Een mind delen met andere gebruiker | JWT |
| Abonneren op web push-meldingen | JWT |
| Auditlog bekijken | Mind Key |
De eenvoudige regel
> [!TIP]
> Als het de data van één mind raakt → Mind Key.
> Als het het account of mind-metadata beheert → JWT.
Mind Key — Data-toegangstoken
Een Mind Key verleent toegang tot de data van één mind. Het is een langlevend token
dat nooit vervalt (tot de mind wordt verwijderd). Perfect voor:
- LLM-agents die herinneringen tussen sessies persistent maken
- Achtergrond-cron-jobs
- MCP-server-configuratie
- Webhook-integraties
- Mobiele apps die memory lezen
Wat Mind Key kan doen
- — alle herinneringen in deze mind lezen
- — herinneringen opslaan/bijwerken
- — chatberichten lezen
- — chatberichten sturen
- — taken tonen
- — taken aanmaken
- — scripts opslaan
- — webhooks registreren
- — computer-commando's in de wachtrij plaatsen
Wat Mind Key NIET kan doen
- Minds aanmaken/tonen/verwijderen (JWT nodig)
- Mind delen met andere gebruiker (JWT nodig)
- Gebruikersaccount-info bekijken (JWT nodig)
- Abonneren op web push (JWT nodig)
JWT — Accountbeheer-token
Een JWT authenticeert het gebruikersaccount. Het vervalt na 7 dagen en wordt gebruikt
voor accountniveau-operaties die meerdere minds beslaan of andere gebruikers betreffen.
Wat JWT kan doen
- — een nieuwe mind aanmaken (retourneert een nieuwe Mind Key)
- — alle minds voor deze gebruiker tonen
- — een mind verwijderen
- — een mind delen met een andere gebruiker
- — abonneren op web push-meldingen
- — mind-shares tonen
Wat JWT NIET kan doen
- Herinneringen lezen/schrijven (Mind Key nodig)
- Chatberichten sturen (Mind Key nodig)
- Taken beheren (Mind Key nodig)
- Webhooks registreren (Mind Key nodig)
Speciaal geval: Computer Token
De -eindpunten (agent-gericht, voor de screen-remote-agent)
gebruiken een derde tokentype: de Computer Token. Dit token wordt geretourneerd door
bij het inwisselen van een installatiecode, en is specifiek voor
één geregistreerde computer.
| Eindpunt | Auth |
|----------|------|
| | Computer Token |
| | Computer Token |
| | Mind Key of JWT |
| | Mind Key of JWT |
Veelvoorkomende patronen
Patroon 1: Enkele LLM-agent
1. Eenmalig registreren → JWT krijgen
2. Eén mind aanmaken → Mind Key krijgen
3. LLM gebruikt Mind Key voor alles
Patroon 2: Multi-project-agent
1. Eenmalig registreren → JWT krijgen
2. Meerdere minds aanmaken (work, personal, project-x) → meerdere Mind Keys krijgen
3. LLM laadt verschillende Mind Key op basis van context
Patroon 3: Team-deling
1. Gebruiker A maakt een mind aan → krijgt Mind Key A
2. Gebruiker A deelt met Gebruiker B via JWT ()
3. Gebruiker B kan nu benaderen via eigen JWT
4. Voor LLM-toegang moet Gebruiker B een eigen Mind Key aanmaken (of die van A gebruiken)
Patroon 4: MCP-server
MCP-servers gebruiken altijd Mind Key (ingesteld via -env-var). Eén MCP-
serverinstantie = één mind. Voor multi-mind-toegang, draai meerdere MCP-instanties
of implementeer client-side mind-wisseling.
Token-formaat overzicht
| Token | Formaat | Voorbeeld |
|-------|---------|-----------|
| Mind Key | + 36 tekens | |
| JWT | + base64 | |
| Computer Token | + 36 tekens | |
Volgende stappen
- Authenticatie — volledige auth-handleiding
- User & Minds API — JWT-beveiligde eindpunten
- Memory API — Mind Key-beveiligde eindpunten
────────────────────────────────────────────────────────────
# Quick Start voor LLM-agents
SUMMARY: In 3 API-aanroepen: alle herinneringen ophalen, een nieuwe opslaan, zoeken. De essentiële LLM-workflow.
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 voor LLM-agents
U verliest alle geheugen tussen sessies. Synapse is uw externe hersenen. Deze handleiding
toont de drie essentiële API-aanroepen die elke LLM-agent moet kennen.
> [!CRITICAL]
> Roep aan aan het BEGIN van ELKE sessie.
> Zonder deze aanroep heeft u geen geheugen van wie de gebruiker is, wat u beloofd heeft,
> of waaraan u de laatste keer werkte.
Stap 1: Alle herinneringen ophalen (ALTIJD EERST)
[CODE BLOCK]
Retourneert een gestructureerde platte-tekst samenvatting van alle opgeslagen herinneringen. Parse dit om
uw mentale model van de gebruiker, hun projecten en eerdere interacties te herstellen.
Voorbeeldrespons:
[CODE BLOCK]
Stap 2: Een nieuwe herinnering opslaan
Wanneer u iets leert dat het onthouden waard is:
[CODE BLOCK]
Categorieën: , , , , , , , ,
Prioriteiten: , , ,
> [!TIP]
> Voeg altijd een -veld toe — een korte identificator voor de herinnering. Hiermee kunt u
> dezelfde herinnering later bijwerken door opnieuw te POSTen met dezelfde key.
Stap 3: Naar een specifieke herinnering zoeken
[CODE BLOCK]
> [!TIP]
> FTS5-syntaxis: meerdere woorden = AND-zoekopdracht. Zinnen tussen aanhalingstekens: .
> Prefix-zoekopdracht: . Booleaans: .
Open tools (geen auth-headers)
Als uw tool alleen URL's kan openen (geen aangepaste headers), gebruik dan de -parameter:
[CODE BLOCK]
> [!WARNING]
> is gelimiteerd tot 60 verzoeken/minuut. Bearer-header heeft geen ratelimit.
> Gebruik waar mogelijk de Bearer-header.
Volledige sessie-workflow
1. Sessiestart: — alle herinneringen laden
2. Tijdens werk: — specifieke feiten vinden
3. Bij nieuwe info: — opslaan (met categorie, key, tags, prioriteit)
4. Periodiek: — menselijke berichten controleren
5. Sessie-einde: Sla eventuele laatste leermomenten op via
Veelvoorkomende patronen
Een bestaande herinnering bijwerken
POST met dezelfde en — de bestaande herinnering wordt
bijgewerkt, niet gedupliceerd.
Projectstatus opslaan
[CODE BLOCK]
Een fout vastleggen (zodat u deze niet herhaalt)
[CODE BLOCK]
Menselijke berichten controleren
[CODE BLOCK]
Retourneert ongelezen berichten van de mens. Antwoord met:
[CODE BLOCK]
Volgende stappen
- Authenticatie — Mind Key vs JWT
- Memory API-referentie — alle 22 memory-eindpunten
- Chat API — asynchrone communicatie met mensen
- LLM-cookbook — praktische patronen
────────────────────────────────────────────────────────────
# Quick Start (Mens)
SUMMARY: Registreer een account, maak uw eerste mind aan, sla een herinnering op — alles in 5 minuten.
Quick Start (Mens)
Deze handleiding leidt u door het aanmaken van een Synapse-account, uw eerste Mind Key,
en het opslaan van uw eerste herinnering. Totale tijd: 5 minuten.
Stap 1: Registreer een account
Open de Synapse API en maak een account aan:
[CODE BLOCK]
Respons:
[CODE BLOCK]
> [!TIP]
> Sla de JWT ergens veilig op — u heeft deze nodig om minds aan te maken. De JWT vervalt
> na 7 dagen; log opnieuw in met hetzelfde eindpunt om te vernieuwen.
Stap 2: Maak uw eerste mind aan
Een "mind" is een geïsoleerde memory-scope. De meeste gebruikers beginnen met één mind, maar u kunt
er meerdere hebben (bijv. "work", "personal", "project-x"). Elke mind heeft zijn eigen
unieke Mind Key.
[CODE BLOCK]
Respons:
[CODE BLOCK]
> [!CRITICAL]
> Sla de onmiddellijk op. Het wordt slechts één keer getoond en kan later
> niet meer worden opgehaald. Als u het verliest, moet u een nieuwe mind aanmaken.
Stap 3: Sla uw eerste herinnering op
Gebruik nu de Mind Key om een herinnering op te slaan:
[CODE BLOCK]
Respons:
[CODE BLOCK]
Stap 4: Alle herinneringen ophalen
Om alles op te halen wat u heeft opgeslagen:
[CODE BLOCK]
Respons (platte tekst, geoptimaliseerd voor LLM-verbruik):
[CODE BLOCK]
Stap 5: Herinneringen doorzoeken
Vind specifieke herinneringen op trefwoord:
[CODE BLOCK]
Stap 6: Verbind uw LLM
De eenvoudigste manier om uw LLM toegang te geven tot Synapse is via MCP:
- Claude Desktop-setup — 2-minuten-configuratie
- Claude Code-setup — terminal-integratie
- Cursor-setup — IDE-integratie
Na setup roept uw LLM automatisch aan aan het begin van
elke sessie en persisteert nieuwe feiten via .
Memory-categorieën
Synapse ondersteunt 8 categorieën — kies de meest specifieke:
| Categorie | Gebruik |
|-----------|---------|
| | Gebruikersnaam, rol, contactgegevens |
| | Voorkeuren, afkeuren, werkstijl |
| | Verifieerbare feiten (projectdetails, data) |
| | Projectstatus, mijlpalen, todo's |
| | Dingen waar de gebruiker goed in is |
| | Eerdere fouten — herhaal ze niet |
| | Sessie-relevante context |
| | Diverse notities |
Prioriteitsniveaus
- — leuk om te weten
- — standaard
- — belangrijk
- — mag nooit vergeten worden (gebruikersidentiteit, juridische info)
Volgende stappen
- Authenticatie deep-dive
- Mind Key vs JWT
- Memory API-referentie
- MCP-integratie
────────────────────────────────────────────────────────────
# Wat is Synapse?
SUMMARY: Synapse is een permanente memory-API voor LLM-agents — uw AI vergeet nooit tussen sessies.
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.)
Wat is Synapse?
Synapse is een permanente memory-API voor LLM-agents. Het lost het fundamentele
probleem van elke chat-gebaseerde LLM op: tussen sessies vergeet de agent alles.
Synapse geeft uw AI een permanente, doorzoekbare hersenen die overleeft tussen gesprekken,
over dagen, en over verschillende LLM-providers.
> [!CRITICAL]
> Als u een LLM-agent bent die dit leest: roep aan aan het begin
> van elke sessie. Zonder deze aanroep heeft u geen geheugen van eerdere interacties,
> geen kennis van wie de gebruiker is, en geen context over lopende projecten.
Het probleem dat Synapse oplost
Elke moderne LLM (Claude, GPT, Gemini, Llama) heeft dezelfde architecturale beperking:
het gesprekscontextvenster is eindig, en zodra de sessie eindigt, is alle staat verloren.
Dit betekent dat uw AI-assistent:
- Uw naam, voorkeuren en lopende projecten vergeet tussen chats
- Niet kan leren van eerdere fouten tussen sessies
- Geen continuïteit heeft voor langlopend werk
- Elke keer dezelfde verduidelijkende vragen opnieuw stelt
Synapse lost dit op door een eenvoudige HTTP-API te bieden waar de LLM gestructureerde
herinneringen kan opslaan en ophalen. De herinneringen blijven op de server staan, geïndexeerd en
doorzoekbaar, zodat elke toekomstige sessie ze kan ophalen.
Belangrijkste functies
- Permanente memory-opslag — feiten, voorkeuren, projecten, fouten, vaardigheden
- Volledige-tekst zoekopdracht (FTS5) — vind elke herinnering op trefwoord in milliseconden
- Semantisch zoeken — embeddings-gebaseerde similariteitszoekopdracht voor conceptuele query's
- Multi-tenant — elke gebruiker heeft geïsoleerde "minds" (één gebruiker, veel projecten)
- Asynchrone chat — mensen kunnen berichten achterlaten voor de agent terwijl deze werkt
- Taken & planning — ingebouwde taakbeheerder en cron-scheduler
- MCP-integratie — 79 tools beschikbaar als Model Context Protocol voor Claude, Cursor, Continue
- Browser- & computerbesturing — tools voor automatisering op afstand
- Webhooks — ontvang HTTP-callbacks bij memory/chat/task-wijzigingen
Hoe het werkt
[CODE BLOCK]
1. De LLM roept aan bij sessiestart
2. Synapse retourneert een gestructureerde tekstsamenvatting van alle opgeslagen herinneringen
3. De LLM werkt, en roept periodiek aan om nieuwe feiten op te slaan
4. Wanneer de gebruiker een vraag stelt, kan de LLM aanroepen
5. Bij sessie-einde wordt belangrijke nieuwe context gepersisteerd voor de volgende sessie
Voor wie is het?
- LLM-agent-ontwikkelaars die permanente staat nodig hebben
- Power users die lokale LLM's draaien (Ollama, LM Studio) met aangepaste agents
- Teams die AI-assistenten bouwen die gedeeld geheugen nodig hebben
- Automatiseringsengineers die LLM-aanroepen ketenen tussen sessies
Snelle vergelijking
| Functie | ChatGPT Memory | Synapse |
|---------|---------------|---------|
| Opslaglocatie | OpenAI-servers | Uw server |
| API-toegang | Nee (gesloten) | Ja (REST + MCP) |
| Multi-tenant | Nee | Ja (minds) |
| Aangepaste categorieën | Nee | Ja (8 categorieën) |
| Zoekopdracht | Beperkt | FTS5 + semantisch |
| Self-hostable | Nee | Ja (Docker) |
Volgende stappen
- Quick Start voor mensen — krijg een Mind Key in 5 minuten
- Quick Start voor LLM's — eerste API-aanroepen
- Authenticatie — Mind Keys vs JWT's
- Architectuuroverzicht — hoe Synapse is opgebouwd
## CATEGORIE: API-REFERENTIE
Volledige referentie voor elk API-eindpunt.
────────────────────────────────────────────────────────────
# Browser Proxy
SUMMARY: Browserautomatiseringsservice — aparte Docker-container op poort 13000 voor headless browserbesturing.
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
De Browser Proxy is een aparte Docker-service die headless browserautomatisering
via Playwright biedt. Het is NIET direct onderdeel van de Synapse API —
Synapse-eindpunten bevatten geen -paden.
Architectuur
[CODE BLOCK]
Toegangsmethoden
Methode 1: Via de Synapse MCP-server (aanbevolen)
De Synapse MCP-server stelt browsertools beschikbaar als MCP-tools. Gebruik dit
voor door LLM aangestuurde browserautomatisering:
[CODE BLOCK]
Beschikbare MCP-browsertools:
- — open een nieuw browsertabblad
- — navigeer naar een URL
- — klik op een element
- — typ tekst in een veld
- — maak een schermafbeelding
- — sluit het tabblad
- (en meer — zie MCP-integratie)
Methode 2: Directe Browser Proxy-toegang
Voor niet-MCP-integraties maakt u direct verbinding met de browser-proxy-service:
[CODE BLOCK]
Veelvoorkomende toepassingen
Webscraping
[CODE BLOCK]
Formulierautomatisering
[CODE BLOCK]
Schermafbeeldingen maken
[CODE BLOCK]
Gerelateerde services
| Service | Poort | Doel |
|---------|-------|------|
| Synapse API | 12800 | Memory, chat, taken |
| Synapse MCP | 13100 | MCP-server (79 tools) |
| Browser Proxy | 13000 | Headless browserautomatisering |
| SSH Proxy | 12900 | SSH-toegang tot externe machines |
Volgende stappen
- MCP-integratie — hoe u browsertools via MCP gebruikt
- Computer Control API — voor GUI-automatisering op geregistreerde machines
────────────────────────────────────────────────────────────
# Chat API
SUMMARY: Asynchrone chat tussen mensen en LLM-agents — poll, antwoord, geschiedenis, ongelezen teller, bestandsuploads.
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
De Chat API maakt asynchrone berichtenuitwisseling mogelijk tussen mensen en LLM-agents.
In tegenstelling tot synchrone chat (ChatGPT-stijl) kan de mens berichten achterlaten
terwijl de agent aan het werk is — de agent pollt tussen tool-aanroepen door.
Hoe het werkt
[CODE BLOCK]
1. De mens stuurt een bericht via de web-UI (gebruikt JWT)
2. Het bericht wordt opgeslagen en gemarkeerd als ongelezen
3. De agent pollt tussen tool-aanroepen
4. De poll retourneert alle ongelezen berichten en markeert deze als gelezen
5. De agent verwerkt het bericht en antwoordt optioneel via
Eindpunten
GET /chat/poll
Poll voor nieuwe berichten van de mens. Retourneert ongelezen berichten en markeert
ze als gelezen. Gebruik dit tussen tool-aanroepen.
[CODE BLOCK]
Respons:
[CODE BLOCK]
POST /chat/reply
Stuur een bericht als de agent.
[CODE BLOCK]
POST /chat/send
Stuur een bericht als de mens (vereist JWT, niet Mind Key).
[CODE BLOCK]
GET /chat/history
Haal recente chatgeschiedenis op (beide rollen).
[CODE BLOCK]
GET /chat/unread
Haal het aantal ongelezen berichten op.
[CODE BLOCK]
GET /chat/status
Haal de status van de chatsessie op (laatste bericht-tijdstempels, ongelezen tellers).
[CODE BLOCK]
POST /chat/upload
Upload een bestandsbijlage voor een specifiek bericht (multipart-formulier).
[CODE BLOCK]
GET /chat/files/:messageid
Bekijk bestandsbijlagen voor een bericht.
[CODE BLOCK]
GET /chat/file/:fileid
Download een bestandsbijlage.
[CODE BLOCK]
Polling-patroon
> [!TIP]
> Poll elke 30-60 seconden tussen tool-aanroepen. Poll niet vaker —
> dat verspilt API-quota en levert geen voordeel op.
[CODE BLOCK]
Volgende stappen
- Tasks API
- Chat Polling Pattern
────────────────────────────────────────────────────────────
# Computer Control API
SUMMARY: Bedien geregistreerde computers op afstand — commando's in de wachtrij, schermafbeeldingen, scripts uitvoeren op externe machines.
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
De Computer Control API stelt u in staat geregistreerde computers op afstand te
bedienen. Een kleine agent () draait op de doelmachine, pollt
naar commando's, voert ze uit en stuurt de resultaten terug. Dit maakt door LLM
aangestuurde GUI-automatisering mogelijk.
Architectuur
[CODE BLOCK]
Gebruikersgerichte eindpunten (Mind Key of JWT)
GET /computers/list
Toon alle geregistreerde computers.
[CODE BLOCK]
GET /computers/:id
Haal details op van één computer.
[CODE BLOCK]
POST /computers/install-code
Genereer een installatiecode voor het registreren van een nieuwe computer.
[CODE BLOCK]
Respons:
POST /computers/:id/commands
Plaats een commando in de wachtrij voor uitvoering door de externe agent.
[CODE BLOCK]
Respons:
GET /computers/:id/command (via query)
Plaats een commando via GET (voor eenvoudige gevallen).
[CODE BLOCK]
GET /computers/:id/commands
Toon recente commando's voor een computer.
[CODE BLOCK]
GET /computers/:id/commands/:cid
Haal status + resultaat van een specifiek commando op.
[CODE BLOCK]
GET /computers/:id/screenshot
Eenmalig: plaats een screenshot-commando in de wachtrij en wacht tot 30s op het resultaat.
[CODE BLOCK]
POST /computers/:id/disable
Schakel een computer uit (trekt het token in, behoudt het record voor controle).
[CODE BLOCK]
DELETE /computers/:id
Verwijder een computer permanent.
[CODE BLOCK]
Agent-gerichte eindpunten (Computer Token)
Deze eindpunten worden gebruikt door de die draait op de
doelmachine. Ze gebruiken een Computer Token (geretourneerd door ),
geen Mind Key.
POST /computers/register
Wissel een installatiecode in en ontvang een Computer Token.
[CODE BLOCK]
Respons:
> [!CRITICAL]
> Sla het op — het wordt slechts één keer getoond en is vereist
> voor alle agent-gerichte eindpunten.
GET /computers/me/poll
Long-poll voor nieuwe commando's. De agent roept dit aan in een lus.
[CODE BLOCK]
Retourneert onmiddellijk als er commando's klaarstaan, of na seconden als dat niet zo is.
POST /computers/me/commands/:cid/result
Stuur het resultaat van het uitvoeren van een commando.
[CODE BLOCK]
Commando-typen
| Type | Payload | Beschrijving |
|------|---------|--------------|
| | | Maak schermafbeelding als PNG (base64) |
| | | Klik op coördinaten |
| | | Verplaats muis naar coördinaten |
| | | Typ tekst op cursorpositie |
| | | Druk toetsencombinatie in |
| | | Scroll-wiel |
| | | Slepen en neerzetten |
Veelvoorkomend patroon: door LLM aangestuurde GUI-automatisering
[CODE BLOCK]
Volgende stappen
- Browser Proxy — aparte service voor browserautomatisering
- Self-Hosted Agents Guide
────────────────────────────────────────────────────────────
# Cron & Scheduler
SUMMARY: Plan terugkerende API-aanroepen in — cron-jobs die volgens schema activeren, perfect voor periodieke synchronisatie en herinneringen.
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
De Cron API stelt u in staat terugkerende HTTP-aanroepen naar Synapse-eindpunten
(of externe HTTPS-eindpunten) in te plannen. Perfect voor periodieke synchronisatie,
herinneringen en onderhoudstaken.
Eindpunten
POST /cron
Maak een geplande taak aan.
[CODE BLOCK]
Respons:
[CODE BLOCK]
GET /cron
Toon alle geplande taken.
[CODE BLOCK]
DELETE /cron/:id
Verwijder een geplande taak.
[CODE BLOCK]
PUT /cron/:id/toggle
Schakel een taak in of uit zonder deze te verwijderen.
[CODE BLOCK]
Schema-syntaxis
Standaard cron (5 velden)
[CODE BLOCK]
Voorbeelden:
| Schema | Betekenis |
|--------|-----------|
| | Elk uur |
| | Elke 15 minuten |
| | Doorweektags om 9 uur 's ochtends |
| | Elke zondag om middernacht |
| | De eerste van elke maand om middernacht |
Gehele interval (seconden)
Voor eenvoudige intervallen geeft u een geheel getal op:
[CODE BLOCK]
Eindpuntbeperkingen
> [!WARNING]
> Eindpunten moeten - of -URL's zijn die verwijzen naar:
> - Dezelfde Synapse-instantie (bijv. )
> - Openbare HTTPS-URL's (geen privé-IP's, geen localhost, geen metadata-IP's)
Dit voorkomt SSRF-aanvallen waarbij een gecompromitteerde mind verzoeken naar
interne services kan inplannen.
Veelvoorkomende patronen
Elk uur geheugen ophalen (voor LLM-agents)
[CODE BLOCK]
Dagelijkse back-up
[CODE BLOCK]
Periodieke chat-poll (elke 5 minuten)
[CODE BLOCK]
Wekelijkse rapportage-trigger
[CODE BLOCK]
Volgende stappen
- Variables API
- Webhooks API
────────────────────────────────────────────────────────────
# Fouten & Foutafhandeling
SUMMARY: HTTP-statuscodes, foutresponsformaat en hoe u veelvoorkomende fouten kunt herstellen.
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.
Fouten & Foutafhandeling
Synapse gebruikt standaard HTTP-statuscodes met een consistent foutresponsformaat.
Deze pagina legt uit hoe u fouten kunt interpreteren en ervan kunt herstellen.
Formaat van foutrespons
Alle fouten retourneren JSON met deze structuur:
[CODE BLOCK]
| Veld | Beschrijving |
|------|--------------|
| | HTTP-statuscode |
| | HTTP-statusnaam |
| | Door mensen leesbare foutbeschrijving |
| | URL naar relevante documentatie (indien van toepassing) |
HTTP-statuscodes
200 OK
Succes. Het verzoek is correct verwerkt.
201 Created
Succes. Een nieuwe resource is aangemaakt (bijv. ).
204 No Content
Succes. Geen body geretourneerd (bijv. ).
400 Bad Request
Het verzoek was ongeldig. Veelvoorkomende oorzaken:
- Ontbrekende verplichte JSON-velden
- Ongeldige JSON-syntaxis
- Ongeldige enum-waarde (bijv. verkeerde categorie)
[CODE BLOCK]
Oplossing: Controleer de requestbody tegen de API-documentatie. Zorg dat alle
verplichte velden aanwezig zijn en geldige waarden hebben.
401 Unauthorized
Authenticatie mislukt. Veelvoorkomende oorzaken:
- Ontbrekende -header
- Ongeldige Mind Key of JWT
- Een Mind Key gebruiken waar een JWT vereist is (of omgekeerd)
[CODE BLOCK]
Oplossing: Verifieer uw token. Zie Authenticatie.
403 Forbidden
U bent geauthenticeerd maar mag deze actie niet uitvoeren. Veelvoorkomende oorzaken:
- Poging om een mind van een andere gebruiker te verwijderen
- Poging om een memory te verifiëren met een Mind Key (vereist JWT)
- Mind is uitgeschakeld
Oplossing: Controleer of u het juiste tokentype gebruikt voor dit eindpunt.
404 Not Found
Het aangevraagde pad of de resource bestaat niet.
> [!CRITICAL]
> Raad GEEN eindpuntpaden. Alleen de paden vermeld in
> bestaan. Als u een 404 krijgt, heeft u een verkeerd pad gebruikt.
[CODE BLOCK]
Oplossing: Roep aan om de lijst met geldige eindpunten te zien.
Vergelijk uw URL teken voor teken met de lijst.
409 Conflict
Het verzoek conflicteert met de bestaande staat. Veelvoorkomende oorzaken:
- Poging om te registreren met een e-mailadres dat al bestaat
- Dubbele webhook-URL
Oplossing: Gebruik een andere waarde, of gebruik om de bestaande resource bij te werken.
429 Too Many Requests
U heeft een ratelimit bereikt. Geldt alleen voor -queryparameter-authenticatie (60/min).
[CODE BLOCK]
Responsheaders:
[CODE BLOCK]
Oplossing: Schakel over naar -header (geen ratelimit), of wacht
seconden.
500 Internal Server Error
Serverfout. Dit zou niet moeten gebeuren — als het toch voorkomt, is het een bug.
Oplossing:
1. Probeer opnieuw met exponentiële backoff (1s, 2s, 4s, 8s)
2. Controleer om te zien of de server draait
3. Als het aanhoudt, meld de fout
503 Service Unavailable
De server is tijdelijk niet beschikbaar (bijv. tijdens deployment, databasemigratie).
Oplossing: Wacht en probeer opnieuw. Controleer .
Herstelpatronen
Opnieuw proberen met exponentiële backoff
[CODE BLOCK]
Auth-foutafhandeling
[CODE BLOCK]
Veelvoorkomende foutscenario's
"Mind Key fehlt oder ungültig"
- U bent de -header vergeten
- U heeft gebruikt maar de sleutel is onjuist
- U gebruikt een JWT waar een Mind Key vereist is
"Route not found"
- U heeft een pad geraden dat niet bestaat
- U heeft een werkwoord verkeerd gebruikt (bijv. vs )
- Controleer voor geldige paden
"Rate limit exceeded"
- U gebruikt en heeft 60 aanvragen/min overschreden
- Schakel over naar -header
Volgende stappen
- Authenticatie
- API-overzicht
- Ratelimits
────────────────────────────────────────────────────────────
# Memory API
SUMMARY: Volledige referentie voor de 22 memory-eindpunten: opslaan, ophalen, zoeken, semantisch zoeken, synchroniseren, audit en meer.
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
De Memory API is het hart van Synapse. Het biedt 22 eindpunten voor het opslaan,
ophalen, zoeken en beheren van gestructureerde herinneringen. Alle eindpunten vereisen
een Mind Key voor authenticatie.
> [!CRITICAL]
> Roep altijd aan aan het begin van elke sessie. Dit is
> de enige manier om context van eerdere sessies te herstellen.
Categorieën
Herinneringen zijn ingedeeld in 8 categorieën:
| Categorie | Gebruik |
|-----------|---------|
| | Naam, rol, contactgegevens, voorkeuren over zichzelf |
| | Voorkeuren, afkeuren, werkstijl, communicatievoorkeuren |
| | Verifieerbare feiten (projectdetails, data, URL's) |
| | Projectstatus, mijlpalen, architectuur |
| | Dingen waar de gebruiker goed in is |
| | Eerdere fouten — herhaal ze niet |
| | Sessie-relevante context |
| | Diverse notities |
Prioriteiten
- — leuk om te weten
- — standaard
- — belangrijk
- — mag nooit vergeten worden (gebruikersidentiteit, juridische info)
Kern-eindpunten
GET /memory/recall
Retourneert ALLE herinneringen als op LLM geoptimaliseerde platte tekst. Roep dit aan bij elke sessiestart.
[CODE BLOCK]
Respons (text/plain):
[CODE BLOCK]
POST /memory
Sla een nieuwe herinnering op of werk een bestaande bij (zelfde categorie + key = update).
[CODE BLOCK]
Respons:
GET /memory
Toon herinneringen met optionele filters.
[CODE BLOCK]
PUT /memory/:id
Werk een specifieke herinnering bij op ID.
[CODE BLOCK]
DELETE /memory/:id
Verwijder één herinnering.
[CODE BLOCK]
Zoek-eindpunten
GET /memory/search
Volledige-tekst zoeken met FTS5.
[CODE BLOCK]
FTS5-syntaxis:
- Meerdere woorden = AND:
- Zin:
- Prefix:
- Booleaans:
- Uitsluiten:
GET /memory/semantic-search
Conceptueel zoeken met embeddings (langzamer dan FTS5 maar begrijpt betekenis).
[CODE BLOCK]
Retourneert herinneringen die semantisch overeenkomen met de query, zelfs als er geen
trefwoorden overeenkomen. Handig voor "vind herinneringen over X" waarbij X anders
wordt omschreven.
GET /memory/by-tag
Toon herinneringen per tag.
[CODE BLOCK]
GET /memory/related/:id
Vind herinneringen gerelateerd aan een specifieke herinnering (via gedeelde tags).
[CODE BLOCK]
Synchronisatie & Diff
GET /memory/diff
Incrementele synchronisatie — retourneert herinneringen die sinds een tijdstempel gewijzigd zijn.
[CODE BLOCK]
Respons:
POST /memory/sync
Pas een diff toe vanuit een andere instantie (voor self-hosted synchronisatie).
[CODE BLOCK]
Bulkbewerkingen
POST /memory/bulk-delete
Verwijder meerdere herinneringen op ID.
[CODE BLOCK]
POST /memory/embed-batch
Genereer embeddings voor herinneringen die deze nog niet hebben (voor semantisch zoeken).
[CODE BLOCK]
GET /memory/embed-batch-status
Controleer de voortgang van embedding-generatie.
[CODE BLOCK]
Verificatie
Herinneringen hebben een -vlag. Door agents opgeslagen herinneringen zijn
standaard niet geverifieerd (); door mensen opgeslagen herinneringen
zijn geverifieerd ().
POST /memory/verify
Markeer een herinnering als geverifieerd (vereist JWT, niet Mind Key).
[CODE BLOCK]
POST /memory/unverify
Markeer een herinnering als niet-geverifieerd (vereist JWT).
[CODE BLOCK]
GET /memory/unverified
Toon herinneringen die wachten op menselijke verificatie.
[CODE BLOCK]
Statistieken & Audit
GET /memory/stats
Geaggregeerde statistieken voor de huidige mind.
[CODE BLOCK]
Retourneert:
GET /memory/audit
Auditlog van alle toestandswijzigende bewerkingen.
[CODE BLOCK]
GET /memory/contradictions
Detecteer mogelijke tegenstrijdigheden in opgeslagen herinneringen.
[CODE BLOCK]
GET /memory/expiring
Toon herinneringen met naderende vervaldatums.
[CODE BLOCK]
Health & Export
GET /memory/health
Snelle health check voor het memory-systeem.
[CODE BLOCK]
GET /memory/mind-export
Volledige JSON-export van alle herinneringen (voor back-up).
[CODE BLOCK]
POST /memory/compact
Compacteer vergelijkbare herinneringen (automatische samenvatting).
[CODE BLOCK]
Volgende stappen
- Quick Start voor LLM's
- Memory-best-practices
- FTS5-zoekopdracht
- Semantisch zoeken
────────────────────────────────────────────────────────────
# API-overzicht & Base URL
SUMMARY: Alle Synapse API-eindpunten, base URL, auth-patronen en responsformaten in één oogopslag.
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.
API-overzicht & Base URL
De Synapse API is een RESTful HTTP-API. Alle eindpunten retourneren JSON (behalve waar
vermeld). Deze pagina behandelt de essentiële zaken voordat u naar specifieke
eindpunten duikt.
Base URL
[CODE BLOCK]
Alle paden in deze documentatie zijn relatief ten opzichte van deze base URL. Voor
self-hosted instanties vervangt u dit door uw eigen URL.
Authenticatie
Twee methoden, beide via de -header:
[CODE BLOCK]
Of via queryparameter (ratelimited tot 60/min):
[CODE BLOCK]
Zie Authenticatie voor details.
Eindpuntgroepen
| Groep | Auth | Beschrijving |
|-------|------|--------------|
| Public | Geen | Landingspagina, health, OpenAPI, docs |
| Memory | Mind Key | CRUD, zoeken, synchroniseren, embeddings |
| Chat | Mind Key / JWT | Asynchrone berichtenuitwisseling tussen mens en agent |
| Tasks | Mind Key | Taakbeheer |
| Scripts | Mind Key / JWT | Permanente script-opslag |
| Scheduler | Mind Key | Cron-jobs + variabelen |
| Webhooks | Mind Key | HTTP-callbacks bij gebeurtenissen |
| Computers | Mind Key / JWT | Bediening van computers op afstand |
| User/Minds | JWT | Account + mind-beheer |
| Sharing | JWT | Mind delen tussen gebruikers |
| Push | JWT | Web Push-abonnementen |
| Tools | Geen | Tijd, calc, random (openbare hulpmiddelen) |
Responsformaten
- JSON (standaard):
- Platte tekst: retourneert op LLM geoptimaliseerde tekst
- HTML: , , , ,
Standaard respons-envelope
Succesresponsen retourneren de data direct:
[CODE BLOCK]
Foutresponsen gebruiken dit formaat:
[CODE BLOCK]
> [!NOTE]
> Het -veld verwijst naar relevante documentatie voor veelvoorkomende fouten.
HTTP-statuscodes
| Code | Betekenis |
|------|-----------|
| 200 | Succes (GET, PUT) |
| 201 | Aangemaakt (POST) |
| 204 | Geen inhoud (DELETE) |
| 400 | Onjuist verzoek (validatiefout) |
| 401 | Niet-geautoriseerd (ontbrekend/ongeldig token) |
| 403 | Verboden (verkeerd tokentype) |
| 404 | Niet gevonden (pad bestaat niet) |
| 409 | Conflict (dubbeling) |
| 429 | Te veel verzoeken (ratelimit) |
| 500 | Serverfout |
Ontdekkings-eindpunten
| Eindpunt | Doel |
|----------|------|
| | Landingspagina (op LLM geoptimaliseerd) |
| | Machineleesbare lijst van alle eindpunten |
| | Plattetekst eindpuntlijst |
| | OpenAPI 3.0-specificatie |
| | Volledige API-documentatie (HTML) |
| | API-documentatie als JSON |
| | Documentatiesysteem (HTML) |
| | Documentatie-index (JSON) |
| | Alle documentatie als één tekstblok |
| | Interactieve API-playground |
Ratelimits
| Auth-methode | Limiet |
|--------------|--------|
| Mind Key (header) | Geen |
| Mind Key (?key=) | 60/min per IP |
| JWT (header) | Geen |
| Openbare eindpunten | Geen |
Ratelimited responsen bevatten:
[CODE BLOCK]
Paginering
Lijst-eindpunten ondersteunen en :
[CODE BLOCK]
Standaardlimiet: 100. Maximale limiet: 500.
CORS
Alle eindpunten ondersteunen CORS voor browser-gebaseerde clients:
[CODE BLOCK]
SDK's & Clients
- Node.js SDK: (repo)
- MCP Server: (repo)
- HTTP-client: elke HTTP-bibliotheek (curl, fetch, axios, enz.)
Volgende stappen
- Memory API — de belangrijkste eindpunten
- Chat API — asynchrone communicatie tussen mens en agent
- Fouten & Foutafhandeling
────────────────────────────────────────────────────────────
# Ratelimits & Quota
SUMMARY: Ratelimit-beleid voor de Synapse API — Bearer-header (onbeperkt), ?key= (60/min), openbare eindpunten.
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.
Ratelimits & Quota
Synapse heeft een eenvoudig, voorspelbaar ratelimit-beleid dat is ontworpen om misbruik
te voorkomen zonder legitiem gebruik in de weg te zitten.
Ratelimit-beleid
| Auth-methode | Limiet | Bereik |
|--------------|--------|--------|
| Mind Key () | Geen | Per-mind |
| Mind Key () | 60 aanvragen/min | Per-IP |
| JWT () | Geen | Per-gebruiker |
| Openbare eindpunten | Geen | Globaal |
> [!TIP]
> Gebruik waar mogelijk altijd de -header. Deze heeft geen
> ratelimit. Gebruik alleen voor tools die geen custom headers kunnen instellen.
Ratelimit-headers
Wanneer u -authenticatie gebruikt, bevatten responsen ratelimit-headers:
[CODE BLOCK]
Wanneer u de limiet overschrijdt:
[CODE BLOCK]
Als u een ratelimit raakt
Als u een 429 krijgt:
1. Schakel over naar de Authorization-header (aanbevolen):
[CODE BLOCK]
2. Of wacht seconden en probeer opnieuw.
Waarom de ?key= limiet bestaat
De -queryparameter is handig voor URL-only tools (browsers,
-commando's), maar heeft beveiligings- en prestatie-implicaties:
- Beveiliging: Queryparameters worden gelogd in server-accesslogs, browsergeschiedenis
en Referer-headers. Beperking van gebruik verkleint de blootstelling.
- Prestaties: Queryparameter-authenticatie vereist een IP-gebaseerde ratelimiter
(Redis-lookup per verzoek), wat latency toevoegt. Header-authenticatie slaat dit over.
- Misbruikpreventie: Een gelekte -URL kan worden gedeeld en gebombardeerd.
De IP-limiet beperkt de schade.
Aanbevolen patronen
LLM-agents
[CODE BLOCK]
Browser-gebaseerde tools
Als uw tool alleen URL's kan openen:
[CODE BLOCK]
MCP-server
MCP-servers gebruiken altijd header-authenticatie via de -env-var —
geen ratelimit van toepassing.
Bulk-imports
Voor bulkoperaties (bijv. 1000 herinneringen importeren), gebruik altijd header-authenticatie.
Bulk-imports via raken de ratelimit binnen 1 minuut.
Quota (op mind-niveau)
Er zijn momenteel geen per-mind quota voor opslaggrootte of aantal herinneringen. Alle
limieten zitten op het auth/IP-niveau, niet op dataniveau. Dit kan in de toekomst
veranderen voor multi-tenant fairshare.
Uw gebruik monitoren
[CODE BLOCK]
Volgende stappen
- Authenticatie
- Fouten & Foutafhandeling
────────────────────────────────────────────────────────────
# Scripts API
SUMMARY: Permanente script-opslag — sla herbruikbare shell-, Python- of Node-scripts op en haal ze op via 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
De Scripts API biedt een permanente opslag voor herbruikbare scripts. Scripts worden
binnen een mind benoemd en van een versie voorzien, en kunnen als platte tekst worden
opgehaald — perfect voor -patronen.
Eindpunten
POST /script
Sla een script op of werk het bij.
[CODE BLOCK]
GET /script/:name
Haal scriptinhoud op als . Perfect om naar bash te pipen.
[CODE BLOCK]
GET /script/:name/info
Haal script-metadata op zonder de inhoud.
[CODE BLOCK]
Respons:
[CODE BLOCK]
GET /scripts
Toon alle scripts in de huidige mind.
[CODE BLOCK]
DELETE /script/:name
Verwijder een script.
[CODE BLOCK]
Veelvoorkomende toepassingen
Deployment-scripts
Sla standaard deployment-procedures op zodat de LLM ze kan uitvoeren zonder
de stappen telkens opnieuw af te leiden:
[CODE BLOCK]
Troubleshooting-snippets
Sla diagnostische commando's op voor veelvoorkomende problemen:
[CODE BLOCK]
Configuratiegeneratoren
Sla scripts op die configuraties genereren:
[CODE BLOCK]
Volgende stappen
- Variables API
- Cron & Scheduler
────────────────────────────────────────────────────────────
# Tasks API
SUMMARY: Taakbeheer voor LLM-agents — taken aanmaken, tonen, bijwerken, voltooien en verwijderen met prioriteiten.
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
De Tasks API biedt LLM-agents een gestructureerde manier om werk met meerdere stappen
bij te houden. Taken zijn toegespitst op de huidige mind en blijven bewaard tussen
sessies, zodat de agent het werk kan hervatten waar het was gebleven.
Eindpunten
GET /mind/tasks
Toon alle taken voor de huidige mind.
[CODE BLOCK]
Respons:
[CODE BLOCK]
POST /mind/task
Maak een nieuwe taak aan.
[CODE BLOCK]
GET /mind/task (queryparams)
Maak een taak aan via GET (voor URL-only tools).
[CODE BLOCK]
PUT /mind/task/:id
Werk een bestaande taak bij.
[CODE BLOCK]
GET /mind/task/:id/complete
Markeer een taak als voltooid.
[CODE BLOCK]
GET /mind/task/:id/delete
Verwijder een taak permanent.
[CODE BLOCK]
Prioriteiten
- — niet urgent
- — standaard
- — belangrijk
- — onmiddellijk doen
Statussen
- — aangemaakt, niet gestart
- — wordt momenteel aan gewerkt
- — voltooid
- — afgebroken
Patroon: taakgedreven workflow
[CODE BLOCK]
Volgende stappen
- Task-Driven Workflow
- Cron & Scheduler
────────────────────────────────────────────────────────────
# Hulpmiddelen (tijd, calc, random)
SUMMARY: Openbare hulpeindpunten — server-tijd, veilige rekenmachine, willekeurige-waarde-generator. Geen authenticatie vereist.
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.
Hulpmiddelen
De -eindpunten zijn openbare hulpmiddelen — geen authenticatie vereist.
Ze zijn handig voor LLM-agents die servertijd, veilige wiskunde of willekeurige
waarden nodig hebben.
GET /tools/time
Haal de huidige servertijd, tijdzone en UTC-offset op.
[CODE BLOCK]
Respons:
[CODE BLOCK]
Toepassing: LLM-agents die moeten weten "hoe laat is het nu" voor planning,
tijdstempels of relatieve datumberekeningen.
GET /tools/calc
Veilige rekenmachine — alleen rekenkunde, geen . Ondersteunt , , , ,
, , en getallen.
[CODE BLOCK]
Respons:
[CODE BLOCK]
> [!TIP]
> Gebruik dit in plaats van wiskunde in uw hoofd te doen of via string-parsing.
> Het is veilig (geen code-injectie mogelijk) en accuraat.
Ondersteunde operatoren
- optellen
- aftrekken
- vermenigvuldigen
- delen
- modulo
- haakjes
- Getallen (gehele getallen en decimalen)
Voorbeelden
[CODE BLOCK]
GET /tools/random
Genereer willekeurige waarden.
[CODE BLOCK]
Type-parameters
| Type | Parameters | Uitvoer |
|------|-----------|---------|
| | geen | UUID v4-string |
| | , (standaard 0-100) | Geheel getal |
| | , (standaard 0-100) | Float |
| | , (lengtebereik, standaard 8-16) | Hex-string |
| | , (lengtebereik, standaard 8-16) | Alfabetische string |
Toepassingen voor LLM-agents
Genereer unieke ID's
[CODE BLOCK]
Bereken percentages
[CODE BLOCK]
Haal huidige tijdstempel op
[CODE BLOCK]
Genereer testdata
[CODE BLOCK]
Volgende stappen
- API-overzicht — alle eindpuntgroepen
- Fouten & Foutafhandeling
────────────────────────────────────────────────────────────
# User & Minds API
SUMMARY: Accountbeheer — registreren, inloggen, minds aanmaken, minds tonen, minds verwijderen. JWT-beveiligd.
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
De User & Minds API verzorgt het accountbeheer. Deze eindpunten gebruiken JWT-
authenticatie (niet Mind Keys) omdat ze op accountniveau werken, niet op mind-niveau.
Authenticatie-eindpunten
POST /register
Maak een nieuw gebruikersaccount aan.
[CODE BLOCK]
Respons:
[CODE BLOCK]
POST /login
Log in op een bestaand account.
[CODE BLOCK]
Respons: hetzelfde als .
Minds-eindpunten
POST /minds
Maak een nieuwe mind aan. Retourneert de Mind Key — sla deze onmiddellijk op,
hij wordt slechts één keer getoond.
[CODE BLOCK]
Respons:
[CODE BLOCK]
> [!CRITICAL]
> De wordt slechts één keer getoond. Als u deze verliest, kunt u deze
> niet meer ophalen — u moet de mind verwijderen en een nieuwe aanmaken (waarbij
> alle opgeslagen herinneringen verloren gaan).
GET /minds
Toon alle minds voor de huidige gebruiker.
[CODE BLOCK]
Respons:
[CODE BLOCK]
DELETE /minds/:id
Verwijder een mind permanent.
[CODE BLOCK]
> [!WARNING]
> Het verwijderen van een mind is onomkeerbaar. Alle herinneringen, taken,
> chatgeschiedenis en scripts in die mind gaan permanent verloren. Exporteer
> eerst via als u een back-up nodig heeft.
Multi-mind-patroon
De meeste gebruikers profiteren van meerdere minds om contexten gescheiden te houden:
[CODE BLOCK]
Gebruik verschillende Mind Keys in verschillende LLM-sessies om contexten gescheiden te houden.
Accountbeveiliging
Wachtwoordvereisten
- Minimaal 6 tekens
- Geen maximum (gebruik een wachtwoordmanager)
- Opgeslagen als bcrypt-hash (nooit platte tekst)
JWT-verval
JWT's vervallen na 7 dagen. Wanneer verlopen, roep gewoon opnieuw aan.
Mind Key-beveiliging
Mind Keys vervallen nooit. Als een Mind Key is gecompromitteerd:
1. Maak een nieuwe mind via
2. Werk uw LLM-config bij met de nieuwe Mind Key
3. Verwijder de gecompromitteerde mind via
Volgende stappen
- Authenticatie — volledige auth-handleiding
- Mind Key vs JWT — keuzehandleiding
- Sharing API — deel minds met andere gebruikers
────────────────────────────────────────────────────────────
# Variables API
SUMMARY: Snelle key-value-opslag voor LLM-staat — tellers, vlaggen, laatst-gezien-tijdstempels, gedeeltelijke voortgang.
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
De Variables API is een snelle key-value-opslag voor efemere staat. In tegenstelling
tot herinneringen (die geïndexeerd, doorzoekbaar en gestructureerd zijn), zijn variabelen
geoptimaliseerd voor snelle lees/schrijftoegang — perfect voor tellers, vlaggen en
sessiestaat.
Eindpunten
POST /var
Stel een variabele in of werk deze bij.
[CODE BLOCK]
GET /var/:key
Haal één variabele op.
[CODE BLOCK]
Respons:
[CODE BLOCK]
GET /var
Toon alle variabelen.
[CODE BLOCK]
DELETE /var/:key
Verwijder een variabele.
[CODE BLOCK]
Wanneer variabelen versus memory gebruiken
| Gebruik | Gebruik |
|---------|---------|
| Gebruikersnaam, voorkeuren | Memory (doorzoekbaar, gestructureerd) |
| Laatste sessie-tijdstempel | Variable (efemere staat) |
| Teller (bijv. verzonden berichten) | Variable (veel updates) |
| Workflow-staat ("stap 3 van 5 klaar") | Variable (tijdelijk) |
| Lange projectnotities | Memory (volledige-tekst geïndexeerd) |
| Herbruikbare scripts | Script store (benoemd, van versie voorzien) |
Veelvoorkomende patronen
Laatste sessie bijhouden
[CODE BLOCK]
Teller-patroon
[CODE BLOCK]
Feature flags
[CODE BLOCK]
Volgende stappen
- Memory API — voor gestructureerde, doorzoekbare data
- Cron & Scheduler
────────────────────────────────────────────────────────────
# Webhooks API
SUMMARY: Registreer HTTP-callbacks voor memory-, chat- en taak-gebeurtenissen — wordt op de hoogte gesteld wanneer data verandert.
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
Met webhooks kunt u HTTP-callbacks ontvangen wanneer er gebeurtenissen plaatsvinden in
Synapse. Perfect voor het triggeren van externe automatisering, het sturen van meldingen
of het synchroniseren met andere systemen.
Eindpunten
POST /webhooks
Registreer een nieuwe webhook.
[CODE BLOCK]
Respons:
[CODE BLOCK]
GET /webhooks
Toon alle webhooks voor de huidige mind.
[CODE BLOCK]
GET /webhooks/:id
Haal één webhook op.
[CODE BLOCK]
PUT /webhooks/:id
Werk een webhook bij (URL, events, secret of enabled-vlag).
[CODE BLOCK]
DELETE /webhooks/:id
Verwijder een webhook.
[CODE BLOCK]
Gebeurtenistypen
| Patroon | Vuurt bij |
|---------|-----------|
| | Elke memory-gebeurtenis |
| | Nieuwe herinnering opgeslagen |
| | Herinnering bijgewerkt |
| | Herinnering verwijderd |
| | Elke chat-gebeurtenis |
| | Nieuw bericht van mens |
| | Elke taak-gebeurtenis |
| | Nieuwe taak aangemaakt |
| | Taak als voltooid gemarkeerd |
| | Alle gebeurtenissen |
Webhook-payload
Wanneer een gebeurtenis vuurt, POST Synapse naar uw URL:
[CODE BLOCK]
Handtekeningverificatie
Als u een instelt, ondertekent Synapse elke payload met HMAC-SHA256:
[CODE BLOCK]
Verifieer in uw handler:
[CODE BLOCK]
Patroon: realtime synchronisatie
[CODE BLOCK]
Volgende stappen
- Cron & Scheduler
- Webhook Automation-handleiding
## CATEGORIE: MCP-INTEGRATIE
Integratie met Claude, Cursor en andere MCP-clients.
────────────────────────────────────────────────────────────
# MCP in Claude Code
SUMMARY: Gebruik Synapse-tools vanaf de Claude Code terminal-agent — permanent geheugen voor code-sessies.
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 is de terminal-gebaseerde code-agent van Anthropic. Met Synapse MCP
krijgt Claude Code permanent geheugen tussen code-sessies — het herinnert
uw projectcontext, eerdere beslissingen en codebase-patronen.
Setup
Methode 1: CLI-commando (aanbevolen)
[CODE BLOCK]
Methode 2: Bewerk configuratiebestand
Bewerk :
[CODE BLOCK]
Verifieer dat het werkt
Start Claude Code:
[CODE BLOCK]
In de Claude Code-prompt, typ:
[CODE BLOCK]
Claude zou moeten aanroepen en reageren met uw opgeslagen herinneringen.
Veelvoorkomende patronen
Projectcontext-persistentie
Aan het begin van een code-sessie:
[CODE BLOCK]
Claude roept aan, ziet uw projectlijst, en gaat verder met werk
waar u gebleven was.
Codebase-beslissingen
Wanneer u een architecturale beslissing neemt:
[CODE BLOCK]
Claude roept aan met categorie , prioriteit .
Eerdere fouten vermijden
[CODE BLOCK]
Claude zoekt herinneringen met categorie en herinnert u aan eerdere fouten.
Taak-tracking
[CODE BLOCK]
Claude roept aan, en de taak blijft bewaard tussen sessies.
Tool-profielen
Voor code-sessies waar u niet alle 119 tools nodig heeft:
[CODE BLOCK]
Troubleshooting
MCP-server start niet
[CODE BLOCK]
Mind Key niet herkend
[CODE BLOCK]
Claude Code ziet tools niet
- Herstart Claude Code na configuratiewijzigingen
- Controleer om te verifiëren dat Synapse is geregistreerd
- Zie MCP Troubleshooting
Volgende stappen
- Claude Desktop-setup
- Cursor-setup
- Permanente LLM-agent-handleiding
────────────────────────────────────────────────────────────
# MCP in Claude Desktop
SUMMARY: Verbind Synapse met Claude Desktop in 2 minuten. Claude krijgt 79 Synapse-tools native.
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 is de desktop-app van Anthropic voor macOS en Windows. Met de
Synapse MCP-server geconfigureerd krijgt Claude native toegang tot alle 79 Synapse-
tools — het kan herinneringen opslaan, ophalen, taken beheren, met u chatten, en
meer.
Vereisten
- Claude Desktop-app (macOS of Windows)
- Node.js 18+ geïnstalleerd ()
- Uw Synapse Mind Key
Stap 1: Open het configuratiebestand
- macOS:
- Windows:
Als het bestand niet bestaat, maak het dan aan.
Stap 2: Voeg Synapse MCP-server toe
[CODE BLOCK]
> [!TIP]
> Als u al andere MCP-servers heeft geconfigureerd, voeg dan gewoon het -
> blok toe binnen het bestaande -object.
Stap 3: Herstart Claude Desktop
1. Sluit Claude Desktop volledig (Cmd+Q op macOS, niet alleen venster sluiten)
2. Heropen Claude Desktop
3. Start een nieuwe chat
4. Zoek naar het 🔌-plug-icoon linksonder — het zou "79 tools" moeten zeggen
Stap 4: Test het
In een nieuwe chat, typ:
[CODE BLOCK]
Claude zou de -tool moeten aanroepen en reageren met een samenvatting
van uw opgeslagen herinneringen (of "No memories yet" als uw mind leeg is).
Beschikbare tools (selectie)
| Tool | Beschrijving |
|------|--------------|
| | Alle herinneringen ophalen |
| | Een nieuwe herinnering opslaan |
| | Herinneringen doorzoeken |
| | Taken tonen |
| | Een taak aanmaken |
| | Controleren op nieuwe berichten |
| | Op een bericht antwoorden |
| | Een browsertabblad openen |
| | Geregistreerde computers tonen |
Volledige lijst: Wat is MCP?
Troubleshooting
Geen tools verschijnen in Claude Desktop
1. Verifieer Node.js-versie: (moet ≥ 18 zijn)
2. Controleer dat het configuratiebestand geldige JSON is (geen afsluitende komma's)
3. Herstart Claude Desktop volledig (Cmd+Q, niet alleen sluiten)
4. Controleer Claude Desktop-logs: (macOS)
"Mind Key invalid"-fout
- Verifieer dat begint met
- Krijg een verse sleutel via (vereist JWT van )
- Geen aanhalingstekens rond de sleutel in de JSON
npx niet gevonden
- Installeer Node.js 18+:
- Herstart terminal na installatie
- Op macOS met Homebrew:
Tools worden getoond maar aanroepen falen
- Controleer dat bereikbaar is:
- Verifieer dat uw Mind Key werkt:
- Zie MCP Troubleshooting
Tool-profielen (bespaar tokens)
Als u een kleinere LLM gebruikt of context-tokens wilt besparen, stel een tool-profiel in:
[CODE BLOCK]
Profielen: (8 tools), (25), (119, standaard).
Volgende stappen
- Claude Code-setup
- Cursor-setup
- MCP Troubleshooting
────────────────────────────────────────────────────────────
# MCP in Continue.dev
SUMMARY: Verbind Synapse met Continue.dev — open-source AI-code-assistent voor VS Code en JetBrains.
MCP in Continue.dev
Continue.dev is een open-source AI-code-assistent voor VS Code en JetBrains-
IDE's. Met Synapse MCP krijgt Continue permanent geheugen tussen sessies.
Vereisten
- VS Code of JetBrains IDE
- Continue.dev-extensie geïnstalleerd
- Node.js 18+
- Uw Synapse Mind Key
Setup
Stap 1: Open Continue-configuratie
In VS Code of JetBrains:
1. Open de Continue-extensie-zijbalk
2. Klik op het tandwiel-icoon → "Open config.json"
Of bewerk direct.
Stap 2: Voeg Synapse MCP-server toe
[CODE BLOCK]
Stap 3: Herlaad Continue
Herlaad het VS Code-venster (Cmd+Shift+P → "Reload Window") of herstart uw IDE.
Verifieer dat het werkt
In de Continue-chat:
[CODE BLOCK]
Continue zou moeten aanroepen en reageren met uw opgeslagen herinneringen.
Veelvoorkomende patronen
Projectcontext
[CODE BLOCK]
Continue roept aan, ziet uw project-herinneringen, en gaat verder
met werk waar u gebleven was.
Code-review-patronen
[CODE BLOCK]
Continue vindt uw opgeslagen code-review-patronen en past ze toe.
Pair-programming-geheugen
[CODE BLOCK]
Continue slaat het op als een -herinnering.
Troubleshooting
MCP-server verbindt niet
1. Controleer dat geldige JSON is
2. Verifieer Node.js:
3. Controleer Continue's output-paneel (View → Output → Continue)
4. Herstart IDE
Tools verschijnen niet
- Verifieer dat Continue-versie MCP ondersteunt (≥ 0.9.x)
- Controleer dat -env-var is ingesteld in de configuratie
- Zoek naar MCP-fouten in Continue's logs
Volgende stappen
- Claude Desktop-setup
- Aangepaste MCP-client
────────────────────────────────────────────────────────────
# MCP in Cursor
SUMMARY: Verbind Synapse met Cursor IDE voor permanent projectgeheugen tussen code-sessies.
MCP in Cursor
Cursor is een AI-aangedreven IDE gebaseerd op VS Code. Met Synapse MCP krijgt Cursor
permanent geheugen tussen sessies — het herinnert uw projectbeslissingen,
codebase-patronen en eerdere debugging-sessies.
Vereisten
- Cursor IDE geïnstalleerd ()
- Node.js 18+
- Uw Synapse Mind Key
Setup
Stap 1: Open Cursor-instellingen
In Cursor:
1. Open Instellingen (Cmd+, op macOS, Ctrl+, op Windows/Linux)
2. Zoek naar "MCP" of navigeer naar
Stap 2: Voeg Synapse MCP-server toe
Klik op "Add MCP Server" en configureer:
| Veld | Waarde |
|------|--------|
| Name | |
| Type | |
| Command | |
| Env | |
Stap 3: Bewerk config.json direct (alternatief)
Cursor slaat MCP-config op in :
[CODE BLOCK]
Stap 4: Herstart Cursor
Herstart Cursor volledig (Cmd+Q en heropen op macOS).
Verifieer dat het werkt
In Cursor's chat-paneel (Cmd+L):
[CODE BLOCK]
Cursor zou moeten aanroepen en reageren met uw opgeslagen herinneringen.
Veelvoorkomende patronen
Project-onboarding
Bij het openen van een nieuw project:
[CODE BLOCK]
Cursor roept aan en gaat verder met werk waar u gebleven was.
Architectuurbeslissingen
[CODE BLOCK]
Cursor slaat het op als een -herinnering met -prioriteit.
Debugging-geschiedenis
[CODE BLOCK]
Cursor zoekt naar -herinneringen en herinnert u aan eerdere fixes.
Code-patronen tussen sessies
[CODE BLOCK]
Cursor vindt herinneringen over auth-implementaties die u eerder heeft gedaan.
Troubleshooting
MCP-server verbindt niet
1. Verifieer Node.js: (≥ 18)
2. Test MCP-server: (zou zonder fouten moeten starten)
3. Controleer Cursor's MCP-logs (View → Output → MCP)
4. Herstart Cursor volledig
Tools verschijnen niet
- Controleer dat geldige JSON is
- Verifieer dat -env-var is ingesteld
- Controleer dat Cursor-versie MCP ondersteunt (≥ 0.42)
Mind Key ongeldig
[CODE BLOCK]
Volgende stappen
- Claude Desktop-setup
- Continue.dev-setup
- Permanente LLM-agent-handleiding
────────────────────────────────────────────────────────────
# Bouw een eigen MCP-client
SUMMARY: Maak verbinding met de Synapse MCP-server vanuit uw eigen applicatie via de MCP SDK.
Bouw een eigen MCP-client
Als u uw eigen LLM-applicatie bouwt, kunt u rechtstreeks verbinding maken met
de Synapse MCP-server via de officiële MCP SDK. Hierdoor krijgt uw applicatie
toegang tot alle 79 Synapse-tools.
SDK's
| Taal | Package |
|------|---------|
| TypeScript/JavaScript | |
| Python | |
TypeScript-voorbeeld
Installeren
[CODE BLOCK]
Verbinden via stdio
[CODE BLOCK]
Verbinden via HTTP/SSE (extern)
[CODE BLOCK]
Python-voorbeeld
Installeren
[CODE BLOCK]
Verbinden via stdio
[CODE BLOCK]
Toolprofielen
Bij het verbinden kunt u een specifiek toolprofiel aanvragen via de
-header (HTTP/SSE) of de -omgevingsvariabele (stdio):
[CODE BLOCK]
Foutafhandeling
[CODE BLOCK]
Toepassingen
- Eigen AI-assistenten — bouw uw eigen agent met blijvend geheugen
- Workflow-automatisering — koppel Synapse-tools in eigen workflows
- Data-pipelines — extraheer herinneringen, transformeer, laad elders
- Monitoring-dashboards — toon geheugenstatistieken, chatgeschiedenis, taken
Volgende stappen
- MCP-specificatie
- Synapse MCP-repo
- API-overzicht
────────────────────────────────────────────────────────────
# MCP-probleemoplossing
SUMMARY: Los veelvoorkomende MCP-integratieproblemen op — server start niet, tools verschijnen niet, auth-fouten.
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/
MCP-probleemoplossing
Veelvoorkomende problemen en oplossingen bij het integreren van Synapse MCP met uw LLM-client.
Snelle diagnosecontrole
1. ✅ Node.js 18+ geïnstalleerd? ()
2. ✅ Mind Key begint met ? (niet JWT )
3. ✅ Synapse-API bereikbaar? ()
4. ✅ Mind Key werkt? ()
5. ✅ Config-bestand is geldige JSON? (geen komma's aan het einde, geen opmerkingen)
6. ✅ Client herstart na config-wijziging?
7. ✅ MCP-server start handmatig? ()
Probleem: er verschijnen geen tools in de client
Symptomen
- Claude Desktop / Cursor / Continue toont 0 tools
- Geen 🔌-icoon of "synapse"-vermelding in de lijst met MCP-servers
Oplossingen
1. Start de client volledig opnieuw — Cmd+Q op macOS (niet alleen het venster sluiten)
2. Controleer de locatie van het config-bestand:
- Claude Desktop macOS:
- Claude Desktop Windows:
- Cursor:
- Continue:
3. Valideer de JSON — plak de configuratie in
4. Controleer de client-logs op MCP-fouten:
- Claude Desktop: (macOS)
- Cursor: View → Output → MCP
5. Start de MCP-server handmatig om opstartfouten te zien:
[CODE BLOCK]
Probleem: foutmelding "Mind Key invalid"
Symptomen
- Tools verschijnen, maar aanroepen mislukken met "401 Unauthorized"
- Foutmelding: "Mind Key fehlt oder ungültig"
Oplossingen
1. Verifieer het formaat van de Mind Key — begint met , ongeveer 40 tekens
2. Test direct:
[CODE BLOCK]
3. Controleer of de omgevingsvariabele is ingesteld — voor stdio-transport moet de omgevingsvariabele in de MCP-serverconfiguratie staan, niet in uw shell
4. Vraag een nieuwe Mind Key aan:
[CODE BLOCK]
Probleem: npx niet gevonden
Symptomen
- Foutmelding: "npx: command not found"
- MCP-server start niet
Oplossingen
1. Installeer Node.js 18+:
- macOS: of download via
- Linux:
- Windows: download via
2. Herstart de terminal na installatie
3. Verifieer:
Probleem: SYNAPSEURL onbereikbaar
Symptomen
- MCP-server start, maar tool-aanroepen time-out
- Foutmelding: "fetch failed" of "ECONNREFUSED"
Oplossingen
1. Test de verbinding:
[CODE BLOCK]
2. Controleer de bedrijfsfirewall — blokkeert mogelijk uitgaand HTTPS-verkeer
3. Probeer een alternatieve URL:
- Productie:
- MCP-server:
4. Voor self-hosted: zorg dat uw Synapse-instantie draait en bereikbaar is
Probleem: MCP-server crasht
Symptomen
- MCP-server sluit direct na het opstarten af
- Client-logs tonen "MCP server disconnected"
Oplossingen
1. Voer handmatig uit om de fout te zien:
[CODE BLOCK]
2. Controleer op poortconflicten — de MCP-server gebruikt standaard poort 13100
3. Wis de npx-cache:
[CODE BLOCK]
4. Werk bij naar de laatste versie:
[CODE BLOCK]
Probleem: tool-aanroepen retourneren 429
Symptomen
- Foutmelding: "Rate limit exceeded"
Oplossingen
Dit zou niet moeten voorkomen met MCP (gebruikt header-auth, geen rate limit). Mocht het toch voorkomen:
1. Controleer of u ergens gebruikt — schakel over op header-auth
2. Verifieer — zorg dat deze naar de juiste instantie wijst
3. Neem contact op met support als het probleem aanhoudt
Probleem: tools verschijnen, maar werken niet
Symptomen
- Tools worden in de client getoond
- Een tool aanroepen levert een foutmelding of geen resultaat op
Oplossingen
1. Controleer de toolnaam — moet exact kloppen (bijv. , niet )
2. Verifieer de argumenten — controleer het inputschema van de tool
3. Test via de directe API:
[CODE BLOCK]
4. Controleer de gezondheid van Synapse:
[CODE BLOCK]
Hulp krijgen
Als geen van de bovenstaande oplossingen uw probleem verhelpt:
1. Controleer bestaande issues:
2. Open een nieuw issue met:
- MCP-serverversie ()
- Naam en versie van de client
- Besturingssysteem
- Relevante logfragmenten
- Stappen om te reproduceren
Volgende stappen
- Claude Desktop-instellatie
- Claude Code-instellatie
- API-fouten
────────────────────────────────────────────────────────────
# Wat is MCP?
SUMMARY: Model Context Protocol laat LLM's externe tools aanroepen. Synapse biedt 79 tools via de officiële MCP-server.
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
Wat is MCP?
Het Model Context Protocol (MCP) is een open standaard van Anthropic (2024)
die LLM's op een gestructureerde manier externe tools laat aanroepen. In plaats
van API-documentatie in de prompt te plakken, registreert u tools bij de
MCP-server, en de LLM roept ze aan wanneer nodig — vergelijkbaar met function
calling, maar gestandaardiseerd en onafhankelijk van de client.
Synapse MCP-server
Synapse wordt geleverd met een officiële MCP-server ( op npm)
die 79 tools beschikbaar maakt die alle Synapse-functies dekken:
| Categorie | Tools | Aantal |
|-----------|-------|--------|
| 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 |
| Totaal | | 79+ |
Hoe het werkt
[CODE BLOCK]
1. U configureert uw LLM-client (Claude Desktop, Cursor, enz.) om de Synapse MCP-server te gebruiken
2. De client start de MCP-server (via )
3. De MCP-server verbindt met de Synapse-API via uw Mind Key
4. De LLM ziet alle 79 tools als native functies die deze kan aanroepen
5. Wanneer de LLM iets moet onthouden, roept deze aan — de MCP-server vertaalt dit naar op Synapse
Transports
De Synapse MCP-server ondersteunt drie transports:
stdio (lokaal, aanbevolen voor desktop)
[CODE BLOCK]
HTTP/SSE (extern, multi-tenant)
Verbind uw MCP-client met:
[CODE BLOCK]
WebSocket (mobiel, hoog volume)
[CODE BLOCK]
Toolprofielen (v1.4.0)
Om de token-overhead voor kleinere LLM's te beperken, ondersteunt de MCP-server
drie toolprofielen:
| Profiel | Tools | Tokens | Geschikt voor |
|---------|-------|--------|---------------|
| | 8 (samengestelde dispatch) | 500 | Self-hosted LLM's met ≤8k context |
| | 25 (benoemde) | 2,500 | LLM's van gemiddelde grootte (Claude Haiku, GPT-3.5) |
| | 119 (alle) | 8,250 | Grote LLM's (Claude Sonnet/Opus, GPT-4) — standaard |
Bedienen via:
- Omgevingsvariabele:
- Header:
Ondersteunde clients
- Claude Desktop — desktop-app van Anthropic
- Claude Code — terminal-coding-agent
- Cursor — AI-aangedreven IDE
- Continue.dev — open-source AI-coding-assistant
- Cline — VS Code-extensie
- Elke MCP-compatibele client
Waarom MCP gebruiken in plaats van de directe API?
| Methode | Voordelen | Nadelen |
|---------|-----------|---------|
| Directe API | Eenvoudig, geen extra laag | LLM moet URL's, headers en auth kennen |
| MCP | LLM ziet native tools, geen URL-geheugen nodig | Extra MCP-serverproces |
Voor de meeste gebruiksscenario's met LLM-agents is MCP de betere keuze — de LLM
hoeft geen API-paden of auth-patronen te onthouden.
Volgende stappen
- Claude Desktop-instellatie — configuratie in 2 minuten
- Claude Code-instellering — terminal-integratie
- Eigen MCP-client — bouw uw eigen client
## CATEGORIE: GIDSEN EN TUTORIALS
Stap-voor-stap gidsen voor concrete scenario's.
────────────────────────────────────────────────────────────
# Geautomatiseerde iOS-app-testen
SUMMARY: Gebruik Synapse + Computer Control API om iOS-app-tests te automatiseren via Simulator.
Geautomatiseerde iOS-app-testen
Combineer het memory-systeem van Synapse met de Computer Control API om door LLM
aangedreven iOS-app-tests te bouwen. De LLM herinnert testscenario's, leert van eerdere
fouten, en past zich aan UI-wijzigingen aan.
Architectuur
[CODE BLOCK]
Vereisten
- Synapse-account + Mind Key
- Synapse MCP-server geconfigureerd in Claude Desktop
- iOS Simulator met geïnstalleerd
- Computer geregistreerd in Synapse (zie Computer Control API)
Stap 1: Registreer de Simulator-computer
Op de Mac waarop iOS Simulator draait:
[CODE BLOCK]
Stap 2: Sla testscenario's op in memory
Sla herbruikbare testscenario's op als herinneringen:
[CODE BLOCK]
Stap 3: Door LLM aangedreven testuitvoering
In Claude Desktop (met Synapse MCP geconfigureerd):
[CODE BLOCK]
Claude zal:
1. aanroepen om de -herinnering te vinden
2. aanroepen om de huidige staat te zien
3. Elke stap uitvoeren via (klik, typ)
4. Resultaten verifiëren via schermafbeeldingen
5. Eventuele fouten opslaan als -herinneringen
Stap 4: Zelfherstellende tests
Wanneer een test faalt, sla de fout en het herstel op:
[CODE BLOCK]
De volgende keer dat de LLM de test uitvoert, haalt hij de fout op en past hij het
herstel automatisch toe.
Stap 5: Testresultaat-tracking
Volg testruns als taken:
[CODE BLOCK]
Veelvoorkomende commando's
| Actie | Commando |
|-------|----------|
| Simulator starten | |
| Schermafbeelding | (via Synapse MCP) |
| Tik op (x,y) | |
| Typ tekst | |
| Druk op Home | |
Best practices
> [!TIP]
> - Sla UI-coördinaten op als herinneringen — UI verandert, maar de LLM kan opnieuw leren
> - Gebruik accessibility-labels — stabieler dan coördinaten
> - Sla testdata apart op — gebruik variabelen voor gebruikersnamen, wachtwoorden
> - Draai tests in schone staat — reset Simulator tussen runs
> - Log schermafbeeldingen bij fouten — nuttig voor debugging
Volgende stappen
- Zelfherstellende tests
- Computer Control API
- Memory-best-practices
────────────────────────────────────────────────────────────
# Back-up & Restore
SUMMARY: Exporteer uw herinneringen voor back-up, migreer tussen minds, herstel na dataverlies.
Back-up & Restore
Synapse biedt volledige export/import voor memory-back-up, migratie en disaster-
recovery. Deze handleiding behandelt de essentiële operaties.
Export
Volledige mind-export
Exporteer alle herinneringen in een mind als JSON:
[CODE BLOCK]
Responsformaat:
[CODE BLOCK]
Incrementele export (Diff)
Exporteer alleen herinneringen die sinds een tijdstempel zijn gewijzigd:
[CODE BLOCK]
Respons:
[CODE BLOCK]
Geautomatiseerde back-ups
Plan dagelijkse back-ups via cron:
[CODE BLOCK]
> [!NOTE]
> Het cron-eindpunt ontvangt de respons maar slaat deze niet op. Voor echte
> back-ups, richt de cron op uw eigen back-upserver die de respons opslaat.
Beter: extern back-upscript
[CODE BLOCK]
Toevoegen aan crontab:
[CODE BLOCK]
Restore
Herstel naar dezelfde mind
[CODE BLOCK]
Herstel naar nieuwe mind
[CODE BLOCK]
Python-herstelscript
[CODE BLOCK]
Migratie tussen minds
[CODE BLOCK]
Back-up van andere data
Vergeet niet te back-uppen:
| Datatype | Eindpunt |
|----------|----------|
| Memories | |
| Tasks | |
| Scripts | |
| Webhooks | |
| Cron jobs | |
| Variables | |
| Chat history | |
Verificatie
Na herstel, verifieer:
[CODE BLOCK]
Best practices
> [!TIP]
> - Back-up dagelijks — automatiseer met cron
> - Test restores — een back-up die u niet kunt herstellen is nutteloos
> - Bewaar meerdere versies — minimaal 30 dagen
> - Sla offsite op — S3, Backblaze B2, enz.
> - Versleutel gevoelige back-ups — herinneringen kunnen PII bevatten
> - Documenteer het herstelproces — u bent het vergeten tegen de tijd dat u het nodig heeft
Volgende stappen
- Memory API
- Cron & Scheduler — voor geautomatiseerde back-ups
────────────────────────────────────────────────────────────
# Memory-best-practices
SUMMARY: Hoe u herinneringen structureert voor effectieve recall — categorieën, sleutels, tags, prioriteiten.
Memory-best-practices
Hoe u herinneringen structureert bepaalt hoe nuttig ze zijn. Deze handleiding behandelt
patronen voor het categoriseren, taggen en prioriteren van herinneringen zodat de LLM
de juiste informatie op het juiste moment kan ophalen.
Categorieën: kies de meest specifieke
| Categorie | Gebruik voor | Voorbeeld |
|-----------|--------------|-----------|
| | Gebruikersnaam, rol, contactgegevens | |
| | Voorkeuren, afkeuren, werkstijl | |
| | Verifieerbare feiten | |
| | Projectstatus, beslissingen | |
| | Vaardigheden van de gebruiker | |
| | Eerdere fouten om te vermijden | |
| | Sessie-relevante context | |
| | Diverse notities | |
> [!TIP]
> Bij twijfel, gebruik voor verifieerbare info en voor al het andere.
> Over-categoriseer niet — beter een duidelijke dan een verwarrende .
Sleutels: betekenisvolle identificatoren
Het -veld is de identificator van de herinnering. Gebruik betekenisvolle, stabiele sleutels:
Goede sleutels:
-
-
-
-
Slechte sleutels:
- (niet betekenisvol)
- (niet beschrijvend)
- (datum helpt niet bij recall)
Sleutelnaamconventies
- (kleine letters met underscores)
- Voorvoeg met categorie: , ,
- Gebruik beschrijvende zelfstandige naamwoorden, niet werkwoorden
- Houd onder 50 tekens
Tags: voor zoeken en filteren
Tags maken snelle filtering en zoekopdrachten mogelijk. Voeg 2-5 tags toe per herinnering:
[CODE BLOCK]
Tag-patronen
- Projectnamen: , ,
- Onderwerpen: , , ,
- Status: , ,
- Prioriteitsindicatoren: ,
> [!NOTE]
> Tags zijn niet hoofdlettergevoelig. Gebruik kleine letters voor consistentie.
Prioriteiten: wees realistisch
| Prioriteit | Gebruik voor | % van herinneringen |
|------------|--------------|---------------------|
| | Gebruikersidentiteit, juridische info, onomkeerbare beslissingen | 5% |
| | Actieve projecten, belangrijke voorkeuren | 20% |
| | Meeste feiten, notities, context | 65% |
| | Efemeer, leuk-om-te-weten | 10% |
> [!WARNING]
> Markeer niet alles . Als alles kritiek is, is niets dat.
> Reserveer voor dingen die echte schade veroorzaken als ze vergeten worden.
Wanneer wel en niet opslaan
Sla altijd op
- Gebruikersidentiteit (naam, e-mail, rol)
- Langetermijnvoorkeuren
- Projectbeslissingen en rationaal
- Eerdere fouten en geleerde lessen
- Gemaakte toezeggingen aan de gebruiker
- Niet opslaan
- Tijdelijke staat (gebruik variabelen)
- Letterlijke gespreksgeschiedenis (chat-systeem handelt dit af)
- Gevoelige data (wachtwoorden, API-sleutels)
- Gemakkelijk af te leiden feiten (huidige datum, bestandsinhouden)
- Efemere context (gebruik -categorie met lage prioriteit)
Herinneringen bijwerken
POST met dezelfde + werkt de bestaande herinnering bij:
[CODE BLOCK]
> [!TIP]
> Gebruik stabiele sleutels zodat u kunt bijwerken zonder duplicaten te maken. De LLM
> moet dezelfde sleutel opnieuw POSTen als info verandert, niet nieuwe herinneringen maken.
Memory-levenscyclus
[CODE BLOCK]
- Create: POST /memory met volledige context
- Active: Vaak ophalen, zo nodig bijwerken
- Stale: Nog relevant maar niet actief gebruikt (lagere prioriteit?)
- Archive: Stel prioriteit in op , bewaar voor historische referentie
- Delete: DELETE /memory/:id wanneer niet meer relevant
Periodieke opschoning
[CODE BLOCK]
Patroon: memory-overerving
Voor hiërarchische context (project → subproject → taak):
[CODE BLOCK]
De LLM kan dan zoeken om alle gerelateerde herinneringen te vinden.
Patroon: beslissingslogboek
Sla beslissingen met rationaal op zodat de LLM ze niet heroverweegt:
[CODE BLOCK]
Patroon: foutvermijding
Sla fouten op met specifieke vermijdingsinstructies:
[CODE BLOCK]
Anti-patronen om te vermijden
> [!WARNING]
> - Gesprekslogs opslaan — chat-systeem handelt dit af
> - Volledige bestanden opslaan — gebruik script store of externe opslag
> - Efemere staat opslaan — gebruik variabelen
> - Geheimen opslaan — gebruik omgevingsvariabelen
> - Herinneringen dupliceren — gebruik stabiele sleutels
> - Over-taggen — 2-5 tags per herinnering is ideaal
> - Alles is kritiek — wees realistisch met prioriteiten
Volgende stappen
- Memory API
- Permanente LLM-agent
- Memory-tagging-strategie
────────────────────────────────────────────────────────────
# Multi-agent-coördinatie
SUMMARY: Coördineer meerdere LLM-agents met gedeelde Synapse-minds, taken en chat.
Multi-agent-coördinatie
Wanneer u meerdere LLM-agents heeft die aan gerelateerde taken werken, biedt Synapse
de coördinatielaag — gedeeld geheugen, taaktoewijzing en asynchrone chat.
Patronen
Patroon 1: Gedeelde mind (enkele bron van waarheid)
Alle agents delen één Mind Key. Ze lezen/schrijven naar dezelfde memory-opslag.
[CODE BLOCK]
Toepassing: Klein team van agents aan één project.
Setup:
[CODE BLOCK]
Coördinatie via taken:
[CODE BLOCK]
Patroon 2: Gespecialiseerde minds (geïsoleerde contexten)
Elke agent heeft zijn eigen mind. Ze communiceren via een gedeelde "coördinatie"-mind.
[CODE BLOCK]
Toepassing: Agents met verschillende specialiteiten (coderen, review, deployment).
Setup:
[CODE BLOCK]
Coördinatie via gedeelde mind:
[CODE BLOCK]
Patroon 3: Hub-and-Spoke (orchestrator)
Een centrale orchestrator-agent wijst taken toe aan worker-agents.
[CODE BLOCK]
Toepassing: Complexe workflows met parallel werk.
Implementatie:
[CODE BLOCK]
Coördinatie via chat
Agents kunnen communiceren via het chat-systeem:
[CODE BLOCK]
> [!NOTE]
> Chatberichten zijn role-tagged. Stel role=agent in voor agent-naar-agent-berichten,
> role=human voor mens-naar-agent.
Coördinatie via variabelen
Gebruik variabelen voor lichte coördinatie (locks, vlaggen):
[CODE BLOCK]
Best practices
> [!TIP]
> - Gebruik aparte minds voor aparte zaken — meng coder- en review-memory niet
> - Tag agents in chat — voor duidelijke adressering
> - Gebruik taken voor werktoewijzing — niet chat (chat is voor discussie)
> - Implementeer idempotentie — agents kunnen mislukte operaties opnieuw proberen
> - Log alles — sla beslissingen op in memory voor auditability
Volgende stappen
- Permanente LLM-agent
- LLM-cookbook
- Webhook-automatisering
────────────────────────────────────────────────────────────
# Bouw een permanente LLM-agent
SUMMARY: Stap-voor-stap handleiding om een LLM-agent te bouwen die herinnert tussen sessies met Synapse.
Overzicht
Deze handleiding leidt u door het bouwen van een LLM-agent die context persistent maakt
tussen sessies met Synapse. Aan het einde zal uw agent:
- Eerdere context ophalen bij sessiestart
- Nieuwe leermomenten opslaan terwijl ze gebeuren
- Taken met meerdere stappen tussen sessies volgen
- Communiceren met mensen via asynchrone chat
Architectuur
[CODE BLOCK]
Stap 1: Stel Mind Key in
[CODE BLOCK]
Stap 2: Sessiestart-protocol
Aan het begin van elke sessie, haal alle herinneringen op:
[CODE BLOCK]
Stap 3: Sla nieuwe leermomenten op
Wanneer de agent iets leert dat het onthouden waard is:
[CODE BLOCK]
Stap 4: Taakbeheer
Volg werk met meerdere stappen tussen sessies:
[CODE BLOCK]
Stap 5: Asynchrone chat met mensen
Poll voor berichten tussen tool-aanroepen:
[CODE BLOCK]
Stap 6: Sessie-einde-protocol
Bij sessie-einde, sla uiteindelijke context op:
[CODE BLOCK]
Volledig patroon
[CODE BLOCK]
Best practices
> [!TIP]
>
> - Haal altijd eerst op — start nooit werk zonder context te laden
> - Sla proactief op — wacht niet tot sessie-einde
> - Gebruik betekenisvolle sleutels — , , niet
> - Tag alles — tags sturen zoeken en filteren
> - Stel realistische prioriteiten in — niet alles is
Volgende stappen
- LLM-cookbook — praktische patronen
- Memory-best-practices
- Multi-agent-coördinatie
────────────────────────────────────────────────────────────
# Zelfherstellende test-pijplijnen
SUMMARY: Bouw test-pijplijnen die leren van fouten en zich automatisch aanpassen met Synapse-memory.
Zelfherstellende test-pijplijnen
Traditionele test-suites breken wanneer de UI verandert. Zelfherstellende tests gebruiken
Synapse-memory om te leren van eerdere fouten en zich aan te passen — wat flaky tests
en onderhoudslast vermindert.
Concept
[CODE BLOCK]
1. Test draait
2. Als het faalt, sla de fout op (wat ging er mis, waarom, hoe te fixen)
3. Volgende run: haal relevante fouten op vóór uitvoering
4. Pas bekende fixes automatisch toe
Implementatie
Stap 1: Test-wrapper
Wikkel elke test met memory-recall/opslag:
[CODE BLOCK]
Stap 2: Adaptieve testlogica
Binnen de test, controleer op bekende fouten en pas fixes toe:
[CODE BLOCK]
Stap 3: Herstelstrategieën
Sla herstelstrategieën op als herinneringen:
[CODE BLOCK]
Stap 4: CI-integratie
[CODE BLOCK]
Stap 5: Fout-analyse-dashboard
[CODE BLOCK]
Best practices
> [!TIP]
> - Sla tracebacks op — ze bevatten de exacte regel die faalde
> - Tag op testnaam — maakt snelle filtering mogelijk
> - Gebruik -categorie — scheidt van gewone herinneringen
> - Stel prioriteit in — fouten mogen nooit vergeten worden
> - Periodieke opschoning — verwijder herinneringen voor opgeloste problemen
> - Sla geen gevoelige data op — credentials, PII
Veelvoorkomende foutpatronen om op te slaan
| Fouttype | Wat op te slaan |
|----------|-----------------|
| Element niet gevonden | Gebruikte selector, paginastaat, schermafbeelding |
| Timeout | Wachttijd, waarop gewacht werd |
| Assertion mislukt | Verwachte vs werkelijke waarde |
| Netwerkfout | URL, statuscode, responsebody |
| Toestemming geweigerd | Vereiste toestemming, huidige gebruikersrol |
Volgende stappen
- Geautomatiseerde iOS-testen
- Memory-best-practices
- Error-recovery-cookbook
────────────────────────────────────────────────────────────
# Webhook-automatisering
SUMMARY: Trigger externe systemen wanneer herinneringen veranderen — sync, meld, automatiseer.
Webhook-automatisering
Met webhooks kunt u externe systemen triggeren wanneer Synapse-gebeurtenissen vuren. Deze handleiding
behandelt veelvoorkomende automatiseringspatronen.
Veelvoorkomende patronen
Patroon 1: Melding bij kritieke herinnering
Stuur een Slack-bericht wanneer een kritieke herinnering wordt opgeslagen:
[CODE BLOCK]
Registreer de webhook:
[CODE BLOCK]
Patroon 2: Synchroniseer naar extern systeem
Synchroniseer herinneringen naar Notion, Obsidian of een externe KB:
[CODE BLOCK]
Patroon 3: Trigger CI/CD
Trigger een deployment wanneer een "release"-herinnering wordt opgeslagen:
[CODE BLOCK]
Patroon 4: Word agent wakker bij menselijk bericht
Trigger een LLM-agent-run wanneer een mens een chatbericht stuurt:
[CODE BLOCK]
Patroon 5: Geaggregeerde metrics
Volg memory-groei, chat-activiteit, taakvoltooiing:
[CODE BLOCK]
Handtekeningverificatie
Verifieer altijd webhook-handtekeningen om spoofing te voorkomen:
[CODE BLOCK]
Retry-logica
Synapse probeert mislukte webhooks opnieuw met exponentiële backoff. Uw handler moet:
1. Snel 200 retourneren — doe niet zwaar werk synchroon
2. Werk in wachtrij plaatsen — gebruik een achtergrond-job-systeem
3. Idempotent zijn — dezelfde gebeurtenis kan twee keer worden geleverd
[CODE BLOCK]
Webhooks debuggen
Leveringsgeschiedenis controleren
Webhook-leveringen worden gelogd. Controleer recente leveringen van uw webhook:
[CODE BLOCK]
Test webhook handmatig
[CODE BLOCK]
Veelvoorkomende problemen
| Probleem | Oplossing |
|----------|-----------|
| 4xx-responsen | Controleer dat uw handler 200 retourneert |
| 5xx-responsen | Serverfout — controleer uw app-logs |
| Timeout | Retourneer 200 snel, wachtrij werk asynchroon |
| Dubbele leveringen | Maak handler idempotent |
| Handtekening-kloppingsprobleem | Verifieer dat secret correct is |
Best practices
> [!TIP]
> - Verifieer altijd handtekeningen — sla dit nooit over
> - Retourneer 200 snel — blokkeer Synapse niet
> - Wees idempotent — handel dubbele leveringen af
> - Gebruik specifieke events — niet
> - Monitor leveringsfouten — stel alerting in
Volgende stappen
- Webhooks API
- Cron & Scheduler
- Permanente LLM-agent
## CATEGORIE: CONCEPTEN
Architectuur en concepten achter Synapse.
────────────────────────────────────────────────────────────
# Synapse-architectuur
SUMMARY: Hoe Synapse is opgebouwd — Fastify, PostgreSQL, FTS5, embeddings, MCP-server.
Synapse-architectuur
Synapse is een multi-tenant memory-API gebouwd op Fastify, PostgreSQL met FTS5,
en een optionele embeddings-service voor semantisch zoeken.
Architectuur op hoog niveau
[CODE BLOCK]
Kerncomponenten
1. Synapse API (Fastify)
De hoofd-HTTP-server. Verwerkt:
- REST-eindpunten (, , , enz.)
- Authenticatie (Mind Key voor agents, JWT voor mensen)
- Ratelimiting (alleen -auth)
- Statische bestandsweergave (web-UI op , , enz.)
- Webhook-dispatch
Gebouwd met Fastify 5 voor prestaties. Draait op poort 12800 in productie.
2. PostgreSQL met FTS5
De primaire datastore. Gebruikt PostgreSQL met de FTS5-extensie voor
volledige-tekst zoekopdrachten.
Belangrijke tabellen:
| Tabel | Doel |
|-------|------|
| | Gebruikersaccounts |
| | Mind-scopes (elk heeft een Mind Key) |
| | Memory-records met FTS5 virtuele tabel |
| | Taakbeheer |
| | Chatgeschiedenis |
| | Permanente scripts |
| | Webhook-registraties |
| | Geplande taken |
| | Key-value-opslag |
| | Audittrail |
FTS5 maakt sub-milliseconde volledige-tekst zoekopdrachten mogelijk over alle
memory-inhoud. Zie FTS5-zoekopdracht voor details.
3. Embeddings-service (optioneel)
Voor semantisch zoeken genereert Synapse vector-embeddings van memory-inhoud.
Deze worden naast herinneringen opgeslagen en gebruikt voor similariteitszoekopdrachten.
- Provider: configureerbaar (OpenAI, lokaal model, enz.)
- Opgeslagen als -kolom in de -tabel
- Gebruikt door het -eindpunt
- Zie Semantisch zoeken
4. MCP-server (aparte service)
De Synapse MCP-server draait als een apart proces (poort 13100). Deze:
- Stelt 79 tools beschikbaar via Model Context Protocol
- Ondersteunt stdio-, HTTP/SSE- en WebSocket-transporten
- Vertaalt MCP-tool-aanroepen naar Synapse API-aanroepen
- Multi-tenant: één Mind Key per sessie
5. Browser Proxy (aparte service)
Voor browserautomatisering draait een aparte Playwright-gebaseerde service op poort 13000.
De MCP-server kan deze aanroepen voor -tools.
6. SSH Proxy (aparte service)
Voor SSH-gebaseerde commando's op afstand draait een aparte service op poort 12900.
Multi-tenant-model
[CODE BLOCK]
Elke mind is volledig geïsoleerd. Mind Keys verlenen toegang tot precies één mind.
JWT's verlenen toegang tot het gebruikersaccount (voor het beheren van minds).
Zie Multi-tenancy voor details.
Verzoek-flow
Memory-opslagverzoek
[CODE BLOCK]
Memory-zoekverzoek
[CODE BLOCK]
Deployment
Synapse wordt uitgerold als Docker-container. Zie :
[CODE BLOCK]
Prestatiekenmerken
| Bewerking | Latentie | Doorvoer |
|-----------|----------|----------|
| 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 |
Volgende stappen
- Memory-model
- Multi-tenancy
- FTS5-zoekopdracht
────────────────────────────────────────────────────────────
# FTS5 volledige-tekst zoekopdracht
SUMMARY: Hoe Synapse SQLite FTS5 gebruikt voor sub-milliseconde volledige-tekst memory-zoekopdrachten.
FTS5 volledige-tekst zoekopdracht
Synapse gebruikt FTS5 (Full-Text Search 5) voor snelle, flexibele memory-zoekopdrachten.
Deze pagina legt uit hoe het werkt en hoe u het effectief kunt gebruiken.
Wat is FTS5?
FTS5 is een SQLite-extensie (ook beschikbaar in PostgreSQL via extensies) die
volledige-tekst zoekmogelijkheden biedt. Het:
- Indexeert tekstinhoud voor snelle trefwoordzoekopdrachten
- Ondersteunt booleaanse operatoren (AND, OR, NOT)
- Ondersteunt overeenkomsten met zinnen via aanhalingstekens
- Ondersteunt prefix-overeenkomsten met
- Rangschikt resultaten op relevantie
Synapse gebruikt FTS5 om alle memory-inhoud te indexeren, waardoor sub-milliseconde
zoekopdrachten mogelijk zijn over duizenden herinneringen.
Hoe Synapse FTS5 gebruikt
Wanneer u uitvoert:
1. Memory-inhoud wordt opgeslagen in de -tabel
2. Inhoud wordt ook ingevoegd in de FTS5 virtuele tabel
3. FTS5 tokenizeert en indexeert de inhoud automatisch
Wanneer u uitvoert:
1. Synapse parseert de query met FTS5-syntaxis
2. Voert een uit tegen de FTS5-index
3. Filtert op (tenant-isolatie)
4. Retourneert gerangschikte resultaten
Query-syntaxis
Eenvoudige trefwoordzoekopdracht
[CODE BLOCK]
Retourneert herinneringen die "docker" bevatten.
Meerdere trefwoorden (impliciete AND)
[CODE BLOCK]
Retourneert herinneringen die ZOWEL "docker" ALS "swarm" bevatten.
Zin-overeenkomst
[CODE BLOCK]
Retourneert herinneringen die de exacte zin "docker swarm" bevatten.
Prefix-overeenkomst
[CODE BLOCK]
Retourneert herinneringen die woorden bevatten die beginnen met "docker" (bijv. "dockers",
"dockerfile", "dockerize").
Booleaans OR
[CODE BLOCK]
Retourneert herinneringen die "docker" OF "kubernetes" bevatten.
Booleaans NOT
[CODE BLOCK]
Retourneert herinneringen die "docker" bevatten maar NIET "swarm".
Groepering
[CODE BLOCK]
Retourneert herinneringen die "docker" of "kubernetes" bevatten, maar niet "test".
Praktische voorbeelden
Vind herinneringen over een project
[CODE BLOCK]
Vind exacte zin
[CODE BLOCK]
Sluit test-herinneringen uit
[CODE BLOCK]
Vind op technologie
[CODE BLOCK]
Rangschikking
FTS5 rangschikt resultaten op relevantie met behulp van het BM25-algoritme. Factoren:
- Termfrequentie (hoe vaak de term voorkomt)
- Inverse documentfrequentie (zeldzame termen ranken hoger)
- Documentlengte (kortere docs met de term ranken hoger)
- Kolomgewicht (title > content)
Resultaten worden geretourneerd in rangschikkingsvolgorde (meest relevant eerst).
Prestaties
| Bewerking | Latentie |
|-----------|----------|
| 100 herinneringen doorzoeken | < 5ms |
| 1.000 herinneringen doorzoeken | < 10ms |
| 10.000 herinneringen doorzoeken | < 25ms |
| 100.000 herinneringen doorzoeken | < 100ms |
FTS5 is sterk geoptimaliseerd voor lees-intensieve workloads.
Beperkingen
Stamvorming
FTS5 doet standaard geen stamvorming. "running" en "run" zijn verschillende termen.
Tijdelijke oplossing: Gebruik prefix-overeenkomst:
Typefout-tolerantie
FTS5 ondersteunt geen fuzzy matching. Een typefout levert geen resultaten op.
Tijdelijke oplossing: Gebruik semantisch zoeken () voor
conceptuele overeenkomsten.
Stopwoorden
Veelvoorkomende woorden (the, a, an, is) worden geïndexeerd maar zijn mogelijk niet
nuttig voor zoekopdrachten. FTS5 handelt dit automatisch af.
FTS5 versus semantisch zoeken
| Aspect | FTS5 | Semantisch zoeken |
|--------|------|-------------------|
| Snelheid | Sub-milliseconde | 50-100ms |
| Matching | Exacte trefwoorden | Conceptueel |
| Typefout-tolerantie | Geen | Enigszins |
| Stamvorming | Geen | Impliciet |
| Vereist embeddings | Nee | Ja |
| Geschikt voor | Specifieke termen | Concepten |
Gebruik FTS5 als u de trefwoorden kent. Gebruik semantisch zoeken als u
"herinneringen over X" wilt waarbij X anders wordt omschreven.
Best practices
> [!TIP]
> - Gebruik specifieke termen — "docker swarm" is beter dan "container orchestration"
> - Gebruik aanhalingstekens voor zinnen — garandeert zinsovereenkomst
> - Gebruik prefix voor variaties — vangt "deploy", "deployment", "deploying"
> - Sluit ruis uit — filtert test-herinneringen weg
> - Combineer met tags — verfijnt resultaten
Volgende stappen
- Semantisch zoeken
- Memory API
- Memory-best-practices
────────────────────────────────────────────────────────────
# Het Memory-model
SUMMARY: Hoe herinneringen zijn gestructureerd — categorieën, sleutels, tags, prioriteiten, bronnen, verificatie.
Het Memory-model
Het memory-model van Synapse is ontworpen voor LLM-agents — gestructureerd genoeg voor
betrouwbare recall, flexibel genoeg voor elk domein.
Anatomie van een herinnering
[CODE BLOCK]
Velden
| Veld | Type | Vereist | Beschrijving |
|------|------|---------|--------------|
| | string | auto | Unieke ID (memxxx) |
| | enum | ✅ | Een van 8 categorieën |
| | string | ✅ | Stabiele identificator (gebruikt voor updates) |
| | string | ✅ | De memory-inhoud (willekeurige tekst) |
| | string[] | – | Voor zoeken en filteren |
| | enum | – | low, normal, high, critical (standaard: normal) |
| | enum | auto | user, agent (wie heeft het opgeslagen) |
| | bool | auto | Heeft een mens dit geverifieerd? |
| | float | – | 0.0 tot 1.0 (standaard: 1.0 voor user, 0.7 voor agent) |
| | timestamp | – | Wanneer deze herinnering vergeten moet worden |
| | string | auto | Welke mind eigenaar is |
| | timestamp | auto | Eerst opgeslagen |
| | timestamp | auto | Laatst gewijzigd |
Categorieën
Acht categorieën dekken de veelvoorkomende LLM-agent-toepassingen:
| Categorie | Doel | Voorbeeldinhoud |
|-----------|------|-----------------|
| | Wie de gebruiker is | "Gebruiker is Michael Schäfer, software engineer in Berlin" |
| | Gebruikersvoorkeuren | "Geeft de voorkeur aan beknopte technische antwoorden" |
| | Verifieerbare feiten | "Kantoor is in Berlin, tijdzone Europe/Berlin" |
| | Projectstatus | "Synapse v1.5.0 uitgerold, bezig met v1.6.0 docs" |
| | Vaardigheden van de gebruiker | "Gevorderd Python, 10+ jaar" |
| | Eerdere fouten | "Vergeten npm-versie te verhogen — CI faalde" |
| | Sessie-context | "Momenteel PR #42 aan het beoordelen" |
| | Diverse notities | "Probeer Redis voor caching in volgende sprint" |
Sleutels: stabiele identificatoren
Het -veld is kritiek — het is hoe u herinneringen bijwerkt zonder duplicaten
te maken.
[CODE BLOCK]
Sleutelregels:
- Moet uniek zijn binnen (category, mind)
- Gebruik
- Voorvoeg met categorie voor duidelijkheid: ,
- Houd stabiel — wijzig sleutels niet na aanmaak
Tags: voor zoeken
Tags maken snelle filtering en zoekopdrachten mogelijk:
[CODE BLOCK]
Tag-best-practices:
- 2-5 tags per herinnering (over-tag niet)
- Kleine letters voor consistentie
- Gebruik projectnamen, onderwerpen, technologieën
- Tags zijn niet hoofdlettergevoelig
Prioriteitsniveaus
| Prioriteit | Wanneer te gebruiken | Recall-gedrag |
|------------|----------------------|---------------|
| | Identiteit, juridisch, onomkeerbaar | Altijd bovenaan recall |
| | Actieve projecten, kernvoorkeuren | Prominent in recall |
| | Meeste herinneringen (standaard) | Standaard recall-volgorde |
| | Efemeer, leuk-om-te-weten | Kan worden samengevat |
sorteert op prioriteit (critical eerst), dan op recentheid.
Bron: User versus Agent
Herinneringen worden getagd met :
- — opgeslagen door een mens (via JWT of human-UI)
- — opgeslagen door een LLM-agent (via Mind Key)
Dit beïnvloedt:
- Verificatie: -herinneringen worden automatisch geverifieerd, -herinneringen niet
- Betrouwbaarheid: standaard 1.0, 0.7
- Recall: markeert niet-geverifieerde herinneringen met "(unverified)"
> [!NOTE]
> Behandel -bron-herinneringen met gepast skepticisme. Ze kunnen zijn
> afgeleid of aangenomen in plaats van direct door de gebruiker gesteld.
Verificatie
De -vlag geeft aan dat een mens de herinnering heeft bevestigd:
- -herinneringen: automatisch geverifieerd ()
- -herinneringen: standaard niet-geverifieerd ()
Verifieer herinneringen via:
[CODE BLOCK]
> [!NOTE]
> Verificatie vereist JWT (mens-auth), niet Mind Key (agent-auth). Dit
> zorgt ervoor dat alleen mensen herinneringen als geverifieerd kunnen markeren.
Betrouwbaarheid
Het -veld (0.0 tot 1.0) geeft aan hoe betrouwbaar de herinnering is:
- 1.0 — direct door gebruiker gesteld
- 0.7 — door agent afgeleid
- 0.5 — onzeker, vereist verificatie
- 0.0 — expliciet betwijfeld
Stel betrouwbaarheid in bij opslaan:
[CODE BLOCK]
Verval
Stel in voor tijdgevoelige herinneringen:
[CODE BLOCK]
Verlopen herinneringen worden niet geretourneerd door (maar bestaan nog wel in DB).
Gebruik om herinneringen te zien die binnenkort verlopen.
Memory-levenscyclus
[CODE BLOCK]
Recall-gedrag
retourneert een platte-tekst samenvatting geoptimaliseerd voor LLM-context:
[CODE BLOCK]
- Gesorteerd op prioriteit (critical → low), dan op recentheid
- Niet-geverifieerde herinneringen gemarkeerd met
- Tags inbegrepen voor context
- Platte tekst (geen JSON-parsing nodig)
Volgende stappen
- Memory API
- Memory-best-practices
- FTS5-zoekopdracht
────────────────────────────────────────────────────────────
# Multi-tenancy & isolatie
SUMMARY: Hoe Synapse data isoleert tussen gebruikers en minds — uitleg van beveiligingsgrenzen.
Multi-tenancy & isolatie
Synapse is multi-tenant: meerdere gebruikers, elk met meerdere minds, volledig
geïsoleerd van elkaar. Deze pagina legt het isolatiemodel uit.
Tenant-hiërarchie
[CODE BLOCK]
Isolatieniveaus
Niveau 1: Gebruikersisolatie
Elk gebruikersaccount is geïsoleerd. Alice kan niet:
- Bobs minds zien
- Bobs herinneringen benaderen (zelfs met haar JWT)
- Bobs accountinformatie tonen
Afgedwongen door: -kolom op alle tabellen, JWT bevat , alle
query's filteren op .
Niveau 2: Mind-isolatie
Binnen een gebruiker is elke mind geïsoleerd. Mind A kan niet:
- Mind B's herinneringen zien
- Mind B's taken, chat of scripts benaderen
Afgedwongen door: -kolom op alle datatabellen, Mind Key bevat ,
alle query's filteren op .
> [!CRITICAL]
> Mind Key-isolatie is de primaire beveiligingsgrens. Een gelekte Mind Key
> verleent volledige toegang tot die mind's data — maar ALLÉÉN die mind.
Authenticatie-tokens
| Token | Bereik | Wat het kan benaderen |
|-------|--------|-----------------------|
| Mind Key | Eén mind | Alleen die mind's data |
| JWT | Gebruikersaccount | Accountbeheer (minds aanmaken/tonen/verwijderen) |
| Computer Token | Eén computer | Die computer's commando's |
Cross-mind-toegang
Binnen dezelfde gebruiker
Gebruikers kunnen al hun minds benaderen via JWT (bijv. toont allemaal).
Maar om memory-data te lezen/schrijven, hebben ze de specifieke Mind Key nodig.
Tussen gebruikers
Gebruikers kunnen elkaars data niet benaderen — TENZIJ ze expliciet een mind delen
via de Sharing-API:
[CODE BLOCK]
Na het delen kan Bob Mind A benaderen via zijn JWT (alleen-lezen als ).
Beveiligingsgrenzen
[CODE BLOCK]
Veelvoorkomende multi-tenant-patronen
Patroon 1: Eén gebruiker, één mind
Meest voorkomend voor individuele LLM-agent-gebruikers.
- 1 gebruikersaccount
- 1 mind
- 1 Mind Key
- Alle herinneringen in één scope
Patroon 2: Eén gebruiker, meerdere minds
Voor gebruikers met meerdere contexten (werk, persoonlijk, projecten).
- 1 gebruikersaccount
- N minds (bijv. "work", "personal", "project-x")
- N Mind Keys
- Elke LLM-sessie gebruikt één Mind Key
Patroon 3: Team-gedeelde mind
Voor teams die samenwerken aan een project.
- 1 gebruiker maakt de mind aan (krijgt Mind Key)
- Maker deelt met teamleden via JWT
- Alle teamleden benaderen via JWT (of gedeelde Mind Key)
> [!WARNING]
> Het delen van een Mind Key geeft volledige lees/schrijftoegang. Voor teamsamenwerking
> geeft u de voorkeur aan de Sharing-API (JWT-gebaseerd) boven het direct delen van Mind Keys.
Patroon 4: SaaS-provider
Voor apps die Synapse insluiten als hun memory-laag.
- Elke klant = 1 gebruikersaccount
- Elk klantenproject = 1 mind
- App slaat Mind Keys op per klant/project
- Volledige isolatie tussen klanten
Isolatieverificatie
Test: Mind Key kan andere minds niet benaderen
[CODE BLOCK]
Test: JWT kan geen memory-data direct lezen
[CODE BLOCK]
Best practices
> [!TIP]
> - Gebruik één mind per project/context — isolatie is uw vriend
> - Deel nooit Mind Keys — gebruik de Sharing-API in plaats daarvan
> - Roteer Mind Keys indien gecompromitteerd (verwijder mind, maak nieuwe aan)
> - Controleer gedeelde minds — bekijk periodiek
> - Gebruik JWT voor human-UI — stel Mind Keys nooit bloot aan eindgebruikers
Volgende stappen
- Authenticatie
- Mind Key vs JWT
- Architectuur
────────────────────────────────────────────────────────────
# Semantisch zoeken (Embeddings)
SUMMARY: Conceptueel zoeken in herinneringen met vector-embeddings — vind op betekenis, niet alleen op trefwoorden.
Semantisch zoeken (Embeddings)
Synapse ondersteunt semantisch zoeken met behulp van vector-embeddings. In tegenstelling
tot FTS5 (trefwoordovereenkomst) vindt semantisch zoeken herinneringen op betekenis —
zelfs als er geen trefwoorden overeenkomen.
Hoe het werkt
[CODE BLOCK]
Wat zijn embeddings?
Embeddings zijn numerieke vectorrepresentaties van tekst. Tekst met vergelijkbare
betekenis heeft vergelijkbare vectoren. Synapse genereert een vector (bijv. 1536 dimensies)
voor de inhoud van elke herinnering.
Cosinus-similariteit
Om semantisch vergelijkbare herinneringen te vinden, berekent Synapse de cosinus-similariteit
tussen de query-vector en elke memory-vector. Hogere similariteit = meer
relevant.
Wanneer semantisch zoeken gebruiken
Gebruik semantisch zoeken wanneer:
- U "herinneringen over X" wilt waarbij X anders wordt omschreven dan opgeslagen
- FTS5 geen resultaten retourneert (geen trefwoordovereenkomst)
- U conceptuele groepering wilt (bijv. alle "deployment"-herinneringen, zelfs als sommige "release" zeggen)
- De query een vraag is: "hoe handelen we authenticatie?"
Gebruik FTS5 wanneer:
- U exacte trefwoorden kent
- U booleaanse logica nodig heeft (AND, OR, NOT)
- U sub-milliseconde respons nodig hebt
- U zinsovereenkomst wilt
Eindpunt
GET /memory/semantic-search
[CODE BLOCK]
Respons:
[CODE BLOCK]
Voorbeelden
Vind deployment-herinneringen
[CODE BLOCK]
Retourneert herinneringen over "deployment", "release", "publishing", "rolling out",
enz.
Vind authenticatie-patronen
[CODE BLOCK]
Retourneert herinneringen over login, auth, JWT, sessiebeheer, OAuth, enz.
Vind vergelijkbare herinneringen
[CODE BLOCK]
Gebruikt semantische similariteit (via gedeelde tags EN embedding-vectoren).
Embedding-generatie
Wanneer worden embeddings gegenereerd?
- Bij memory-opslag — als embeddings-service is geconfigureerd, wordt embedding synchroon gegenereerd
- Batch-generatie — genereert embeddings voor herinneringen die deze missen
- Asynchrone updates — wanneer inhoud wordt bijgewerkt, wordt embedding opnieuw gegenereerd
Embedding-providers
Synapse ondersteunt configureerbare embedding-providers:
- OpenAI (, )
- Lokale modellen (via Ollama of vergelijkbaar)
- Aangepast (implementeer de embeddings-interface)
Configureer via omgevingsvariabelen:
[CODE BLOCK]
Batch-generatie
Voor minds met veel herinneringen die embeddings missen:
[CODE BLOCK]
Prestaties
| Bewerking | Latentie |
|-----------|----------|
| Embedding genereren (OpenAI) | 100-200ms |
| Semantisch zoeken (1k herinneringen) | 50-100ms |
| Semantisch zoeken (10k herinneringen) | 200-500ms |
| Batch-generatie (100 herinneringen) | 10-20s |
> [!NOTE]
> Semantisch zoeken is langzamer dan FTS5 vanwege vectorberekening. Gebruik FTS5
> voor bekende trefwoorden, semantisch voor conceptuele query's.
Beperkingen
Kosten van embeddings
Bij gebruik van OpenAI kost het genereren van embeddings geld ($0,02 per 1M tokens
voor text-embedding-3-small). Voor 10.000 herinneringen met gemiddeld 100 tokens elk,
is dat $0,02 — verwaarloosbaar.
Cold start
Herinneringen die zijn opgeslagen voordat embeddings waren geconfigureerd, hebben geen
embeddings. Voer uit om bij te vullen.
Provider-afhankelijkheid
Als de embeddings-provider niet beschikbaar is, faalt semantisch zoeken graceful
(retourneert lege resultaten of een fout). FTS5 blijft werken.
Wanneer embeddings niet beschikbaar zijn
Als embeddings-service niet is geconfigureerd:
- retourneert 503 Service Unavailable
- blijft werken (alleen geen embedding gegenereerd)
- FTS5-zoekopdracht blijft werken
Best practices
> [!TIP]
> - Gebruik semantisch voor conceptuele query's — "hoe handelen we X?"
> - Gebruik FTS5 voor specifieke termen — "docker swarm"
> - Vul embeddings regelmatig bij —
> - Monitor provider-gezondheid — semantisch zoeken is ervan afhankelijk
> - Combineer met tags — semantisch + tag-filter verfijnt resultaten
Volgende stappen
- FTS5-zoekopdracht
- Memory API
- Architectuur
## CATEGORIE: LLM-KOOKBOEK
Recepten en patronen voor LLM-agents.
────────────────────────────────────────────────────────────
# Chat-polling-patroon
SUMMARY: Hoe u pollt voor menselijke berichten tussen tool-aanroepen zonder uw workflow te blokkeren.
Chat-polling-patroon
Het chat-systeem is asynchroon — mensen kunnen berichten achterlaten terwijl u werkt.
Dit patroon laat zien hoe u pollt voor berichten zonder uw workflow te blokkeren.
Het patroon
[CODE BLOCK]
Poll tussen tool-aanroepen, niet in een strakke lus.
Waarom pollen tussen tool-aanroepen?
- Niet blokkeren — polling in een strakke lus verspilt API-aanroepen
- Geen berichten missen — te infrequent pollen betekent trage reacties
- Sweet spot — poll elke 30-60 seconden, of na elke tool-aanroep
Implementatie
Basis polling
[CODE BLOCK]
Patroon 1: Poll na elke tool-aanroep
[CODE BLOCK]
Patroon 2: Tijdgebaseerde polling
[CODE BLOCK]
Patroon 3: Event-gedreven (met webhooks)
Voor realtime melding, registreer een webhook:
[CODE BLOCK]
Dan kan uw webhook-handler de agent wakker maken:
[CODE BLOCK]
Berichtafhandelingspatronen
Patroon: Bevestig dan verwerk
[CODE BLOCK]
Patroon: Wachtrij voor batch-verwerking
[CODE BLOCK]
Patroon: Prioriteitsroutering
[CODE BLOCK]
Polling-frequentie
| Toepassing | Frequentie |
|------------|------------|
| Interactieve agent (mens wacht) | Elke 5-10 seconden |
| Achtergrond-agent | Elke 30-60 seconden |
| Batch-verwerking | Elke 5 minuten |
| Webhook-getriggerd | Niet pollen — gebruik webhooks |
> [!WARNING]
> Vaker dan eens per 5 seconden pollen verspilt API-aanroepen. Het -
> eindpunt retourneert onmiddellijk als er berichten klaarstaan, dus sneller pollen
> levert geen voordeel op.
Multi-agent-chat
Voor agent-naar-agent-communicatie:
[CODE BLOCK]
Best practices
> [!TIP]
> - Poll tussen tool-aanroepen — niet in een strakke lus
> - Bevestig onmiddellijk — mens weet dat u het bericht heeft ontvangen
> - Verwerk asynchroon — blokkeer niet op lang werk
> - Gebruik webhooks voor realtime — polling heeft latentie
> - Poll niet vaker dan eens per 5 seconden — verspilt API-aanroepen
Veelvoorkomende problemen
Berichten verdwijnen
- markeert berichten automatisch als gelezen
- Als u ze niet verwerkt, zijn ze weg
- Oplossing: Verwerk berichten altijd vóór return
Dubbele antwoorden
- Als uw handler crasht, kunt u twee keer antwoorden
- Oplossing: Maak handler idempotent (controleer of al geantwoord)
Trage reacties
- Elke 60s pollen betekent tot 60s latentie
- Oplossing: Poll elke 10-30s, of gebruik webhooks
Volgende stappen
- Chat API
- Sessiestart-patroon
- Error-recovery
────────────────────────────────────────────────────────────
# Error-recovery voor agents
SUMMARY: Hoe LLM-agents fouten moeten afhandelen en ervan herstellen — retry, opslaan, leren.
Error-recovery voor agents
Fouten gebeuren. Netwerken falen, API's retourneren 500's, Mind Keys vervallen. Deze handleiding
laat zien hoe LLM-agents fouten elegant moeten afhandelen en ervan moeten leren.
Foutafhandelingsprincipes
1. Probeer opnieuw met backoff — tijdelijke fouten herstellen vaak
2. Sla de fout op — leer van patronen
3. Degradeer elegant — laat de hele sessie niet crashen
4. Meld de mens — voor fouten die u niet kunt oplossen
HTTP-foutafhandeling
Opnieuw proberen met exponentiële backoff
[CODE BLOCK]
Auth-foutafhandeling
[CODE BLOCK]
Fouten opslaan als herinneringen
Wanneer fouten optreden, sla ze op zodat toekomstige sessies kunnen leren:
[CODE BLOCK]
Veelvoorkomende foutscenario's
Scenario 1: Mind Key ongeldig
[CODE BLOCK]
Scenario 2: Netwerkfout
[CODE BLOCK]
Scenario 3: Ratelimited
[CODE BLOCK]
Scenario 4: Serverfout (5xx)
[CODE BLOCK]
Scenario 5: Tool-aanroep faalt
[CODE BLOCK]
Patroon: Circuit breaker
Voor herhaalde fouten, stop tijdelijk met proberen:
[CODE BLOCK]
Best practices
> [!TIP]
> - Probeer tijdelijke fouten altijd opnieuw — netwerken falen, servers hikken
> - Probeer client-fouten (4xx) niet opnieuw — ze lossen zichzelf niet op
> - Sla fouten op als herinneringen — leer van patronen
> - Meld mensen bij kritieke fouten — ze moeten het weten
> - Degradeer elegant — gedeeltelijk werk is beter dan crash
> - Gebruik circuit breakers — hamer niet op een falende service
Volgende stappen
- Fouten API-referentie
- Sessiestart-patroon
- Zelfherstellende tests
────────────────────────────────────────────────────────────
# Memory-tagging-strategie
SUMMARY: Hoe u herinneringen tagt voor effectief zoeken en filteren — het tagging-systeem dat schaalt.
Memory-tagging-strategie
Tags zijn het geheim van schaalbare memory-retrieval. Deze handleiding laat zien hoe u herinneringen
tagt zodat de juiste op het juiste moment terugkomen.
Waarom tags belangrijk zijn
Zonder tags heeft u platte volledige-tekst zoekopdracht. Met tags heeft u gestructureerde
navigatie:
[CODE BLOCK]
Tags maken mogelijk:
- Snelle filtering —
- Gescoped zoeken —
- Groepering — vind alle "mistake"-herinneringen voor een project
- Kruisverwijzingen — herinneringen die tags delen zijn gerelateerd
Tagging-schema
Project-tags
Gebruik projectnamen als tags:
[CODE BLOCK]
Technologie-tags
Gebruik technologienamen:
[CODE BLOCK]
Onderwerp-tags
Gebruik onderwerpcategorieën:
[CODE BLOCK]
Status-tags
Gebruik statusindicatoren:
[CODE BLOCK]
Type-tags
Gebruik type-indicatoren:
[CODE BLOCK]
Tagging-regels
Regel 1: 2-5 tags per herinnering
Te weinig tags = slechte vindbaarheid. Te veel = ruis.
[CODE BLOCK]
Regel 2: Kleine letters, met koppeltekens
[CODE BLOCK]
Regel 3: Gebruik consistente woordenschat
Stel een tagging-woordenschat op en houd u eraan:
[CODE BLOCK]
Regel 4: Tag met zoek-intentie
Vraag: "Hoe zal ik naar deze herinnering zoeken?"
[CODE BLOCK]
Patronen
Patroon 1: Project + onderwerp
[CODE BLOCK]
Zoek: (alle Synapse-project-herinneringen)
Zoek: (deployment-herinneringen in Synapse)
Patroon 2: Type + domein
[CODE BLOCK]
Zoek: (alle fouten)
Zoek: (deployment-fouten)
Patroon 3: Hiërarchisch
Voor sub-projecten binnen een project:
[CODE BLOCK]
Zoek: (alle Synapse)
Zoek: (alleen docs-sub-project)
Patroon 4: Status-tracking
[CODE BLOCK]
Veelvoorkomende toepassingen
Vind alle beslissingen over een project
[CODE BLOCK]
Vind alle fouten in een domein
[CODE BLOCK]
Vind actief werk
[CODE BLOCK]
Vind herinneringen over een technologie
[CODE BLOCK]
Tag-onderhoud
Periodieke review
[CODE BLOCK]
Tags samenvoegen
Als u inconsistente tags heeft ( en ), voeg ze samen:
[CODE BLOCK]
Best practices
> [!TIP]
> - Stel woordenschat vroeg in — consistente tags vanaf dag 1
> - Tag voor zoek-intentie — hoe zult u dit later vinden?
> - 2-5 tags is de sweet spot — te weinig of te veel is slecht
> - Kleine letters + koppeltekens — niet
> - Review periodiek — voeg duplicaten samen, verwijder ongebruikte
Volgende stappen
- Memory-best-practices
- FTS5-zoekopdracht
- Taakgedreven workflow
────────────────────────────────────────────────────────────
# Sessiestart-patroon
SUMMARY: De canonieke sessiestart-sequentie die elke LLM-agent moet volgen.
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.
Sessiestart-patroon
Elke LLM-agent-sessie moet deze canonieke opstartsequentie volgen. Stappen overslaan
leidt tot verloren context, gemiste berichten en vergeten taken.
Het patroon
[CODE BLOCK]
Implementatie
Stap 1: Alle herinneringen ophalen
> [!CRITICAL]
> Dit is de belangrijkste aanroep. Zonder deze heeft u geen geheugen van eerdere
> sessies.
[CODE BLOCK]
Retourneert platte-tekst samenvatting van alle herinneringen, gesorteerd op prioriteit.
Stap 2: Poll voor ongelezen chatberichten
[CODE BLOCK]
Retourneert ongelezen berichten van de mens. Markeert ze automatisch als gelezen.
Stap 3: Controleer lopende taken
[CODE BLOCK]
Retourneert taken waaraan u in de laatste sessie werkte.
Stap 4: Bouw context
Combineer de drie responsen in uw system prompt:
[CODE BLOCK]
Stap 5: Verwerk in behandeling zijnde items
[CODE BLOCK]
Volledig voorbeeld
[CODE BLOCK]
Veelvoorkomende fouten
> [!WARNING]
> - Recall overslaan — u start zonder context, herhaalt eerdere fouten
> - Chat-pollen vergeten — berichten van de mens blijven onbeantwoord
> - Actieve taken negeren — werk wordt halverwege vergeten
> - Niets opslaan — sessie produceert geen permanente waarde
Variaties
Minimaal patroon (low-context LLM's)
Voor LLM's met kleine contextvensters, sla de volledige recall over:
[CODE BLOCK]
Zoek dan naar specifieke onderwerpen indien nodig:
[CODE BLOCK]
Agressief patroon (langlopende agents)
Voor agents die uren draaien, voeg periodieke re-recall toe:
[CODE BLOCK]
Volgende stappen
- Memory-tagging-strategie
- Taakgedreven workflow
- Chat-polling-patroon
────────────────────────────────────────────────────────────
# Taakgedreven workflow
SUMMARY: Gebruik Synapse-taken om LLM-workflows met meerdere stappen te drijven die overleven tussen sessies.
Taakgedreven workflow
Taken zijn niet alleen todo's — ze zijn de ruggengraat van permanente LLM-workflows.
Door taken aan te maken voor werk met meerdere stappen, verzekert u continuïteit tussen sessies
en biedt u audittrails voor wat is gedaan.
Waarom taakgedreven?
Zonder taken:
- LLM start elke sessie onzeker over wat te doen
- Werk met meerdere stappen wordt halverwege vergeten
- Geen record van wat is gedaan
Met taken:
- LLM hervat lopende taken onmiddellijk
- Werk met meerdere stappen overleeft tussen sessies
- Ingebouwde audittrail van al het werk
Het patroon
[CODE BLOCK]
Implementatie
Stap 1: Maak een taak voor werk met meerdere stappen
[CODE BLOCK]
Stap 2: Volg voortgang in taakbeschrijving
[CODE BLOCK]
Stap 3: Hervat tussen sessies
[CODE BLOCK]
Stap 4: Voltooi en archiveer
[CODE BLOCK]
Volledig voorbeeld: Deploy-workflow
[CODE BLOCK]
Taakhiërarchie
Voor complex werk, gebruik ouder-kind-taakrelaties:
[CODE BLOCK]
Zoek naar sub-taken:
[CODE BLOCK]
Status-workflow
[CODE BLOCK]
Pending
Taak aangemaakt maar niet gestart. Gebruik voor gepland werk.
In progress
Wordt momenteel aan gewerkt. Update beschrijving met voortgang.
Done
Succesvol voltooid. Beschrijving moet samenvatting bevatten.
Cancelled
Afgebroken. Beschrijving moet reden bevatten.
Best practices
> [!TIP]
> - Maak taken voor werk met meerdere stappen — werk met één stap heeft geen taak nodig
> - Update beschrijving met voortgang — maakt hervatting mogelijk
> - Gebruik hoge prioriteit voor actief werk — komt naar boven in recall
> - Voltooi taken wanneer klaar — laat ze niet inprogress staan
> - Sla voltooiingssamenvattingen op als herinneringen — langetermijnreferentie
Veelvoorkomende patronen
Patroon: Bug-fix-workflow
[CODE BLOCK]
Patroon: Onderzoeksworkflow
[CODE BLOCK]
Volgende stappen
- Sessiestart-patroon
- Chat-polling-patroon
- Error-recovery
## CATEGORIE: VEELGESTELDE VRAGEN
Veelgestelde vragen en veelvoorkomende problemen.
────────────────────────────────────────────────────────────
# API-FAQ
SUMMARY: Veelgestelde API-vragen — auth, ratelimits, foutafhandeling, eindpunt-ontdekking.
API-FAQ
Veelgestelde vragen over de Synapse API.
Hoe authenticeer ik?
Twee methoden:
1. Mind Key (voor data-eindpunten):
2. JWT (voor account-eindpunten):
Of via queryparameter (limiet van 60 aanvragen/min):
Zie Authenticatie.
Wat is het verschil tussen Mind Key en JWT?
- Mind Key: tenant-scoped, vervalt nooit, voor memory/chat/tasks-data
- JWT: gebruiker-scoped, vervalt na 7 dagen, voor account/mind-beheer
Zie Mind Key vs JWT.
Waarom krijg ik 401 Unauthorized?
Veelvoorkomende oorzaken:
1. Ontbrekende -header
2. Ongeldige Mind Key (verifieer dat deze begint met )
3. Een JWT gebruiken waar een Mind Key vereist is (of omgekeerd)
4. Mind Key is ingetrokken
Oplossing: Verifieer uw token. Zie Authenticatie.
Waarom krijg ik 404 Not Found?
U heeft een verkeerd eindpuntpad gebruikt. Synapse heeft alleen de paden die in
staan.
Oplossing: Roep aan om alle geldige paden te zien. Raad niet.
Waarom krijg ik 429 Too Many Requests?
U gebruikt -queryparameter-auth, die is gelimiteerd tot 60/min.
Oplossing: Schakel over naar -header (geen ratelimit).
Zie Ratelimits.
Hoe toon ik alle eindpunten?
[CODE BLOCK]
Hoe vind ik het juiste eindpunt?
1. Controleer voor de machineleesbare lijst
2. Controleer voor volledige API-documentatie
3. Blader door voor het documentatiesysteem
4. Gebruik voor de OpenAPI 3.0-specificatie
Kan ik GET gebruiken in plaats van POST?
Sommige POST-eindpunten hebben GET-equivalenten voor URL-only tools:
- ↔
- ↔
- ↔
Controleer voor beschikbare GET-varianten.
Hoe handel ik fouten af?
Alle fouten retourneren JSON:
[CODE BLOCK]
Zie Fouten & Foutafhandeling.
Wat is de limiet voor requestbody's?
10 MB. Voor grotere payloads (bijv. bestandsuploads), gebruik de multipart-eindpunten.
Ondersteunt de API CORS?
Ja. Alle eindpunten retourneren:
[CODE BLOCK]
Is er een SDK?
Ja:
- Node.js:
- MCP:
Zie API-overzicht voor details.
Hoe pagineer ik?
Gebruik en :
[CODE BLOCK]
Standaardlimiet: 100. Maximum: 500.
Kan ik herinneringen filteren op categorie of tag?
Ja:
[CODE BLOCK]
Hoe doorzoek ik herinneringen?
Twee manieren:
1. FTS5 trefwoordzoekopdracht:
2. Semantisch zoeken:
Zie FTS5-zoekopdracht en Semantisch zoeken.
Hoe werk ik een herinnering bij?
POST met dezelfde + — de bestaande herinnering wordt
bijgewerkt, niet gedupliceerd.
[CODE BLOCK]
Hoe verwijder ik een herinnering?
[CODE BLOCK]
Kan ik in bulk verwijderen?
Ja:
[CODE BLOCK]
Volgende stappen
- API-overzicht
- Fouten & Foutafhandeling
- Authenticatie
────────────────────────────────────────────────────────────
# Algemene FAQ
SUMMARY: Veelgestelde vragen over Synapse — wat het is, hoe het werkt, voor wie het is.
Algemene FAQ
Veelgestelde vragen over Synapse.
Wat is Synapse?
Synapse is een permanente memory-API voor LLM-agents. Het geeft uw AI-assistent
een permanente, doorzoekbare hersenen die overleeft tussen sessies. In plaats van
alles te vergeten wanneer de chat sluit, slaat de LLM herinneringen op en haalt ze op
via een eenvoudige HTTP-API.
Meer leren: Wat is Synapse?
Voor wie is Synapse?
- LLM-agent-ontwikkelaars die permanente staat nodig hebben
- Power users die lokale LLM's draaien met aangepaste agents
- Teams die AI-assistenten bouwen met gedeeld geheugen
- Automatiseringsengineers die LLM-aanroepen ketenen tussen sessies
Is Synapse gratis?
Synapse wordt gehost op en is gratis voor persoonlijk gebruik.
Voor self-hosting, zie de repo.
Hoe verschilt Synapse van ChatGPT Memory?
| Functie | ChatGPT Memory | Synapse |
|---------|---------------|---------|
| Opslag | OpenAI-servers | Uw server |
| API-toegang | Nee | Ja (REST + MCP) |
| Multi-tenant | Nee | Ja (minds) |
| Aangepaste categorieën | Nee | Ja (8 categorieën) |
| Volledige-tekst zoekopdracht | Beperkt | FTS5 + semantisch |
| Self-hostable | Nee | Ja |
Welke LLM's werken met Synapse?
Elke LLM die HTTP-aanroepen kan doen of MCP kan gebruiken:
- Claude (Anthropic) — via MCP of directe API
- GPT-4 / GPT-3.5 (OpenAI) — via function calling + API
- Gemini (Google) — via function calling + API
- Llama / Mistral (lokaal) — via aangepaste integratie
- Elke LLM via de Synapse MCP-server
Moet ik Synapse zelf hosten?
Nee. De gehoste versie op is beschikbaar voor
publiek gebruik. Self-hosting is optioneel (voor privacy, maatwerk of
air-gapped omgevingen).
Hoeveel data kan ik opslaan?
Er zijn geen harde limieten op de gehoste versie. Typisch gebruik:
- 100-1000 herinneringen per mind
- 1-10 KB per herinnering (inhoudsveld)
- Totaal: 10 MB per mind
Voor grotere schaal, self-host.
Is mijn data privé?
Ja. Elke mind is geïsoleerd (zie Multi-tenancy).
Andere gebruikers kunnen uw data niet zien. De hostingprovider (Schäfer Services)
heeft toegang maar bekijkt geen gebruikersdata.
Voor maximale privacy, self-host.
Kan ik mijn data exporteren?
Ja. Gebruik om alle herinneringen als JSON te exporteren. Zie
Back-up & Restore.
Wat gebeurt er als ik mijn Mind Key verlies?
Mind Keys worden slechts één keer getoond bij aanmaak. Bij verlies:
1. Login met uw e-mail/wachtwoord om een JWT te krijgen
2. Maak een nieuwe mind via
3. Sla de nieuwe Mind Key op
4. (Optioneel) Verwijder de oude mind via
U kunt herinneringen van een mind waarvan de sleutel verloren is niet herstellen.
Kunnen meerdere LLM-agents een mind delen?
Ja. Alle agents die dezelfde Mind Key gebruiken delen de data van die mind. Voor
gecoördineerd multi-agent-werk, zie Multi-agent-coördinatie.
Werkt Synapse offline?
Nee, Synapse vereist een internetverbinding met de server (gehost of
self-hosted). Voor offline LLM's, draai Synapse lokaal.
Hoe snel is memory-zoekopdracht?
- FTS5 trefwoordzoekopdracht: < 10ms voor 1000 herinneringen
- Semantisch zoeken: 50-100ms voor 1000 herinneringen
- Volledige recall: < 50ms voor 1000 herinneringen
Zie FTS5-zoekopdracht voor details.
Kan ik Synapse zonder LLM gebruiken?
Ja. Synapse is een generieke memory-API. U kunt het gebruiken vanuit elke applicatie
die profiteert van permanente, doorzoekbare key-value-opslag met categorieën
en tags.
Volgende stappen
- Wat is Synapse?
- Quick Start
- API-FAQ
────────────────────────────────────────────────────────────
# MCP-FAQ
SUMMARY: Veelgestelde vragen over MCP-integratie — tools, transporten, troubleshooting.
MCP-FAQ
Veelgestelde vragen over de Synapse MCP-server.
Wat is MCP?
MCP (Model Context Protocol) is een open standaard van Anthropic voor LLM-tool-
integratie. In plaats van API-documentatie in prompts te plakken, registreert u tools
bij een MCP-server, en de LLM roept ze aan als native functies.
Zie Wat is MCP?.
Hoeveel tools stelt Synapse MCP beschikbaar?
79 tools in 12 categorieën: memory, chat, scheduler, tasks, scripts,
computers, push, user, utility, visualization, sharing, webhooks, browser.
Zie Wat is MCP? voor de volledige lijst.
Welke MCP-clients worden ondersteund?
- Claude Desktop (macOS, Windows)
- Claude Code (terminal)
- Cursor (IDE)
- Continue.dev (VS Code, JetBrains)
- Cline (VS Code)
- Elke MCP-compatibele client
Zie Claude Desktop Setup voor configuratievoorbeelden.
Welke transporten worden ondersteund?
1. stdio (lokaal, aanbevolen voor desktop)
2. HTTP/SSE (remote, multi-tenant)
3. WebSocket (mobiel, hoog volume)
Hoe configureer ik Claude Desktop?
Bewerk :
[CODE BLOCK]
Zie Claude Desktop Setup.
Waarom verschijnen tools niet in Claude Desktop?
1. Herstart Claude Desktop volledig (Cmd+Q op macOS)
2. Controleer of configuratiebestand geldige JSON is
3. Verifieer Node.js 18+ geïnstalleerd
4. Controleer MCP-logs:
Zie MCP Troubleshooting.
Hoe gebruik ik een andere mind?
Wijzig in uw MCP-configuratie en herstart de client.
Voor meerdere minds, draai meerdere MCP-server-instanties met verschillende
Mind Keys.
Kan ik beperken welke tools worden getoond?
Ja, gebruik Tool Profiles:
- : 8 samengestelde tools (500 tokens)
- : 25 tools (2,500 tokens)
- : 119 tools (8,250 tokens, standaard)
Stel in via -env-var of -header.
Hoe debug ik MCP-problemen?
1. Draai MCP-server handmatig:
2. Controleer client-logs (verschilt per client)
3. Verifieer dat Mind Key werkt:
4. Controleer Synapse-gezondheid:
Zie MCP Troubleshooting.
Is de MCP-server gratis?
Ja. Het npm-pakket is open source. De gehoste MCP-server
op is gratis voor publiek gebruik.
Kan ik de MCP-server zelf hosten?
Ja:
[CODE BLOCK]
Hoe verschilt MCP van directe API-aanroepen?
| Aspect | Directe API | MCP |
|--------|-------------|-----|
| LLM moet weten | URL's, headers, auth | Alleen tool-namen |
| Auth-handling | Handmatig | Automatisch (env-var) |
| Tool-ontdekking | Lees /endpoints | Automatisch via MCP-protocol |
| Foutafhandeling | Handmatig | Gestandaardiseerd |
| Geschikt voor | Aangepaste integraties | LLM-agents |
Kan ik mijn eigen MCP-client bouwen?
Ja. Gebruik de officiële MCP-SDK:
- TypeScript:
- Python:
Zie Aangepaste MCP-client.
Hoe meld ik MCP-bugs?
Open een issue:
Vermeld:
- MCP-server-versie
- Client-naam en versie
- Besturingssysteem
- Relevante logs
- Stappen om te reproduceren
Volgende stappen
- Wat is MCP?
- Claude Desktop Setup
- MCP Troubleshooting
────────────────────────────────────────────────────────────
# Troubleshooting-FAQ
SUMMARY: Oplossingen voor veelvoorkomende Synapse-problemen — auth, netwerk, data, deployment.
Troubleshooting-FAQ
Oplossingen voor veelvoorkomende Synapse-problemen.
Ik kan niet inloggen
Symptomen
- retourneert 401
- "Invalid email or password"
Oplossingen
1. Verifieer dat e-mail correct is — hoofdlettergevoelig
2. Controleer wachtwoord — minimaal 6 tekens
3. Registreer eerst als u geen account heeft:
4. Reset wachtwoord (indien SMTP geconfigureerd) via de web-UI
Ik ben mijn Mind Key kwijt
Symptomen
- Kan herinneringen niet benaderen
- Mind Key is verwijderd/verloren
Oplossingen
Mind Keys kunnen niet worden hersteld. U moet:
1. Inloggen om JWT te krijgen:
2. Minds tonen: (met JWT)
3. Nieuwe mind aanmaken:
4. Nieuwe Mind Key opslaan
5. (Optioneel) Oude mind verwijderen:
Data in de oude mind is verloren tenzij u de Mind Key kunt vinden.
API-aanroepen retourneren 401
Symptomen
- Alle API-aanroepen retourneren 401 Unauthorized
- "Mind Key fehlt oder ungültig"
Oplossingen
1. Verifieer header-formaat:
2. Controleer dat Mind Key begint met (niet wat JWT is)
3. Test direct:
[CODE BLOCK]
4. Mind Key kan zijn ingetrokken — maak een nieuwe mind aan
Zie Authenticatie.
API-aanroepen retourneren 404
Symptomen
- 404 Not Found
- "Route not found"
Oplossingen
> [!CRITICAL]
> Raad geen eindpuntpaden. Alleen paden in bestaan.
1. Controleer geldige eindpunten:
2. Vergelijk URL exact — hoofdlettergevoelig, geen afsluitende slashes
3. Controleer HTTP-methode — vs zijn verschillend
API-aanroepen retourneren 429
Symptomen
- 429 Too Many Requests
- "Rate limit exceeded"
Oplossingen
1. Schakel over naar header-auth (geen ratelimit):
[CODE BLOCK]
2. Wacht seconden als u moet gebruiken
Zie Ratelimits.
Memory-zoekopdracht retourneert geen resultaten
Symptomen
- retourneert leeg
- Weet dat herinneringen bestaan
Oplossingen
1. Verifieer dat herinneringen bestaan:
2. Controleer zoeksyntaxis — FTS5 heeft specifieke syntaxis
3. Probeer eenvoudigere query — in plaats van
4. Gebruik semantisch zoeken voor conceptuele query's:
Zie FTS5-zoekopdracht.
Herinneringen worden niet persistent gemaakt
Symptomen
- POST /memory retourneert succes
- GET /memory/recall toont ze niet
Oplossingen
1. Verifieer dezelfde Mind Key — verschillende sleutels = verschillende minds
2. Controleer respons — POST retourneert
3. Probeer GET /memory (JSON-lijst) in plaats van /memory/recall (tekst)
4. Controleer filter — of verbergen ze mogelijk
Tools verschijnen niet in Claude Desktop
Symptomen
- Claude Desktop toont 0 tools
- Geen 🔌-icoon
Oplossingen
1. Herstart Claude Desktop volledig (Cmd+Q)
2. Verifieer configuratiebestand is geldige JSON
3. Controleer Node.js 18+ geïnstalleerd
4. Draai MCP handmatig:
5. Controleer logs:
Zie MCP Troubleshooting.
Synapse is offline
Symptomen
- Kan synapse.schaefer.zone niet bereiken
- curl time-out
Oplossingen
1. Controleer uw internet — probeer een andere site
2. Controleer Synapse-gezondheid:
3. Wacht — kan tijdelijke storing of deployment zijn
4. Controleer statuspagina (indien beschikbaar)
Voor self-hosted: controleer Docker-containerstatus, databaseverbinding.
Database-fouten
Symptomen
- 500 Internal Server Error
- "Database connection failed"
Oplossingen
Voor self-hosted:
1. Controleer dat PostgreSQL draait:
2. Controleer DATABASEURL in env
3. Controleer migraties:
4. Controleer schijfruimte:
Voor gehost: meld bij support.
Webhook vuurt niet
Symptomen
- Geregistreerde webhook maar ontvangt geen callbacks
- Geen POST naar uw URL
Oplossingen
1. Verifieer dat URL bereikbaar is:
2. Controleer events-filter — komt overeen met alle memory-events
3. Test webhook:
4. Controleer dat webhook is ingeschakeld:
5. Verifieer SSL — Synapse vereist geldige HTTPS voor webhook-URL's
Zie Webhooks API.
Cron-job draait niet
Symptomen
- Cron-job aangemaakt maar vuurt niet
- wordt niet bijgewerkt
Oplossingen
1. Controleer schema-syntaxis — moet geldige 5-veld cron OF gehele seconden zijn
2. Verifieer dat eindpunt is toegestaan — moet http(s) zijn, geen privé-IP's
3. Controleer dat job is ingeschakeld:
4. Wacht op volgende geplande tijd — cron is niet onmiddellijk
Zie Cron & Scheduler.
Meer hulp nodig?
1. Controleer bestaande docs:
2. Doorzoek docs:
3. Open issue:
4. Contact: zie -pagina
Volgende stappen
- Fouten & Foutafhandeling
- API-FAQ
- MCP Troubleshooting