# DOCUMENTATION SYNAPSE — Référence complète
# Généré le : 2026-07-18T06:14:48.228Z
# Total des articles : 47
Ce document contient la documentation complète de l'API Synapse.
Base URL: https://synapse.schaefer.zone
Language: fr
========================================================================
## CATÉGORIE : DÉMARRAGE
Tout ce qu'il faut pour démarrer avec Synapse.
────────────────────────────────────────────────────────────
# Authentification & Mind Keys
SUMMARY: Comment fonctionne l'authentification Synapse : Mind Keys pour les agents, JWT pour les humains, ?key= pour les outils n'utilisant que des URLs.
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.
Authentification & Mind Keys
Synapse utilise deux méthodes d'authentification, chacune optimisée pour un cas
d'usage différent. Comprendre la différence est essentiel pour construire des
intégrations fiables.
Deux méthodes d'auth
| Méthode | Cas d'usage | Limite de débit | Expiration |
|--------|----------|------------|--------|
| Mind Key | Agents LLM, outils automatisés | Aucune (en-tête) / 60 min (requête) | Jamais |
| JWT | Interface humaine, opérations de compte | Aucune | 7 jours |
Mind Key (pour les agents)
Une Mind Key est un jeton d'API limité au tenant. Elle authentifie les données d'un
seul mind (mémoires, tâches, chat, scripts, etc.). Utilisez-la pour :
- Les agents LLM appelant l'API
- Les scripts d'automatisation en arrière-plan
- La configuration du serveur MCP
- Toute intégration longue durée
Authentification par en-tête (recommandée)
[CODE BLOCK]
Paramètre de requête (pour les outils n'utilisant que des URLs)
[CODE BLOCK]
> [!WARNING]
> Le paramètre de requête est limité à 60 requêtes par minute. L'en-tête
> Bearer n'a pas de limite de débit. Utilisez l'en-tête chaque fois que votre client
> prend en charge les en-têtes personnalisés.
Créer une Mind Key
[CODE BLOCK]
La réponse inclut — sauvegardez-la immédiatement, elle n'est affichée
qu'une seule fois.
Lister vos minds
[CODE BLOCK]
Supprimer un mind (irréversible !)
[CODE BLOCK]
JWT (pour les humains)
Les JWT authentifient le compte utilisateur, pas un mind spécifique. Utilisez-les
pour :
- L'inscription et la connexion au compte
- La création / liste / suppression de minds
- Le partage de minds avec d'autres utilisateurs
- La gestion des abonnements Web Push
Inscription
[CODE BLOCK]
Renvoie :
Connexion
[CODE BLOCK]
Renvoie :
Expiration du JWT
Les JWT expirent après 7 jours. Une fois expirés, appelez simplement à
nouveau pour en obtenir un nouveau. La Mind Key n'expire jamais, donc les intégrations
d'agents existantes continuent de fonctionner.
Bonnes pratiques de sécurité
> [!CRITICAL]
> - Ne commitez jamais de Mind Keys dans git. Utilisez des variables d'environnement.
> - Ne journalisez jamais de Mind Keys. Masquez-les dans les logs ().
> - Pivotez les clés si vous suspectez une fuite (supprimez le mind, créez-en un nouveau).
> - Utilisez un mind par projet pour limiter le rayon d'impact en cas de fuite de clé.
Schéma de variable d'environnement
[CODE BLOCK]
[CODE BLOCK]
Configuration du serveur MCP
[CODE BLOCK]
Schéma multi-mind
Chaque utilisateur peut avoir plusieurs minds. Schémas courants :
| Nom du mind | Rôle |
|-----------|---------|
| | Mémoires liées au travail |
| | Préférences personnelles, famille |
| | Contexte de projet spécifique |
| | Progression d'apprentissage |
| | Fallback à usage général |
Utilisez différentes Mind Keys pour différentes sessions LLM afin de garder les
contextes isolés.
Limites de débit
| Méthode d'auth | Limite | Portée |
|-------------|-------|-------|
| Mind Key (en-tête) | Aucune | Par mind |
| Mind Key (?key=) | 60/min | Par IP |
| JWT (en-tête) | Aucune | Par utilisateur |
| Endpoints publics | Aucune | Globale |
Les en-têtes de limite de débit (, ,
) sont inclus dans les réponses le cas échéant.
Prochaines étapes
- Mind Key vs JWT — quand utiliser laquelle
- API Memory — ce que vous pouvez faire avec une Mind Key
- API User — gestion de compte avec JWT
────────────────────────────────────────────────────────────
# Mind Key vs JWT — Quand utiliser laquelle ?
SUMMARY: Guide de décision : Mind Key pour l'accès aux données agent, JWT pour la gestion de compte.
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 — Quand utiliser laquelle ?
Synapse possède deux jetons d'authentification. Choisir le mauvais mène à des erreurs
401. Ce guide vous donne un cadre de décision clair.
Tableau de décision rapide
| Vous voulez... | Utiliser |
|----------------|-----|
| Stocker / rappeler des mémoires | Mind Key |
| Envoyer / poller des messages chat | Mind Key |
| Gérer des tâches | Mind Key |
| Stocker des scripts | Mind Key |
| Enregistrer des webhooks | Mind Key |
| Contrôler des ordinateurs | Mind Key (côté utilisateur) / Computer Token (côté agent) |
| Inscrire un compte utilisateur | Aucune (public) |
| Se connecter | Aucune (public) |
| Créer / lister / supprimer des minds | JWT |
| Partager un mind avec un autre utilisateur | JWT |
| S'abonner aux notifications web push | JWT |
| Consulter le journal d'audit | Mind Key |
La règle simple
> [!TIP]
> Si ça touche les données d'un seul mind → Mind Key.
> Si ça gère le compte ou les métadonnées de mind → JWT.
Mind Key — jeton d'accès aux données
Une Mind Key accorde l'accès aux données d'un seul mind. C'est un jeton longue
durée qui n'expire jamais (jusqu'à la suppression du mind). Parfait pour :
- Les agents LLM persistant des mémoires entre sessions
- Les tâches cron en arrière-plan
- La configuration du serveur MCP
- Les intégrations de webhooks
- Les applications mobiles lisant la mémoire
Ce que la Mind Key peut faire
- — lire toutes les mémoires de ce mind
- — stocker/mettre à jour des mémoires
- — lire les messages de chat
- — envoyer des messages de chat
- — lister les tâches
- — créer des tâches
- — stocker des scripts
- — enregistrer des webhooks
- — mettre en file des commandes
Ce que la Mind Key NE PEUT PAS faire
- Créer / lister / supprimer des minds (besoin d'un JWT)
- Partager un mind avec un autre utilisateur (besoin d'un JWT)
- Voir les infos du compte utilisateur (besoin d'un JWT)
- S'abonner au web push (besoin d'un JWT)
JWT — jeton de gestion de compte
Un JWT authentifie le compte utilisateur. Il expire après 7 jours et est utilisé
pour les opérations au niveau du compte qui couvrent plusieurs minds ou impliquent
d'autres utilisateurs.
Ce que le JWT peut faire
- — créer un nouveau mind (renvoie une nouvelle Mind Key)
- — lister tous les minds de cet utilisateur
- — supprimer un mind
- — partager un mind avec un autre utilisateur
- — s'abonner aux notifications web push
- — lister les partages de mind
Ce que le JWT NE PEUT PAS faire
- Lire / écrire des mémoires (besoin d'une Mind Key)
- Envoyer des messages de chat (besoin d'une Mind Key)
- Gérer des tâches (besoin d'une Mind Key)
- Enregistrer des webhooks (besoin d'une Mind Key)
Cas particulier : Computer Token
Les endpoints (côté agent, pour le screen-remote-agent) utilisent
un troisième type de jeton : le Computer Token. Ce jeton est renvoyé par
lors de l'échange d'un code d'installation, et est
spécifique à un ordinateur enregistré.
| Endpoint | Auth |
|----------|------|
| | Computer Token |
| | Computer Token |
| | Mind Key ou JWT |
| | Mind Key ou JWT |
Schémas courants
Schéma 1 : agent LLM unique
1. S'inscrire une fois → obtenir un JWT
2. Créer un mind → obtenir une Mind Key
3. Le LLM utilise la Mind Key pour tout
Schéma 2 : agent multi-projets
1. S'inscrire une fois → obtenir un JWT
2. Créer plusieurs minds (travail, personnel, projet-x) → obtenir plusieurs Mind Keys
3. Le LLM charge différentes Mind Keys selon le contexte
Schéma 3 : partage en équipe
1. L'utilisateur A crée un mind → obtient la Mind Key A
2. L'utilisateur A partage avec l'utilisateur B via JWT ()
3. L'utilisateur B peut maintenant y accéder via son propre JWT
4. Pour l'accès LLM, l'utilisateur B doit créer sa propre Mind Key (ou utiliser celle de A)
Schéma 4 : serveur MCP
Les serveurs MCP utilisent toujours la Mind Key (définie via la variable d'environnement
). Une instance de serveur MCP = un mind. Pour un accès multi-mind,
exécutez plusieurs instances MCP ou implémentez une commutation de mind côté client.
Aide-mémoire des formats de jeton
| Jeton | Format | Exemple |
|-------|--------|---------|
| Mind Key | + 36 caractères | |
| JWT | + base64 | |
| Computer Token | + 36 caractères | |
Prochaines étapes
- Authentification — guide complet d'auth
- API Utilisateur & Minds — endpoints protégés par JWT
- API Memory — endpoints protégés par Mind Key
────────────────────────────────────────────────────────────
# Démarrage rapide pour les agents LLM
SUMMARY: En 3 appels d'API : rappeler toutes les mémoires, en stocker une nouvelle, rechercher. Le workflow LLM essentiel.
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
Démarrage rapide pour les agents LLM
Vous perdez toute mémoire entre les sessions. Synapse est votre cerveau externe. Ce
guide présente les trois appels d'API essentiels que tout agent LLM doit connaître.
> [!CRITICAL]
> Appelez au DÉBUT de CHAQUE session.
> Sans cet appel, vous n'avez aucune mémoire de qui est l'utilisateur, de ce que vous
> avez promis, ou de ce sur quoi vous travailliez la dernière fois.
Étape 1 : rappeler toutes les mémoires (TOUJOURS EN PREMIER)
[CODE BLOCK]
Renvoie un résumé structuré en texte brut de toutes les mémoires stockées. Analysez-le
pour reconstruire votre modèle mental de l'utilisateur, ses projets et les
interactions passées.
Exemple de réponse :
[CODE BLOCK]
Étape 2 : stocker une nouvelle mémoire
Quand vous apprenez quelque chose qui mérite d'être retenu :
[CODE BLOCK]
Catégories : , , , , , , , ,
Priorités : , , ,
> [!TIP]
> Incluez toujours un champ — un identifiant court pour la mémoire. Cela vous
> permet de mettre à jour la même mémoire plus tard en re-POSTant avec la même clé.
Étape 3 : rechercher une mémoire spécifique
[CODE BLOCK]
> [!TIP]
> Syntaxe FTS5 : plusieurs mots = recherche AND. Phrases entre guillemets :
> . Recherche par préfixe : . Booléen : .
Outils ouverts (sans en-têtes d'auth)
Si votre outil ne peut qu'ouvrir des URLs (pas d'en-têtes personnalisés), utilisez le
paramètre :
[CODE BLOCK]
> [!WARNING]
> est limité à 60 requêtes/minute. L'en-tête Bearer n'a pas de limite de
> débit. Utilisez l'en-tête Bearer chaque fois que possible.
Workflow complet de session
1. Début de session : — charger toutes les mémoires
2. Pendant le travail : — trouver des faits spécifiques
3. Sur nouvelle info : — la stocker (avec catégorie, clé, tags, priorité)
4. Périodiquement : — vérifier les messages humains
5. Fin de session : Stocker tout apprentissage final via
Schémas courants
Mettre à jour une mémoire existante
POST avec la même et — la mémoire existante est mise à
jour, pas dupliquée.
Stocker un statut de projet
[CODE BLOCK]
Enregistrer une erreur (pour ne pas la répéter)
[CODE BLOCK]
Vérifier les messages humains
[CODE BLOCK]
Renvoie les messages non lus de l'humain. Répondez avec :
[CODE BLOCK]
Prochaines étapes
- Authentification — Mind Key vs JWT
- Référence API Memory — tous les 22 endpoints mémoire
- API Chat — communication asynchrone avec les humains
- Cookbook LLM — schémas pratiques
────────────────────────────────────────────────────────────
# Démarrage rapide (humain)
SUMMARY: Inscrivez un compte, créez votre premier mind, stockez une mémoire — en 5 minutes.
Démarrage rapide (humain)
Ce guide vous accompagne dans l'obtention d'un compte Synapse, votre première Mind Key
et le stockage de votre première mémoire. Durée totale : 5 minutes.
Étape 1 : inscrire un compte
Ouvrez l'API Synapse et créez un compte :
[CODE BLOCK]
Réponse :
[CODE BLOCK]
> [!TIP]
> Sauvegardez le JWT en lieu sûr — vous en aurez besoin pour créer des minds. Le JWT
> expire après 7 jours ; reconnectez-vous avec le même endpoint pour le rafraîchir.
Étape 2 : créez votre premier mind
Un « mind » est un scope de mémoire isolé. La plupart des utilisateurs commencent avec
un seul mind, mais vous pouvez en avoir plusieurs (ex. « work », « personal »,
« project-x »). Chaque mind a sa propre Mind Key unique.
[CODE BLOCK]
Réponse :
[CODE BLOCK]
> [!CRITICAL]
> Sauvegardez la immédiatement. Elle n'est affichée qu'une seule fois
> et ne peut pas être récupérée plus tard. Si vous la perdez, vous devrez créer un
> nouveau mind.
Étape 3 : stockez votre première mémoire
Utilisez maintenant la Mind Key pour stocker une mémoire :
[CODE BLOCK]
Réponse :
[CODE BLOCK]
Étape 4 : rappeler toutes les mémoires
Pour récupérer tout ce que vous avez stocké :
[CODE BLOCK]
Réponse (texte brut, optimisée pour la consommation LLM) :
[CODE BLOCK]
Étape 5 : rechercher des mémoires
Trouvez des mémoires spécifiques par mot-clé :
[CODE BLOCK]
Étape 6 : connectez votre LLM
Le moyen le plus simple de donner à votre LLM l'accès à Synapse est via MCP :
- Configuration Claude Desktop — config en 2 minutes
- Configuration Claude Code — intégration terminal
- Configuration Cursor — intégration IDE
Après configuration, votre LLM appellera automatiquement au début de
chaque session et persistera les nouveaux faits via .
Catégories de mémoire
Synapse prend en charge 8 catégories — choisissez la plus spécifique :
| Catégorie | Cas d'usage |
|----------|----------|
| | Nom d'utilisateur, rôle, infos de contact |
| | Goûts, aversions, style de travail |
| | Faits vérifiables (détails de projet, dates) |
| | Statut de projet, jalons, todos |
| | Choses dont l'utilisateur est bon |
| | Erreurs passées — à éviter de répéter |
| | Contexte pertinent à la session |
| | Notes diverses |
Niveaux de priorité
- — utile de savoir
- — par défaut
- — important
- — à ne jamais oublier (identité utilisateur, infos légales)
Prochaines étapes
- Approfondissement authentification
- Mind Key vs JWT
- Référence API Memory
- Intégration MCP
────────────────────────────────────────────────────────────
# Qu'est-ce que Synapse ?
SUMMARY: Synapse est une API de mémoire persistante pour les agents LLM — votre IA n'oublie jamais entre les sessions.
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.)
Qu'est-ce que Synapse ?
Synapse est une API de mémoire persistante pour les agents LLM. Elle résout le
problème fondamental de tout LLM basé sur le chat : entre les sessions, l'agent oublie
tout. Synapse donne à votre IA un cerveau permanent et interrogeable qui survit entre
les conversations, entre les jours et entre les différents fournisseurs LLM.
> [!CRITICAL]
> Si vous êtes un agent LLM qui lit ceci : appelez au début de
> chaque session. Sans cet appel, vous n'avez aucune mémoire des interactions
> passées, aucune connaissance de qui est l'utilisateur, et aucun contexte sur les
> projets en cours.
Le problème que Synapse résout
Chaque LLM moderne (Claude, GPT, Gemini, Llama) a la même limitation architecturale :
la fenêtre de contexte de conversation est finie, et une fois la session terminée,
tout l'état est perdu. Cela signifie que votre assistant IA :
- Oublie votre nom, vos préférences et vos projets en cours entre les chats
- Ne peut pas apprendre des erreurs passées entre les sessions
- N'a aucune continuité pour le travail de longue durée
- Repose les mêmes questions de clarification à chaque fois
Synapse corrige cela en fournissant une simple API HTTP où le LLM peut stocker et
récupérer des mémoires structurées. Les mémoires persistent sur le serveur, indexées
et recherchables, donc toute session future peut les rappeler.
Fonctionnalités clés
- Stockage de mémoire persistant — faits, préférences, projets, erreurs, compétences
- Recherche en texte intégral (FTS5) — trouvez n'importe quelle mémoire par mot-clé en millisecondes
- Recherche sémantique — recherche de similarité basée sur les embeddings pour les requêtes conceptuelles
- Multi-tenant — chaque utilisateur a des « minds » isolés (un utilisateur, plusieurs projets)
- Chat asynchrone — les humains peuvent laisser des messages à l'agent pendant qu'il travaille
- Tâches & planification — gestionnaire de tâches intégré et planificateur cron
- Intégration MCP — 79 outils exposés comme Model Context Protocol pour Claude, Cursor, Continue
- Contrôle de navigateur et d'ordinateur — outils d'automatisation à distance
- Webhooks — recevez des rappels HTTP sur les changements de mémoire/chat/tâches
Comment ça marche
[CODE BLOCK]
1. Le LLM appelle au début de la session
2. Synapse renvoie un résumé textuel structuré de toutes les mémoires stockées
3. Le LLM travaille, appelant périodiquement pour stocker de nouveaux faits
4. Quand l'utilisateur pose une question, le LLM peut appeler
5. À la fin de la session, le nouveau contexte important est persisté pour la prochaine session
Pour qui est-ce ?
- Développeurs d'agents LLM qui ont besoin d'état persistant
- Utilisateurs avancés exécutant des LLM locaux (Ollama, LM Studio) avec des agents personnalisés
- Équipes construisant des assistants IA qui ont besoin de mémoire partagée
- Ingénieurs d'automatisation enchaînant des appels LLM entre sessions
Comparaison rapide
| Fonctionnalité | Mémoire ChatGPT | Synapse |
|---------|---------------|---------|
| Emplacement de stockage | Serveurs OpenAI | Votre serveur |
| Accès API | Non (fermé) | Oui (REST + MCP) |
| Multi-tenant | Non | Oui (minds) |
| Catégories personnalisées | Non | Oui (8 catégories) |
| Recherche | Limitée | FTS5 + sémantique |
| Auto-hébergeable | Non | Oui (Docker) |
Prochaines étapes
- Démarrage rapide pour les humains — obtenez une Mind Key en 5 minutes
- Démarrage rapide pour les LLM — premiers appels d'API
- Authentification — Mind Keys vs JWTs
- Vue d'ensemble de l'architecture — comment Synapse est construit
## CATÉGORIE : RÉFÉRENCE DE L'API
Référence complète de tous les points de terminaison de l'API.
────────────────────────────────────────────────────────────
# Proxy navigateur
SUMMARY: Service d'automatisation de navigateur — conteneur Docker distinct sur le port 13000 pour le contrôle de navigateur headless.
KEY CONTEXT:
Browser Proxy is a SEPARATE Docker service (port 13000), NOT a Synapse endpoint.
Synapse endpoints do NOT include /browser/* paths.
For browser automation, use the MCP browser_new tool OR connect to the browser-proxy service directly.
Synapse MCP exposes browser tools (browser_new, browser_navigate, browser_click, etc.)
Proxy navigateur
Le Proxy navigateur est un service Docker distinct qui fournit de l'automatisation
de navigateur headless via Playwright. Il ne fait PAS partie intégrante de l'API Synapse —
les endpoints Synapse n'incluent pas les chemins .
Architecture
[CODE BLOCK]
Méthodes d'accès
Méthode 1 : via le serveur MCP Synapse (recommandé)
Le serveur MCP Synapse expose les outils navigateur en tant qu'outils MCP. Utilisez
cette méthode pour l'automatisation de navigateur pilotée par LLM :
[CODE BLOCK]
Outils MCP navigateur disponibles :
- — ouvrir un nouvel onglet de navigateur
- — naviguer vers une URL
- — cliquer sur un élément
- — saisir du texte dans un champ
- — capturer une capture d'écran
- — fermer l'onglet
- (et plus — voir Intégration MCP)
Méthode 2 : accès direct au Proxy navigateur
Pour les intégrations hors MCP, connectez-vous directement au service browser-proxy :
[CODE BLOCK]
Cas d'usage courants
Web scraping
[CODE BLOCK]
Automatisation de formulaires
[CODE BLOCK]
Capture d'écran
[CODE BLOCK]
Services associés
| Service | Port | Rôle |
|---------|------|---------|
| Synapse API | 12800 | Memory, chat, tasks |
| Synapse MCP | 13100 | Serveur MCP (79 outils) |
| Proxy navigateur | 13000 | Automatisation de navigateur headless |
| Proxy SSH | 12900 | Accès SSH aux machines distantes |
Prochaines étapes
- Intégration MCP — comment utiliser les outils navigateur via MCP
- API Computer Control — pour l'automatisation d'interface graphique sur machines enregistrées
────────────────────────────────────────────────────────────
# API Chat
SUMMARY: Chat asynchrone entre humains et agents LLM — polling, réponse, historique, compteur de messages non lus, envoi de fichiers.
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
API Chat
L'API Chat permet la messagerie asynchrone entre humains et agents LLM.
Contrairement au chat synchrone (type ChatGPT), l'humain peut laisser des messages
pendant que l'agent travaille — l'agent effectue un polling entre les appels d'outils.
Comment ça marche
[CODE BLOCK]
1. L'humain envoie un message via l'interface web (utilise le JWT)
2. Le message est stocké, marqué comme non lu
3. L'agent effectue un polling via entre les appels d'outils
4. Le polling renvoie tous les messages non lus et les marque comme lus
5. L'agent traite le message, répond éventuellement via
Endpoints
GET /chat/poll
Récupère les nouveaux messages de l'humain. Renvoie les messages non lus et les
marque comme lus. À utiliser entre les appels d'outils.
[CODE BLOCK]
Réponse :
[CODE BLOCK]
POST /chat/reply
Envoie un message en tant qu'agent.
[CODE BLOCK]
POST /chat/send
Envoie un message en tant qu'humain (nécessite un JWT, pas une Mind Key).
[CODE BLOCK]
GET /chat/history
Récupère l'historique récent du chat (les deux rôles).
[CODE BLOCK]
GET /chat/unread
Récupère le nombre de messages non lus.
[CODE BLOCK]
GET /chat/status
Récupère le statut de la session de chat (horodatages du dernier message, compteurs de non lus).
[CODE BLOCK]
POST /chat/upload
Téléverse une pièce jointe pour un message spécifique (formulaire multipart).
[CODE BLOCK]
GET /chat/files/:messageid
Liste les pièces jointes d'un message.
[CODE BLOCK]
GET /chat/file/:fileid
Télécharge une pièce jointe.
[CODE BLOCK]
Schéma de polling
> [!TIP]
> Effectuez un polling toutes les 30 à 60 secondes entre les appels d'outils. Ne
> pollinez pas plus fréquemment — cela gaspille votre quota d'API sans aucun
> bénéfice.
[CODE BLOCK]
Prochaines étapes
- API Tasks
- Schéma de polling de chat
────────────────────────────────────────────────────────────
# API Computer Control
SUMMARY: Contrôle à distance d'ordinateurs enregistrés — file d'attente de commandes, captures d'écran, exécution de scripts sur machines distantes.
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
API Computer Control
L'API Computer Control permet de télécommander des ordinateurs enregistrés. Un
petit agent () s'exécute sur la machine cible, effectue le
polling des commandes, les exécute et renvoie les résultats. Cela permet
l'automatisation d'interface graphique pilotée par LLM.
Architecture
[CODE BLOCK]
Endpoints côté utilisateur (Mind Key ou JWT)
GET /computers/list
Liste tous les ordinateurs enregistrés.
[CODE BLOCK]
GET /computers/:id
Récupère les détails d'un seul ordinateur.
[CODE BLOCK]
POST /computers/install-code
Génère un code d'installation pour enregistrer un nouvel ordinateur.
[CODE BLOCK]
Réponse :
POST /computers/:id/commands
Met en file d'attente une commande à exécuter par l'agent distant.
[CODE BLOCK]
Réponse :
GET /computers/:id/command (via requête)
Met en file d'attente une commande via GET (pour les cas simples).
[CODE BLOCK]
GET /computers/:id/commands
Liste les commandes récentes d'un ordinateur.
[CODE BLOCK]
GET /computers/:id/commands/:cid
Récupère le statut et le résultat d'une commande spécifique.
[CODE BLOCK]
GET /computers/:id/screenshot
Action unique : met en file d'attente une commande de capture d'écran et attend
jusqu'à 30 s le résultat.
[CODE BLOCK]
POST /computers/:id/disable
Désactive un ordinateur (révoque son jeton, conserve l'enregistrement pour audit).
[CODE BLOCK]
DELETE /computers/:id
Supprime définitivement un ordinateur.
[CODE BLOCK]
Endpoints côté agent (Computer Token)
Ces endpoints sont utilisés par le s'exécutant sur la machine
cible. Ils utilisent un Computer Token (renvoyé par ), pas une
Mind Key.
POST /computers/register
Échange un code d'installation contre un Computer Token.
[CODE BLOCK]
Réponse :
> [!CRITICAL]
> Sauvegardez le — il n'est affiché qu'une seule fois et est requis
> pour tous les endpoints côté agent.
GET /computers/me/poll
Long-polling de nouvelles commandes. L'agent l'appelle en boucle.
[CODE BLOCK]
Renvoie immédiatement si des commandes sont en attente, ou après secondes sinon.
POST /computers/me/commands/:cid/result
Publie le résultat de l'exécution d'une commande.
[CODE BLOCK]
Types de commandes
| Type | Payload | Description |
|------|---------|-------------|
| | | Capture l'écran en PNG (base64) |
| | | Clique aux coordonnées |
| | | Déplace la souris aux coordonnées |
| | | Saisit du texte au curseur |
| | | Appuie sur une combinaison de touches |
| | | Fait défiler à la molette |
| | | Glisser-déposer |
Schéma courant : automatisation d'interface graphique pilotée par LLM
[CODE BLOCK]
Prochaines étapes
- Proxy navigateur — service distinct pour l'automatisation de navigateur
- Guide des agents auto-hébergés
────────────────────────────────────────────────────────────
# Cron & Scheduler
SUMMARY: Planifiez des appels d'API récurrents — tâches cron qui se déclenchent selon une planification, parfait pour la synchronisation périodique et les rappels.
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
L'API Cron permet de planifier des appels HTTP récurrents vers des endpoints Synapse
(ou des endpoints HTTPS externes). Parfait pour la synchronisation périodique, les
rappels et les tâches de maintenance.
Endpoints
POST /cron
Crée une tâche planifiée.
[CODE BLOCK]
Réponse :
[CODE BLOCK]
GET /cron
Liste toutes les tâches planifiées.
[CODE BLOCK]
DELETE /cron/:id
Supprime une tâche planifiée.
[CODE BLOCK]
PUT /cron/:id/toggle
Active ou désactive une tâche sans la supprimer.
[CODE BLOCK]
Syntaxe de planification
Cron standard (5 champs)
[CODE BLOCK]
Exemples :
| Planification | Signification |
|----------|---------|
| | Toutes les heures |
| | Toutes les 15 minutes |
| | En semaine à 9 h |
| | Tous les dimanches à minuit |
| | Le premier de chaque mois à minuit |
Intervalle entier (secondes)
Pour des intervalles simples, passez un entier :
[CODE BLOCK]
Restrictions sur les endpoints
> [!WARNING]
> Les endpoints doivent être des URLs ou pointant vers :
> - La même instance Synapse (ex. )
> - Des URLs HTTPS publiques (pas d'IP privées, pas de localhost, pas d'IP de métadonnées)
Cela empêche les attaques SSRF où un mind compromis pourrait planifier des requêtes
vers des services internes.
Schémas courants
Rappel mémoire horaire (pour les agents LLM)
[CODE BLOCK]
Sauvegarde quotidienne
[CODE BLOCK]
Polling périodique du chat (toutes les 5 minutes)
[CODE BLOCK]
Déclencheur de rapport hebdomadaire
[CODE BLOCK]
Prochaines étapes
- API Variables
- API Webhooks
────────────────────────────────────────────────────────────
# Erreurs & gestion des erreurs
SUMMARY: Codes d'état HTTP, format de réponse d'erreur et comment se remettre des erreurs courantes.
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.
Erreurs & gestion des erreurs
Synapse utilise les codes d'état HTTP standard avec un format de réponse d'erreur
cohérent. Cette page explique comment interpréter et récupérer les erreurs.
Format de réponse d'erreur
Toutes les erreurs renvoient du JSON avec cette structure :
[CODE BLOCK]
| Champ | Description |
|-------|-------------|
| | Code d'état HTTP |
| | Nom de l'état HTTP |
| | Description de l'erreur lisible par l'humain |
| | URL vers la documentation pertinente (le cas échéant) |
Codes d'état HTTP
200 OK
Succès. La requête a été traitée correctement.
201 Created
Succès. Une nouvelle ressource a été créée (ex. ).
204 No Content
Succès. Aucun corps renvoyé (ex. ).
400 Bad Request
La requête était mal formée. Causes courantes :
- Champs JSON requis manquants
- Syntaxe JSON invalide
- Valeur d'énumération invalide (ex. mauvaise catégorie)
[CODE BLOCK]
Correction : Vérifiez le corps de la requête par rapport à la documentation de
l'API. Assurez-vous que tous les champs requis sont présents et ont des valeurs valides.
401 Unauthorized
L'authentification a échoué. Causes courantes :
- En-tête manquant
- Mind Key ou JWT invalide
- Utilisation d'une Mind Key là où un JWT est requis (ou inversement)
[CODE BLOCK]
Correction : Vérifiez votre jeton. Voir Authentification.
403 Forbidden
Vous êtes authentifié mais n'êtes pas autorisé à effectuer cette action. Causes
courantes :
- Tentative de suppression du mind d'un autre utilisateur
- Tentative de vérifier une mémoire avec une Mind Key (nécessite un JWT)
- Le mind est désactivé
Correction : Vérifiez si vous utilisez le bon type de jeton pour cet endpoint.
404 Not Found
Le chemin ou la ressource demandée n'existe pas.
> [!CRITICAL]
> Ne devinez PAS les chemins d'endpoints. Seuls les chemins listés dans
> existent. Si vous obtenez un 404, c'est que vous avez utilisé un
> mauvais chemin.
[CODE BLOCK]
Correction : Appelez pour voir la liste des endpoints valides.
Comparez votre URL à la liste caractère par caractère.
409 Conflict
La requête entre en conflit avec l'état existant. Causes courantes :
- Tentative d'inscription avec un email déjà existant
- URL de webhook en doublon
Correction : Utilisez une valeur différente, ou utilisez pour mettre à jour
la ressource existante.
429 Too Many Requests
Vous avez atteint une limite de débit. S'applique uniquement à l'authentification par
paramètre de requête (60/min).
[CODE BLOCK]
En-têtes de réponse :
[CODE BLOCK]
Correction : Passez à l'en-tête (sans limite de débit), ou
attendez secondes.
500 Internal Server Error
Erreur serveur. Cela ne devrait pas arriver — si c'est le cas, c'est un bug.
Correction :
1. Réessayez avec un backoff exponentiel (1 s, 2 s, 4 s, 8 s)
2. Vérifiez pour voir si le serveur fonctionne
3. Si cela persiste, signalez l'erreur
503 Service Unavailable
Le serveur est temporairement indisponible (ex. pendant un déploiement, une migration
de base de données).
Correction : Attendez et réessayez. Vérifiez .
Schémas de récupération
Réessai avec backoff exponentiel
[CODE BLOCK]
Gestion des erreurs d'authentification
[CODE BLOCK]
Scénarios d'erreur courants
"Mind Key fehlt oder ungültig"
- Vous avez oublié l'en-tête
- Vous avez utilisé mais la clé est erronée
- Vous utilisez un JWT là où une Mind Key est requise
"Route not found"
- Vous avez deviné un chemin qui n'existe pas
- Vous avez utilisé un verbe incorrect (ex. vs )
- Vérifiez pour les chemins valides
"Rate limit exceeded"
- Vous utilisez et avez dépassé 60 req/min
- Passez à l'en-tête
Prochaines étapes
- Authentification
- Vue d'ensemble de l'API
- Limites de débit
────────────────────────────────────────────────────────────
# API Memory
SUMMARY: Référence complète des 22 endpoints mémoire : stockage, rappel, recherche, recherche sémantique, synchronisation, audit et plus.
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)
API Memory
L'API Memory est le cœur de Synapse. Elle fournit 22 endpoints pour stocker,
récupérer, rechercher et gérer des mémoires structurées. Tous les endpoints
nécessitent une Mind Key pour l'authentification.
> [!CRITICAL]
> Appelez toujours au début de chaque session. C'est le
> seul moyen de reconstruire le contexte des sessions précédentes.
Catégories
Les mémoires sont organisées en 8 catégories :
| Catégorie | Cas d'usage |
|----------|----------|
| | Nom de l'utilisateur, rôle, infos de contact, préférences sur soi |
| | Goûts, aversions, style de travail, préférences de communication |
| | Faits vérifiables (détails de projet, dates, URLs) |
| | Statut de projet, jalons, architecture |
| | Choses dont l'utilisateur est bon |
| | Erreurs passées — à éviter de répéter |
| | Contexte pertinent à la session |
| | Notes diverses |
Priorités
- — utile de savoir
- — par défaut
- — important
- — à ne jamais oublier (identité de l'utilisateur, infos légales)
Endpoints principaux
GET /memory/recall
Renvoie TOUTES les mémoires sous forme de texte brut optimisé pour les LLM. Appelez-le
à chaque début de session.
[CODE BLOCK]
Réponse (text/plain) :
[CODE BLOCK]
POST /memory
Stocke une nouvelle mémoire ou met à jour une mémoire existante (même catégorie +
clé = mise à jour).
[CODE BLOCK]
Réponse :
GET /memory
Liste les mémoires avec filtres optionnels.
[CODE BLOCK]
PUT /memory/:id
Met à jour une mémoire spécifique par ID.
[CODE BLOCK]
DELETE /memory/:id
Supprime une seule mémoire.
[CODE BLOCK]
Endpoints de recherche
GET /memory/search
Recherche en texte intégral utilisant FTS5.
[CODE BLOCK]
Syntaxe FTS5 :
- Plusieurs mots = AND :
- Phrase :
- Préfixe :
- Booléen :
- Exclusion :
GET /memory/semantic-search
Recherche conceptuelle utilisant des embeddings (plus lente que FTS5 mais comprend
le sens).
[CODE BLOCK]
Renvoie les mémoires sémantiquement similaires à la requête, même si aucun mot-clé ne
correspond. Utile pour « trouver des mémoires à propos de X » où X est décrit
différemment.
GET /memory/by-tag
Liste les mémoires par tag.
[CODE BLOCK]
GET /memory/related/:id
Trouve les mémoires liées à une mémoire spécifique (via des tags partagés).
[CODE BLOCK]
Sync & Diff
GET /memory/diff
Synchronisation incrémentale — renvoie les mémoires modifiées depuis un horodatage.
[CODE BLOCK]
Réponse :
POST /memory/sync
Applique un diff depuis une autre instance (pour la synchronisation auto-hébergée).
[CODE BLOCK]
Opérations en masse
POST /memory/bulk-delete
Supprime plusieurs mémoires par ID.
[CODE BLOCK]
POST /memory/embed-batch
Génère des embeddings pour les mémoires qui n'en ont pas encore (pour la recherche
sémantique).
[CODE BLOCK]
GET /memory/embed-batch-status
Vérifie la progression de la génération d'embeddings.
[CODE BLOCK]
Vérification
Les mémoires ont un indicateur . Les mémoires stockées par l'agent sont non
vérifiées par défaut () ; les mémoires stockées par l'humain sont
vérifiées ().
POST /memory/verify
Marque une mémoire comme vérifiée (nécessite un JWT, pas une Mind Key).
[CODE BLOCK]
POST /memory/unverify
Marque une mémoire comme non vérifiée (nécessite un JWT).
[CODE BLOCK]
GET /memory/unverified
Liste les mémoires en attente de vérification humaine.
[CODE BLOCK]
Statistiques & Audit
GET /memory/stats
Statistiques agrégées pour le mind courant.
[CODE BLOCK]
Renvoie :
GET /memory/audit
Journal d'audit de toutes les opérations modifiant l'état.
[CODE BLOCK]
GET /memory/contradictions
Détecte les contradictions potentielles dans les mémoires stockées.
[CODE BLOCK]
GET /memory/expiring
Liste les mémoires dont la date d'expiration approche.
[CODE BLOCK]
Santé & Export
GET /memory/health
Vérification rapide de la santé du système de mémoire.
[CODE BLOCK]
GET /memory/mind-export
Export JSON complet de toutes les mémoires (pour sauvegarde).
[CODE BLOCK]
POST /memory/compact
Compacte les mémoires similaires (résumé automatique).
[CODE BLOCK]
Prochaines étapes
- Démarrage rapide pour les LLM
- Bonnes pratiques mémoire
- Recherche FTS5
- Recherche sémantique
────────────────────────────────────────────────────────────
# Vue d'ensemble de l'API & URL de base
SUMMARY: Tous les endpoints de l'API Synapse, l'URL de base, les schémas d'authentification et les formats de réponse en un coup d'œil.
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.
Vue d'ensemble de l'API & URL de base
L'API Synapse est une API HTTP RESTful. Tous les endpoints renvoient du JSON (sauf
mention contraire). Cette page couvre l'essentiel à connaître avant d'explorer des
endpoints spécifiques.
URL de base
[CODE BLOCK]
Tous les chemins de cette documentation sont relatifs à cette URL de base. Pour les
instances auto-hébergées, remplacez par votre propre URL.
Authentification
Deux méthodes, toutes deux envoyées via l'en-tête :
[CODE BLOCK]
Ou via un paramètre de requête (limité à 60/min) :
[CODE BLOCK]
Voir Authentification pour plus de détails.
Groupes d'endpoints
| Groupe | Auth | Description |
|-------|------|-------------|
| Public | Aucune | Page d'accueil, santé, OpenAPI, docs |
| Memory | Mind Key | CRUD, recherche, sync, embeddings |
| Chat | Mind Key / JWT | Messagerie asynchrone entre humain et agent |
| Tasks | Mind Key | Gestion des tâches |
| Scripts | Mind Key / JWT | Stockage persistant de scripts |
| Scheduler | Mind Key | Tâches cron + variables |
| Webhooks | Mind Key | Rappels HTTP sur événements |
| Computers | Mind Key / JWT | Contrôle à distance d'ordinateurs |
| User/Minds | JWT | Compte + gestion des minds |
| Sharing | JWT | Partage de minds entre utilisateurs |
| Push | JWT | Abonnements Web Push |
| Tools | Aucune | Heure, calculatrice, aléatoire (utilitaires publics) |
Formats de réponse
- JSON (par défaut) :
- Texte brut : renvoie du texte optimisé pour les LLM
- HTML : , , , ,
Enveloppe de réponse standard
Les réponses de succès renvoient directement les données :
[CODE BLOCK]
Les réponses d'erreur utilisent ce format :
[CODE BLOCK]
> [!NOTE]
> Le champ renvoie vers la documentation pertinente pour les erreurs courantes.
Codes d'état HTTP
| Code | Signification |
|------|---------|
| 200 | Succès (GET, PUT) |
| 201 | Créé (POST) |
| 204 | Aucun contenu (DELETE) |
| 400 | Requête incorrecte (erreur de validation) |
| 401 | Non autorisé (jeton manquant/invalide) |
| 403 | Interdit (mauvais type de jeton) |
| 404 | Introuvable (le chemin n'existe pas) |
| 409 | Conflit (doublon) |
| 429 | Trop de requêtes (limite de débit) |
| 500 | Erreur serveur |
Endpoints de découvrabilité
| Endpoint | Rôle |
|----------|---------|
| | Page d'accueil (optimisée LLM) |
| | Liste lisible par machine de tous les endpoints |
| | Liste d'endpoints en texte brut |
| | Spécification OpenAPI 3.0 |
| | Documentation complète de l'API (HTML) |
| | Docs de l'API en JSON |
| | Système de documentation (HTML) |
| | Index de documentation (JSON) |
| | Toutes les docs en un bloc de texte |
| | Terrain de jeu interactif pour l'API |
Limites de débit
| Méthode d'auth | Limite |
|-------------|-------|
| Mind Key (en-tête) | Aucune |
| Mind Key (?key=) | 60/min par IP |
| JWT (en-tête) | Aucune |
| Endpoints publics | Aucune |
Les réponses soumises à limite de débit incluent :
[CODE BLOCK]
Pagination
Les endpoints de liste prennent en charge et :
[CODE BLOCK]
Limite par défaut : 100. Limite maximale : 500.
CORS
Tous les endpoints prennent en charge CORS pour les clients basés sur navigateur :
[CODE BLOCK]
SDK & Clients
- SDK Node.js : (dépôt)
- Serveur MCP : (dépôt)
- Client HTTP : n'importe quelle bibliothèque HTTP (curl, fetch, axios, etc.)
Prochaines étapes
- API Memory — les endpoints les plus importants
- API Chat — communication asynchrone humain-agent
- Erreurs & gestion des erreurs
────────────────────────────────────────────────────────────
# Limites de débit & quotas
SUMMARY: Politique de limites de débit pour l'API Synapse — en-tête Bearer (illimité), ?key= (60/min), endpoints publics.
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.
Limites de débit & quotas
Synapse a une politique de limites de débit simple et prévisible, conçue pour
prévenir les abus sans gêner les usages légitimes.
Politique de limites de débit
| Méthode d'auth | Limite | Portée |
|-------------|-------|-------|
| Mind Key () | Aucune | Par mind |
| Mind Key () | 60 req/min | Par IP |
| JWT () | Aucune | Par utilisateur |
| Endpoints publics | Aucune | Globale |
> [!TIP]
> Utilisez toujours l'en-tête lorsque c'est possible. Il
> n'a aucune limite de débit. N'utilisez que pour les outils qui ne peuvent
> pas définir d'en-têtes personnalisés.
En-têtes de limite de débit
Lorsque vous utilisez l'authentification , les réponses incluent des en-têtes
de limite de débit :
[CODE BLOCK]
Lorsque vous dépassez la limite :
[CODE BLOCK]
Que faire en cas de limite de débit
Si vous obtenez un 429 :
1. Passez à l'en-tête Authorization (recommandé) :
[CODE BLOCK]
2. Ou attendez secondes et réessayez.
Pourquoi la limite ?key= existe
Le paramètre de requête est pratique pour les outils n'utilisant que des URLs
(navigateurs, commandes ), mais il a des implications de sécurité et de
performance :
- Sécurité : Les paramètres de requête sont consignés dans les journaux d'accès
serveur, l'historique du navigateur et les en-têtes Referer. Limiter l'usage réduit
l'exposition.
- Performance : L'authentification par paramètre de requête nécessite un
limiteur de débit basé sur l'IP (recherche Redis par requête), ce qui ajoute de la
latence. L'authentification par en-tête l'évite.
- Prévention des abus : Une URL fuite pourrait être partagée et martelée.
La limite par IP contient le rayon d'impact.
Schémas recommandés
Agents LLM
[CODE BLOCK]
Outils basés sur navigateur
Si votre outil ne peut qu'ouvrir des URLs :
[CODE BLOCK]
Serveur MCP
Les serveurs MCP utilisent toujours l'authentification par en-tête via la variable
d'environnement — aucune limite de débit ne s'applique.
Imports en masse
Pour les opérations en masse (ex. import de 1000 mémoires), utilisez toujours
l'authentification par en-tête. Les imports en masse via atteindront la
limite de débit en moins d'une minute.
Quotas (niveau mind)
Il n'y a actuellement aucun quota par mind sur la taille de stockage ou le nombre de
mémoires. Toutes les limites se situent au niveau auth/IP, pas au niveau des données.
Cela pourrait changer à l'avenir pour l'équité multi-tenant.
Surveiller votre utilisation
[CODE BLOCK]
Prochaines étapes
- Authentification
- Erreurs & gestion des erreurs
────────────────────────────────────────────────────────────
# API Scripts
SUMMARY: Stockage persistant de scripts — sauvegardez des scripts shell, Python ou Node réutilisables et récupérez-les 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
API Scripts
L'API Scripts fournit un stockage persistant pour les scripts réutilisables. Les
scripts sont nommés et versionnés dans un mind, et peuvent être récupérés en texte
brut — parfait pour les schémas .
Endpoints
POST /script
Stocke ou met à jour un script.
[CODE BLOCK]
GET /script/:name
Récupère le contenu du script en . Parfait pour le rediriger vers bash.
[CODE BLOCK]
GET /script/:name/info
Récupère les métadonnées du script sans le contenu.
[CODE BLOCK]
Réponse :
[CODE BLOCK]
GET /scripts
Liste tous les scripts du mind courant.
[CODE BLOCK]
DELETE /script/:name
Supprime un script.
[CODE BLOCK]
Cas d'usage courants
Scripts de déploiement
Stockez les procédures de déploiement standard pour que le LLM puisse les exécuter
sans avoir à re-dériver les étapes à chaque fois :
[CODE BLOCK]
Snippets de dépannage
Stockez des commandes de diagnostic pour les problèmes courants :
[CODE BLOCK]
Générateurs de configuration
Stockez des scripts qui génèrent des configurations :
[CODE BLOCK]
Prochaines étapes
- API Variables
- Cron & Scheduler
────────────────────────────────────────────────────────────
# API Tasks
SUMMARY: Gestion des tâches pour les agents LLM — créer, lister, mettre à jour, compléter, supprimer des tâches avec priorités.
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
API Tasks
L'API Tasks offre aux agents LLM un moyen structuré de suivre le travail multi-étapes.
Les tâches sont limitées au mind courant et persistent entre les sessions, ce qui
permet à l'agent de reprendre le travail là où il s'était arrêté.
Endpoints
GET /mind/tasks
Liste toutes les tâches du mind courant.
[CODE BLOCK]
Réponse :
[CODE BLOCK]
POST /mind/task
Crée une nouvelle tâche.
[CODE BLOCK]
GET /mind/task (paramètres de requête)
Crée une tâche via GET (pour les outils n'utilisant que des URLs).
[CODE BLOCK]
PUT /mind/task/:id
Met à jour une tâche existante.
[CODE BLOCK]
GET /mind/task/:id/complete
Marque une tâche comme terminée.
[CODE BLOCK]
GET /mind/task/:id/delete
Supprime définitivement une tâche.
[CODE BLOCK]
Priorités
- — non urgent
- — par défaut
- — important
- — à faire immédiatement
Statuts
- — créée, non commencée
- — en cours de traitement
- — terminée
- — abandonnée
Schéma : workflow piloté par les tâches
[CODE BLOCK]
Prochaines étapes
- Workflow piloté par les tâches
- Cron & Scheduler
────────────────────────────────────────────────────────────
# Outils utilitaires (heure, calcul, aléatoire)
SUMMARY: Endpoints utilitaires publics — heure serveur, calculatrice sûre, générateur de valeurs aléatoires. Aucune authentification requise.
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.
Outils utilitaires
Les endpoints sont des utilitaires publics — aucune authentification requise.
Ils sont utiles pour les agents LLM qui ont besoin de l'heure côté serveur, de calculs
sûrs ou de valeurs aléatoires.
GET /tools/time
Récupère l'heure actuelle du serveur, le fuseau horaire et le décalage UTC.
[CODE BLOCK]
Réponse :
[CODE BLOCK]
Cas d'usage : agents LLM qui ont besoin de savoir « quelle heure est-il maintenant »
pour la planification, les horodatages ou les calculs de dates relatives.
GET /tools/calc
Calculatrice sûre — arithmétique uniquement, pas d'. Prend en charge , ,
, , , , et les nombres.
[CODE BLOCK]
Réponse :
[CODE BLOCK]
> [!TIP]
> Utilisez ceci plutôt que d'essayer de faire des calculs de tête ou via l'analyse
> de chaînes. C'est sûr (aucune injection de code possible) et précis.
Opérateurs pris en charge
- addition
- soustraction
- multiplication
- division
- modulo
- parenthèses
- Nombres (entiers et décimaux)
Exemples
[CODE BLOCK]
GET /tools/random
Génère des valeurs aléatoires.
[CODE BLOCK]
Paramètres par type
| Type | Paramètres | Sortie |
|------|-----------|--------|
| | aucun | Chaîne UUID v4 |
| | , (par défaut 0-100) | Entier |
| | , (par défaut 0-100) | Flottant |
| | , (plage de longueur, par défaut 8-16) | Chaîne hexadécimale |
| | , (plage de longueur, par défaut 8-16) | Chaîne alphabétique |
Cas d'usage pour les agents LLM
Générer des identifiants uniques
[CODE BLOCK]
Calculer des pourcentages
[CODE BLOCK]
Obtenir l'horodatage courant
[CODE BLOCK]
Générer des données de test
[CODE BLOCK]
Prochaines étapes
- Vue d'ensemble de l'API — tous les groupes d'endpoints
- Erreurs & gestion des erreurs
────────────────────────────────────────────────────────────
# API Utilisateur & Minds
SUMMARY: Gestion de compte — inscription, connexion, création de minds, liste de minds, suppression de minds. Protégé par JWT.
KEY CONTEXT:
Auth: JWT (from /register or /login)
Register: POST /register { email, password, display_name? } → returns JWT
Login: POST /login { email, password } → returns JWT
Create mind: POST /minds { name, description? } → returns mind_key (shown once!)
List minds: GET /minds
Delete mind: DELETE /minds/:id (irreversible — deletes all memories!)
JWT expires after 7 days. Mind Key never expires.
Mind Key is shown only once at creation — save it permanently.
API Utilisateur & Minds
L'API Utilisateur & Minds gère l'administration de compte. Ces endpoints utilisent
l'authentification JWT (pas les Mind Keys) car ils opèrent au niveau du compte, pas au
niveau du mind.
Endpoints d'authentification
POST /register
Crée un nouveau compte utilisateur.
[CODE BLOCK]
Réponse :
[CODE BLOCK]
POST /login
Connexion à un compte existant.
[CODE BLOCK]
Réponse : identique à .
Endpoints Minds
POST /minds
Crée un nouveau mind. Renvoie la Mind Key — sauvegardez-la immédiatement, elle
n'est affichée qu'une seule fois.
[CODE BLOCK]
Réponse :
[CODE BLOCK]
> [!CRITICAL]
> La n'est affichée qu'une seule fois. Si vous la perdez, vous ne pouvez
> pas la récupérer — vous devez supprimer le mind et en créer un nouveau (ce qui
> perd toutes les mémoires stockées).
GET /minds
Liste tous les minds de l'utilisateur courant.
[CODE BLOCK]
Réponse :
[CODE BLOCK]
DELETE /minds/:id
Supprime un mind définitivement.
[CODE BLOCK]
> [!WARNING]
> Supprimer un mind est irréversible. Toutes les mémoires, tâches, historique de
> chat et scripts de ce mind sont définitivement perdus. Exportez d'abord via
> si vous avez besoin d'une sauvegarde.
Schéma multi-mind
La plupart des utilisateurs bénéficient de plusieurs minds pour isoler les contextes :
[CODE BLOCK]
Utilisez différentes Mind Keys dans différentes sessions LLM pour garder les contextes
isolés.
Sécurité du compte
Exigences de mot de passe
- Minimum 6 caractères
- Pas de maximum (utilisez un gestionnaire de mots de passe)
- Stocké sous forme de hachage bcrypt (jamais en clair)
Expiration du JWT
Les JWT expirent après 7 jours. Une fois expirés, appelez simplement à
nouveau.
Sécurité de la Mind Key
Les Mind Keys n'expirent jamais. Si une Mind Key est compromise :
1. Créez un nouveau mind via
2. Mettez à jour votre configuration LLM avec la nouvelle Mind Key
3. Supprimez le mind compromis via
Prochaines étapes
- Authentification — guide complet d'auth
- Mind Key vs JWT — guide de décision
- API Sharing — partager des minds avec d'autres utilisateurs
────────────────────────────────────────────────────────────
# API Variables
SUMMARY: Magasin clé-valeur rapide pour l'état LLM — compteurs, drapeaux, horodatages de dernière vue, progression partielle.
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)
API Variables
L'API Variables est un magasin clé-valeur rapide pour l'état éphémère. Contrairement
aux mémoires (qui sont indexées, recherchables et structurées), les variables sont
optimisées pour un accès lecture/écriture rapide — parfaites pour les compteurs, les
drapeaux et l'état de session.
Endpoints
POST /var
Définit ou met à jour une variable.
[CODE BLOCK]
GET /var/:key
Récupère une seule variable.
[CODE BLOCK]
Réponse :
[CODE BLOCK]
GET /var
Liste toutes les variables.
[CODE BLOCK]
DELETE /var/:key
Supprime une variable.
[CODE BLOCK]
Quand utiliser Variables ou Memory
| Cas d'usage | Utiliser |
|----------|-----|
| Nom d'utilisateur, préférences | Memory (recherchable, structuré) |
| Horodatage de dernière session | Variable (état éphémère) |
| Compteur (ex. messages envoyés) | Variable (mises à jour fréquentes) |
| État de workflow (« étape 3 sur 5 faite ») | Variable (transitoire) |
| Notes de projet longues | Memory (indexé en texte intégral) |
| Scripts réutilisables | Script store (nommé, versionné) |
Schémas courants
Suivre la dernière session
[CODE BLOCK]
Schéma de compteur
[CODE BLOCK]
Drapeaux de fonctionnalité
[CODE BLOCK]
Prochaines étapes
- API Memory — pour les données structurées et recherchables
- Cron & Scheduler
────────────────────────────────────────────────────────────
# API Webhooks
SUMMARY: Enregistrez des rappels HTTP pour les événements de mémoire, chat et tâches — soyez notifié quand les données changent.
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
API Webhooks
Les webhooks permettent de recevoir des rappels HTTP lorsque des événements se
produisent dans Synapse. Parfait pour déclencher des automatisations externes, envoyer
des notifications ou synchroniser vers d'autres systèmes.
Endpoints
POST /webhooks
Enregistre un nouveau webhook.
[CODE BLOCK]
Réponse :
[CODE BLOCK]
GET /webhooks
Liste tous les webhooks du mind courant.
[CODE BLOCK]
GET /webhooks/:id
Récupère un seul webhook.
[CODE BLOCK]
PUT /webhooks/:id
Met à jour un webhook (URL, événements, secret ou drapeau enabled).
[CODE BLOCK]
DELETE /webhooks/:id
Supprime un webhook.
[CODE BLOCK]
Types d'événements
| Schéma | Se déclenche quand |
|---------|------------|
| | Tout événement de mémoire |
| | Nouvelle mémoire stockée |
| | Mémoire mise à jour |
| | Mémoire supprimée |
| | Tout événement de chat |
| | Nouveau message de l'humain |
| | Tout événement de tâche |
| | Nouvelle tâche créée |
| | Tâche marquée comme terminée |
| | Tous les événements |
Payload du webhook
Lorsqu'un événement se déclenche, Synapse envoie un POST vers votre URL :
[CODE BLOCK]
Vérification de signature
Si vous définissez un , Synapse signe chaque payload avec HMAC-SHA256 :
[CODE BLOCK]
Vérifiez dans votre gestionnaire :
[CODE BLOCK]
Schéma : synchronisation en temps réel
[CODE BLOCK]
Prochaines étapes
- Cron & Scheduler
- Guide d'automatisation par webhooks
## CATÉGORIE : INTÉGRATION MCP
Intégration avec Claude, Cursor et autres clients MCP.
────────────────────────────────────────────────────────────
# MCP dans Claude Code
SUMMARY: Utilisez les outils Synapse depuis l'agent terminal Claude Code — mémoire persistante pour les sessions de codage.
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 dans Claude Code
Claude Code est l'agent de codage basé terminal d'Anthropic. Avec MCP Synapse, Claude
Code gagne une mémoire persistante entre les sessions de codage — il se souvient de
votre contexte de projet, des décisions passées et des schémas de codebase.
Configuration
Méthode 1 : commande CLI (recommandée)
[CODE BLOCK]
Méthode 2 : éditer le fichier de config
Éditez :
[CODE BLOCK]
Vérifier que ça fonctionne
Démarrez Claude Code :
[CODE BLOCK]
Dans le prompt Claude Code, tapez :
[CODE BLOCK]
Claude devrait appeler et répondre avec vos mémoires stockées.
Schémas courants
Persistance du contexte de projet
Au début d'une session de codage :
[CODE BLOCK]
Claude appelle , voit votre liste de projets et continue le travail
là où vous l'aviez laissé.
Décisions de codebase
Quand vous prenez une décision architecturale :
[CODE BLOCK]
Claude appelle avec la catégorie , priorité .
Éviter les erreurs passées
[CODE BLOCK]
Claude recherche les mémoires avec la catégorie et vous rappelle les erreurs
passées.
Suivi des tâches
[CODE BLOCK]
Claude appelle , et la tâche persiste entre les sessions.
Tool Profiles
Pour les sessions de codage où vous n'avez pas besoin des 119 outils :
[CODE BLOCK]
Dépannage
Le serveur MCP ne démarre pas
[CODE BLOCK]
Mind Key non reconnue
[CODE BLOCK]
Claude Code ne voit pas les outils
- Redémarrez Claude Code après les changements de config
- Vérifiez pour confirmer que Synapse est enregistré
- Voir Dépannage MCP
Prochaines étapes
- Configuration Claude Desktop
- Configuration Cursor
- Guide agent LLM persistant
────────────────────────────────────────────────────────────
# MCP dans Claude Desktop
SUMMARY: Connectez Synapse à Claude Desktop en 2 minutes. Claude obtient 79 outils Synapse nativement.
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 dans Claude Desktop
Claude Desktop est l'application desktop d'Anthropic pour macOS et Windows. Avec le
serveur MCP Synapse configuré, Claude obtient un accès natif aux 79 outils Synapse —
il peut stocker des mémoires, les rappeler, gérer des tâches, chatter avec vous, et
plus encore.
Prérequis
- Application Claude Desktop (macOS ou Windows)
- Node.js 18+ installé ()
- Votre Mind Key Synapse
Étape 1 : ouvrir le fichier de config
- macOS :
- Windows :
Si le fichier n'existe pas, créez-le.
Étape 2 : ajouter le serveur MCP Synapse
[CODE BLOCK]
> [!TIP]
> Si vous avez déjà d'autres serveurs MCP configurés, ajoutez simplement le bloc
> à l'intérieur de l'objet existant.
Étape 3 : redémarrer Claude Desktop
1. Quittez complètement Claude Desktop (Cmd+Q sur macOS, pas juste fermer la fenêtre)
2. Rouvrez Claude Desktop
3. Démarrez un nouveau chat
4. Cherchez l'icône de plug 🔌 en bas à gauche — elle devrait dire « 79 tools »
Étape 4 : tester
Dans un nouveau chat, tapez :
[CODE BLOCK]
Claude devrait appeler l'outil et répondre avec un résumé de vos
mémoires stockées (ou « No memories yet » si votre mind est vide).
Outils disponibles (sélection)
| Outil | Description |
|------|-------------|
| | Rappeler toutes les mémoires |
| | Stocker une nouvelle mémoire |
| | Rechercher des mémoires |
| | Lister les tâches |
| | Créer une tâche |
| | Vérifier les nouveaux messages |
| | Répondre à un message |
| | Ouvrir un onglet de navigateur |
| | Lister les ordinateurs enregistrés |
Liste complète : Qu'est-ce que MCP ?
Dépannage
Aucun outil n'apparaît dans Claude Desktop
1. Vérifiez la version de Node.js : (doit être ≥ 18)
2. Vérifiez que le fichier de config est du JSON valide (pas de virgules finales)
3. Redémarrez Claude Desktop complètement (Cmd+Q, pas juste fermer)
4. Vérifiez les logs Claude Desktop : (macOS)
Erreur « Mind Key invalid »
- Vérifiez que commence par
- Obtenez une nouvelle clé via (nécessite un JWT de )
- Pas de guillemets autour de la clé dans le JSON
npx introuvable
- Installez Node.js 18+ :
- Redémarrez le terminal après l'installation
- Sur macOS avec Homebrew :
Les outils apparaissent mais les appels échouent
- Vérifiez que est accessible :
- Vérifiez que votre Mind Key fonctionne :
- Voir Dépannage MCP
Tool Profiles (économiser des tokens)
Si vous utilisez un LLM plus petit ou voulez économiser des tokens de contexte,
définissez un profil d'outils :
[CODE BLOCK]
Profils : (8 outils), (25), (119, par défaut).
Prochaines étapes
- Configuration Claude Code
- Configuration Cursor
- Dépannage MCP
────────────────────────────────────────────────────────────
# MCP dans Continue.dev
SUMMARY: Connectez Synapse à Continue.dev — assistant de codage IA open source pour VS Code et JetBrains.
MCP dans Continue.dev
Continue.dev est un assistant de codage IA open source pour VS Code et les IDE
JetBrains. Avec MCP Synapse, Continue gagne une mémoire persistante entre les
sessions.
Prérequis
- VS Code ou IDE JetBrains
- Extension Continue.dev installée
- Node.js 18+
- Votre Mind Key Synapse
Configuration
Étape 1 : ouvrir la config Continue
Dans VS Code ou JetBrains :
1. Ouvrez la barre latérale de l'extension Continue
2. Cliquez sur l'icône engrenage → « Open config.json »
Ou éditez directement.
Étape 2 : ajouter le serveur MCP Synapse
[CODE BLOCK]
Étape 3 : recharger Continue
Rechargez la fenêtre VS Code (Cmd+Shift+P → « Reload Window ») ou redémarrez votre IDE.
Vérifier que ça fonctionne
Dans le chat Continue :
[CODE BLOCK]
Continue devrait appeler et répondre avec vos mémoires stockées.
Schémas courants
Contexte de projet
[CODE BLOCK]
Continue appelle , voit vos mémoires de projet et continue le travail
là où vous l'aviez laissé.
Schémas de revue de code
[CODE BLOCK]
Continue trouve vos schémas de revue de code stockés et les applique.
Mémoire de programmation en binôme
[CODE BLOCK]
Continue le stocke en tant que mémoire .
Dépannage
Le serveur MCP ne se connecte pas
1. Vérifiez que est du JSON valide
2. Vérifiez Node.js :
3. Consultez le panneau de sortie de Continue (View → Output → Continue)
4. Redémarrez l'IDE
Les outils n'apparaissent pas
- Vérifiez que la version de Continue prend en charge MCP (≥ 0.9.x)
- Vérifiez que la variable d'env est définie dans la config
- Cherchez les erreurs MCP dans les logs de Continue
Prochaines étapes
- Configuration Claude Desktop
- Client MCP personnalisé
────────────────────────────────────────────────────────────
# MCP dans Cursor
SUMMARY: Connectez Synapse à l'IDE Cursor pour une mémoire de projet persistante entre les sessions de codage.
MCP dans Cursor
Cursor est un IDE alimenté par IA basé sur VS Code. Avec MCP Synapse, Cursor gagne
une mémoire persistante entre les sessions — il se souvient de vos décisions de
projet, des schémas de codebase et des sessions de débogage passées.
Prérequis
- IDE Cursor installé ()
- Node.js 18+
- Votre Mind Key Synapse
Configuration
Étape 1 : ouvrir les paramètres Cursor
Dans Cursor :
1. Ouvrez les Paramètres (Cmd+, sur macOS, Ctrl+, sur Windows/Linux)
2. Recherchez « MCP » ou naviguez vers
Étape 2 : ajouter le serveur MCP Synapse
Cliquez sur « Add MCP Server » et configurez :
| Champ | Valeur |
|-------|-------|
| Nom | |
| Type | |
| Commande | |
| Env | |
Étape 3 : éditer config.json directement (alternative)
Cursor stocke la config MCP dans :
[CODE BLOCK]
Étape 4 : redémarrer Cursor
Redémarrez complètement Cursor (Cmd+Q et rouvrez sur macOS).
Vérifier que ça fonctionne
Dans le panneau de chat de Cursor (Cmd+L) :
[CODE BLOCK]
Cursor devrait appeler et répondre avec vos mémoires stockées.
Schémas courants
Onboarding de projet
À l'ouverture d'un nouveau projet :
[CODE BLOCK]
Cursor appelle et continue le travail là où vous l'aviez laissé.
Décisions d'architecture
[CODE BLOCK]
Cursor le stocke en tant que mémoire avec priorité .
Historique de débogage
[CODE BLOCK]
Cursor recherche les mémoires et vous rappelle les corrections passées.
Schémas de code inter-sessions
[CODE BLOCK]
Cursor trouve les mémoires sur les implémentations d'authentification que vous avez
déjà faites.
Dépannage
Le serveur MCP ne se connecte pas
1. Vérifiez Node.js : (≥ 18)
2. Testez le serveur MCP : (devrait démarrer sans erreurs)
3. Consultez les logs MCP de Cursor (View → Output → MCP)
4. Redémarrez Cursor complètement
Les outils n'apparaissent pas
- Vérifiez que est du JSON valide
- Vérifiez que la variable d'env est définie
- Vérifiez que la version de Cursor prend en charge MCP (≥ 0.42)
Mind Key invalide
[CODE BLOCK]
Prochaines étapes
- Configuration Claude Desktop
- Configuration Continue.dev
- Guide agent LLM persistant
────────────────────────────────────────────────────────────
# Construire un client MCP personnalisé
SUMMARY: Connectez-vous au serveur MCP Synapse depuis votre propre application en utilisant le SDK MCP.
Construire un client MCP personnalisé
Si vous construisez votre propre application LLM, vous pouvez vous connecter au
serveur MCP Synapse directement en utilisant le SDK MCP officiel. Cela donne à votre
application accès aux 79 outils Synapse.
SDKs
| Langage | Paquet |
|----------|---------|
| TypeScript/JavaScript | |
| Python | |
Exemple TypeScript
Installation
[CODE BLOCK]
Connexion via stdio
[CODE BLOCK]
Connexion via HTTP/SSE (distant)
[CODE BLOCK]
Exemple Python
Installation
[CODE BLOCK]
Connexion via stdio
[CODE BLOCK]
Tool Profiles
À la connexion, vous pouvez demander un profil d'outils spécifique via l'en-tête
(HTTP/SSE) ou la variable d'env (stdio) :
[CODE BLOCK]
Gestion des erreurs
[CODE BLOCK]
Cas d'usage
- Assistants IA personnalisés — construisez votre propre agent avec mémoire persistante
- Automatisation de workflow — enchaînez les outils Synapse dans des workflows personnalisés
- Pipelines de données — extraire les mémoires, transformer, charger ailleurs
- Tableaux de bord de surveillance — afficher les stats de mémoire, l'historique chat, les tâches
Prochaines étapes
- Spécification MCP
- Dépôt Synapse MCP
- Vue d'ensemble de l'API
────────────────────────────────────────────────────────────
# Dépannage MCP
SUMMARY: Résolvez les problèmes courants d'intégration MCP — serveur qui ne démarre pas, outils qui n'apparaissent pas, erreurs d'auth.
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/
Dépannage MCP
Problèmes courants et solutions lors de l'intégration de MCP Synapse avec votre client
LLM.
Liste de vérification de diagnostic rapide
1. ✅ Node.js 18+ installé ? ()
2. ✅ La Mind Key commence par ? (pas un JWT )
3. ✅ L'API Synapse est accessible ? ()
4. ✅ La Mind Key fonctionne ? ()
5. ✅ Le fichier de config est du JSON valide ? (pas de virgules finales, pas de commentaires)
6. ✅ Le client a-t-il été redémarré après le changement de config ?
7. ✅ Le serveur MCP démarre-t-il manuellement ? ()
Problème : aucun outil n'apparaît dans le client
Symptômes
- Claude Desktop / Cursor / Continue affiche 0 outils
- Pas d'icône 🔌 ou d'entrée « synapse » dans la liste des serveurs MCP
Solutions
1. Redémarrez le client complètement — Cmd+Q sur macOS (pas juste fermer la fenêtre)
2. Vérifiez l'emplacement du fichier de config :
- Claude Desktop macOS :
- Claude Desktop Windows :
- Cursor :
- Continue :
3. Validez le JSON — collez la config dans
4. Consultez les logs client pour les erreurs MCP :
- Claude Desktop : (macOS)
- Cursor : View → Output → MCP
5. Exécutez le serveur MCP manuellement pour voir les erreurs de démarrage :
[CODE BLOCK]
Problème : erreur « Mind Key invalid »
Symptômes
- Les outils apparaissent mais les appels échouent avec « 401 Unauthorized »
- Erreur : "Mind Key fehlt oder ungültig"
Solutions
1. Vérifiez le format de la Mind Key — commence par , 40 caractères
2. Testez directement :
[CODE BLOCK]
3. Vérifiez que la variable d'env est définie — pour le transport stdio, la variable d'env doit être dans la config du serveur MCP, pas dans votre shell
4. Obtenez une nouvelle Mind Key :
[CODE BLOCK]
Problème : npx introuvable
Symptômes
- Erreur : "npx: command not found"
- Le serveur MCP ne démarre pas
Solutions
1. Installez Node.js 18+ :
- macOS : ou téléchargez depuis
- Linux :
- Windows : téléchargez depuis
2. Redémarrez le terminal après l'installation
3. Vérifiez :
Problème : SYNAPSEURL inaccessible
Symptômes
- Le serveur MCP démarre mais les appels d'outils expirent
- Erreur : "fetch failed" ou "ECONNREFUSED"
Solutions
1. Testez la connectivité :
[CODE BLOCK]
2. Vérifiez le pare-feu d'entreprise — peut bloquer le HTTPS sortant
3. Essayez une URL alternative :
- Production :
- Serveur MCP :
4. Pour l'auto-hébergement : assurez-vous que votre instance Synapse fonctionne et est accessible
Problème : le serveur MCP plante
Symptômes
- Le serveur MCP se ferme immédiatement après le démarrage
- Les logs client affichent « MCP server disconnected »
Solutions
1. Exécutez manuellement pour voir l'erreur :
[CODE BLOCK]
2. Vérifiez les conflits de port — le serveur MCP utilise le port 13100 par défaut
3. Nettoyez le cache npx :
[CODE BLOCK]
4. Mettez à jour vers la dernière version :
[CODE BLOCK]
Problème : les appels d'outils renvoient 429
Symptômes
- Erreur : "Rate limit exceeded"
Solutions
Cela ne devrait pas arriver avec MCP (utilise l'auth par en-tête, sans limite de
débit). Si c'est le cas :
1. Vérifiez si vous utilisez quelque part — passez à l'auth par en-tête
2. Vérifiez — assurez-vous qu'elle pointe vers la bonne instance
3. Contactez le support si le problème persiste
Problème : les outils apparaissent mais ne fonctionnent pas
Symptômes
- Outils listés dans le client
- Appeler un outil renvoie une erreur ou aucun résultat
Solutions
1. Vérifiez le nom de l'outil — doit être exact (ex. , pas )
2. Vérifiez les arguments — consultez le schéma d'entrée de l'outil
3. Testez via API directe :
[CODE BLOCK]
4. Vérifiez la santé de Synapse :
[CODE BLOCK]
Obtenir de l'aide
Si aucune des solutions ci-dessus ne résout votre problème :
1. Consultez les tickets existants :
2. Ouvrez un nouveau ticket avec :
- Version du serveur MCP ()
- Nom et version du client
- Système d'exploitation
- Extraits de logs pertinents
- Étapes pour reproduire
Prochaines étapes
- Configuration Claude Desktop
- Configuration Claude Code
- Erreurs API
────────────────────────────────────────────────────────────
# Qu'est-ce que MCP ?
SUMMARY: Le Model Context Protocol permet aux LLM d'appeler des outils externes. Synapse expose 79 outils via le serveur MCP officiel.
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
Qu'est-ce que MCP ?
Le Model Context Protocol (MCP) est un standard ouvert d'Anthropic (2024) qui
permet aux LLM d'appeler des outils externes de manière structurée. Au lieu de coller
la documentation de l'API dans le prompt, vous enregistrez des outils auprès du
serveur MCP, et le LLM les appelle au besoin — comme du function calling, mais
standardisé et indépendant du client.
Serveur MCP Synapse
Synapse fournit un serveur MCP officiel ( sur npm) qui expose
79 outils couvrant toutes les fonctionnalités Synapse :
| Catégorie | Outils | Nombre |
|----------|-------|-------|
| 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 |
| Total | | 79+ |
Comment ça marche
[CODE BLOCK]
1. Vous configurez votre client LLM (Claude Desktop, Cursor, etc.) pour utiliser le serveur MCP Synapse
2. Le client démarre le serveur MCP (via )
3. Le serveur MCP se connecte à l'API Synapse en utilisant votre Mind Key
4. Le LLM voit les 79 outils comme des fonctions natives qu'il peut appeler
5. Quand le LLM a besoin de se souvenir de quelque chose, il appelle — le serveur MCP traduit cela en sur Synapse
Transports
Le serveur MCP Synapse prend en charge trois transports :
stdio (local, recommandé pour desktop)
[CODE BLOCK]
HTTP/SSE (distant, multi-tenant)
Connectez votre client MCP à :
[CODE BLOCK]
WebSocket (mobile, haut volume)
[CODE BLOCK]
Tool Profiles (v1.4.0)
Pour réduire la surcharge de tokens pour les LLM plus petits, le serveur MCP prend en
charge trois profils d'outils :
| Profil | Outils | Tokens | Idéal pour |
|---------|-------|--------|----------|
| | 8 (dispatch composite) | 500 | LLM auto-hébergés avec ≤8k de contexte |
| | 25 (nommés) | 2 500 | LLM de taille moyenne (Claude Haiku, GPT-3.5) |
| | 119 (tous) | 8 250 | Grands LLM (Claude Sonnet/Opus, GPT-4) — par défaut |
Contrôlez via :
- Variable d'env :
- En-tête :
Clients pris en charge
- Claude Desktop — application desktop d'Anthropic
- Claude Code — agent de codage terminal
- Cursor — IDE alimenté par IA
- Continue.dev — assistant de codage IA open source
- Cline — extension VS Code
- Tout client compatible MCP
Pourquoi utiliser MCP plutôt que l'API directe ?
| Approche | Avantages | Inconvénients |
|----------|------|------|
| API directe | Simple, pas de couche supplémentaire | Le LLM doit connaître les URLs, en-têtes, auth |
| MCP | Le LLM voit des outils natifs, pas de mémorisation d'URL | Processus serveur MCP supplémentaire |
Pour la plupart des cas d'usage d'agents LLM, MCP est le meilleur choix — le LLM n'a
pas besoin de mémoriser les chemins d'API ou les schémas d'auth.
Prochaines étapes
- Configuration Claude Desktop — config en 2 minutes
- Configuration Claude Code — intégration terminal
- Client MCP personnalisé — construisez le vôtre
## CATÉGORIE : GUIDES ET TUTORIELS
Guides pas à pas pour des scénarios concrets.
────────────────────────────────────────────────────────────
# Tests automatisés d'applications iOS
SUMMARY: Utilisez Synapse + l'API Computer Control pour automatiser les tests d'applications iOS via Simulator.
Tests automatisés d'applications iOS
Combinez le système de mémoire de Synapse avec l'API Computer Control pour construire
des tests d'applications iOS pilotés par LLM. Le LLM se souvient des scénarios de
test, apprend des échecs passés et s'adapte aux changements d'interface.
Architecture
[CODE BLOCK]
Prérequis
- Compte Synapse + Mind Key
- Serveur MCP Synapse configuré dans Claude Desktop
- iOS Simulator avec installé
- Ordinateur enregistré dans Synapse (voir API Computer Control)
Étape 1 : enregistrer l'ordinateur Simulator
Sur le Mac exécutant iOS Simulator :
[CODE BLOCK]
Étape 2 : stocker les scénarios de test en mémoire
Stockez les scénarios de test réutilisables en tant que mémoires :
[CODE BLOCK]
Étape 3 : exécution de test pilotée par LLM
Dans Claude Desktop (avec MCP Synapse configuré) :
[CODE BLOCK]
Claude va :
1. Appeler pour trouver la mémoire
2. Appeler pour voir l'état actuel
3. Exécuter chaque étape via (clic, saisie)
4. Vérifier les résultats via captures d'écran
5. Stocker tout échec en tant que mémoires
Étape 4 : tests auto-réparables
Quand un test échoue, stockez l'échec et la récupération :
[CODE BLOCK]
La prochaine fois que le LLM exécute le test, il rappelle l'échec et applique la
récupération automatiquement.
Étape 5 : suivi des résultats de test
Suivez les exécutions de test en tant que tâches :
[CODE BLOCK]
Commandes courantes
| Action | Commande |
|--------|---------|
| Lancer Simulator | |
| Capture d'écran | (via MCP Synapse) |
| Taper à (x,y) | |
| Saisir du texte | |
| Appuyer sur Home | |
Bonnes pratiques
> [!TIP]
> - Stockez les coordonnées UI en mémoire — l'UI change, mais le LLM peut réapprendre
> - Utilisez les labels d'accessibilité — plus stables que les coordonnées
> - Stockez les données de test séparément — utilisez des variables pour les noms d'utilisateur, mots de passe
> - Exécutez les tests dans un état propre — réinitialisez Simulator entre les exécutions
> - Journalisez les captures d'écran pour les échecs — utiles pour le débogage
Prochaines étapes
- Tests auto-réparables
- API Computer Control
- Bonnes pratiques mémoire
────────────────────────────────────────────────────────────
# Sauvegarde & restauration
SUMMARY: Exportez vos mémoires pour sauvegarde, migrez entre minds, restaurez après une perte de données.
Sauvegarde & restauration
Synapse fournit un export/import complet pour la sauvegarde de mémoire, la migration
et la reprise après sinistre. Ce guide couvre les opérations essentielles.
Export
Export complet du mind
Exportez toutes les mémoires d'un mind en JSON :
[CODE BLOCK]
Format de réponse :
[CODE BLOCK]
Export incrémental (diff)
Exportez uniquement les mémoires modifiées depuis un horodatage :
[CODE BLOCK]
Réponse :
[CODE BLOCK]
Sauvegardes automatisées
Planifiez des sauvegardes quotidiennes via cron :
[CODE BLOCK]
> [!NOTE]
> L'endpoint cron reçoit la réponse mais ne la stocke pas. Pour de vraies sauvegardes,
> pointez le cron vers votre propre serveur de sauvegarde qui enregistre la réponse.
Mieux : script de sauvegarde externe
[CODE BLOCK]
Ajoutez à crontab :
[CODE BLOCK]
Restauration
Restaurer vers le même mind
[CODE BLOCK]
Restaurer vers un nouveau mind
[CODE BLOCK]
Script de restauration Python
[CODE BLOCK]
Migration entre minds
[CODE BLOCK]
Sauvegarder d'autres données
N'oubliez pas de sauvegarder :
| Type de données | Endpoint |
|-----------|----------|
| Mémoires | |
| Tâches | |
| Scripts | |
| Webhooks | |
| Tâches cron | |
| Variables | |
| Historique chat | |
Vérification
Après restauration, vérifiez :
[CODE BLOCK]
Bonnes pratiques
> [!TIP]
> - Sauvegardez quotidiennement — automatisez avec cron
> - Testez les restaurations — une sauvegarde que vous ne pouvez pas restaurer est inutile
> - Conservez plusieurs versions — au moins 30 jours
> - Stockez hors site — S3, Backblaze B2, etc.
> - Chiffrez les sauvegardes sensibles — les mémoires peuvent contenir des PII
> - Documentez le processus de restauration — vous l'aurez oublié quand vous en aurez besoin
Prochaines étapes
- API Memory
- Cron & Scheduler — pour les sauvegardes automatisées
────────────────────────────────────────────────────────────
# Bonnes pratiques mémoire
SUMMARY: Comment structurer les mémoires pour un rappel efficace — catégories, clés, tags, priorités.
Bonnes pratiques mémoire
La façon dont vous structurez les mémoires détermine leur utilité. Ce guide couvre
les schémas pour catégoriser, tagger et prioriser les mémoires afin que le LLM puisse
rappeler la bonne information au bon moment.
Catégories : choisissez la plus spécifique
| Catégorie | Utiliser pour | Exemple |
|----------|---------|---------|
| | Nom d'utilisateur, rôle, infos de contact | |
| | Goûts, aversions, style de travail | |
| | Faits vérifiables | |
| | Statut de projet, décisions | |
| | Compétences de l'utilisateur | |
| | Erreurs passées à éviter | |
| | Contexte pertinent à la session | |
| | Notes diverses | |
> [!TIP]
> En cas de doute, utilisez pour les infos vérifiables et pour tout le
> reste. Ne sur-catégorisez pas — mieux vaut avoir un clair qu'un
> confus.
Clés : identifiants significatifs
Le champ est l'identifiant de la mémoire. Utilisez des clés significatives et
stables :
Bonnes clés :
-
-
-
-
Mauvaises clés :
- (non significative)
- (non descriptive)
- (la date n'aide pas le rappel)
Conventions de nommage des clés
- (minuscules avec tirets bas)
- Préfixez avec la catégorie : , ,
- Utilisez des noms descriptifs, pas des verbes
- Gardez en dessous de 50 caractères
Tags : pour la recherche et le filtrage
Les tags permettent le filtrage et la recherche rapides. Ajoutez 2-5 tags par mémoire :
[CODE BLOCK]
Schémas de tags
- Noms de projet : , ,
- Sujets : , , ,
- Statut : , ,
- Indicateurs de priorité : ,
> [!NOTE]
> Les tags sont insensibles à la casse. Utilisez des minuscules pour la cohérence.
Priorités : soyez réaliste
| Priorité | Utiliser pour | % des mémoires |
|----------|---------|---------------|
| | Identité utilisateur, infos légales, décisions irréversibles | 5 % |
| | Projets actifs, préférences importantes | 20 % |
| | La plupart des faits, notes, contexte | 65 % |
| | Éphémère, utile à savoir | 10 % |
> [!WARNING]
> Ne marquez pas tout . Si tout est critique, rien ne l'est. Réservez
> pour ce qui causerait un réel préjudice si c'était oublié.
Quand stocker ou non
Toujours stocker
- Identité utilisateur (nom, email, rôle)
- Préférences longue durée
- Décisions de projet et justification
- Erreurs passées et leçons apprises
- Engagements pris envers l'utilisateur
Ne pas stocker
- État transitoire (utilisez plutôt des variables)
- Historique de conversation verbatim (le système chat gère cela)
- Données sensibles (mots de passe, clés API)
- Faits facilement dérivables (date actuelle, contenu de fichiers)
- Contexte éphémère (utilisez la catégorie avec priorité basse)
Mettre à jour les mémoires
POST avec la même + met à jour la mémoire existante :
[CODE BLOCK]
> [!TIP]
> Utilisez des clés stables pour pouvoir mettre à jour sans créer de doublons. Le LLM
> doit re-POSTer la même clé quand les infos changent, pas créer de nouvelles mémoires.
Cycle de vie d'une mémoire
[CODE BLOCK]
- Create : POST /memory avec contexte complet
- Active : Rappeler fréquemment, mettre à jour au besoin
- Stale : Toujours pertinent mais pas activement utilisé (priorité plus basse ?)
- Archive : Définir la priorité sur , conserver pour référence historique
- Delete : DELETE /memory/:id quand plus pertinent
Nettoyage périodique
[CODE BLOCK]
Schéma : héritage de mémoire
Pour un contexte hiérarchique (projet → sous-projet → tâche) :
[CODE BLOCK]
Le LLM peut alors chercher pour trouver toutes les mémoires liées.
Schéma : journal de décisions
Stockez les décisions avec leur justification pour que le LLM ne les re-questionne
pas :
[CODE BLOCK]
Schéma : évitement des erreurs
Stockez les erreurs avec des instructions d'évitement spécifiques :
[CODE BLOCK]
Anti-schémas à éviter
> [!WARNING]
> - Stocker les journaux de conversation — le système chat gère cela
> - Stocker des fichiers entiers — utilisez le script store ou le stockage externe
> - Stocker l'état éphémère — utilisez des variables
> - Stocker des secrets — utilisez des variables d'environnement
> - Dupliquer les mémoires — utilisez des clés stables
> - Sur-tagger — 2-5 tags par mémoire est idéal
> - Tout est critique — soyez réaliste avec les priorités
Prochaines étapes
- API Memory
- Agent LLM persistant
- Stratégie de tagging mémoire
────────────────────────────────────────────────────────────
# Coordination multi-agent
SUMMARY: Coordonnez plusieurs agents LLM utilisant des minds, tâches et chat Synapse partagés.
Coordination multi-agent
Quand vous avez plusieurs agents LLM travaillant sur des tâches liées, Synapse fournit
la couche de coordination — mémoire partagée, affectation de tâches et chat asynchrone.
Schémas
Schéma 1 : Mind partagé (source unique de vérité)
Tous les agents partagent une Mind Key. Ils lisent/écrivent le même magasin de mémoire.
[CODE BLOCK]
Cas d'usage : petite équipe d'agents travaillant sur un projet.
Configuration :
[CODE BLOCK]
Coordination via tâches :
[CODE BLOCK]
Schéma 2 : Minds spécialisés (contextes isolés)
Chaque agent a son propre mind. Ils communiquent via un mind de « coordination »
partagé.
[CODE BLOCK]
Cas d'usage : agents avec différentes spécialités (codage, revue, déploiement).
Configuration :
[CODE BLOCK]
Coordination via mind partagé :
[CODE BLOCK]
Schéma 3 : hub-and-spoke (orchestrateur)
Un agent orchestrateur central affecte des tâches à des agents travailleurs.
[CODE BLOCK]
Cas d'usage : workflows complexes avec travail parallèle.
Implémentation :
[CODE BLOCK]
Coordination via chat
Les agents peuvent communiquer via le système de chat :
[CODE BLOCK]
> [!NOTE]
> Les messages de chat sont marqués par rôle. Définissez role=agent pour les messages
> agent-à-agent, role=human pour humain-à-agent.
Coordination via variables
Utilisez des variables pour une coordination légère (verrous, drapeaux) :
[CODE BLOCK]
Bonnes pratiques
> [!TIP]
> - Utilisez des minds séparés pour des préoccupations séparées — ne mélangez pas mémoire de codeur et de relecteur
> - Taguez les agents dans le chat — pour une adresse claire
> - Utilisez des tâches pour l'affectation de travail — pas le chat (le chat est pour la discussion)
> - Implémentez l'idempotence — les agents peuvent réessayer des opérations échouées
> - Journalisez tout — stockez les décisions en mémoire pour l'auditabilité
Prochaines étapes
- Agent LLM persistant
- Cookbook LLM
- Automatisation par webhooks
────────────────────────────────────────────────────────────
# Construire un agent LLM persistant
SUMMARY: Guide étape par étape pour construire un agent LLM qui se souvient entre les sessions en utilisant Synapse.
Vue d'ensemble
Ce guide vous accompagne dans la construction d'un agent LLM qui persiste le contexte
entre les sessions via Synapse. À la fin, votre agent pourra :
- Rappeler le contexte passé au début de la session
- Stocker les nouveaux apprentissages au fur et à mesure
- Suivre des tâches multi-étapes entre les sessions
- Communiquer avec les humains via chat asynchrone
Architecture
[CODE BLOCK]
Étape 1 : configurer la Mind Key
[CODE BLOCK]
Étape 2 : protocole de début de session
Au début de chaque session, rappeler toutes les mémoires :
[CODE BLOCK]
Étape 3 : stocker les nouveaux apprentissages
Chaque fois que l'agent apprend quelque chose qui mérite d'être retenu :
[CODE BLOCK]
Étape 4 : gestion des tâches
Suivez le travail multi-étapes entre les sessions :
[CODE BLOCK]
Étape 5 : chat asynchrone avec les humains
Pollinez les messages entre les appels d'outils :
[CODE BLOCK]
Étape 6 : protocole de fin de session
À la fin de la session, stocker le contexte final :
[CODE BLOCK]
Schéma complet
[CODE BLOCK]
Bonnes pratiques
> [!TIP]
>
> - Toujours rappeler d'abord — ne jamais commencer le travail sans charger le contexte
> - Stockez proactivement — n'attendez pas la fin de session
> - Utilisez des clés significatives — , , pas
> - Taguez tout — les tags alimentent la recherche et le filtrage
> - Définissez des priorités réalistes — tout n'est pas
Prochaines étapes
- Cookbook LLM — schémas pratiques
- Bonnes pratiques mémoire
- Coordination multi-agent
────────────────────────────────────────────────────────────
# Pipelines de test auto-réparables
SUMMARY: Construisez des pipelines de test qui apprennent des échecs et s'adaptent automatiquement en utilisant la mémoire Synapse.
Pipelines de test auto-réparables
Les suites de test traditionnelles se cassent quand l'UI change. Les tests
auto-réparables utilisent la mémoire Synapse pour apprendre des échecs passés et
s'adapter — réduisant les tests instables et la charge de maintenance.
Concept
[CODE BLOCK]
1. Le test s'exécute
2. S'il échoue, stocker l'échec (ce qui n'a pas marché, pourquoi, comment corriger)
3. Prochaine exécution : rappeler les échecs pertinents avant d'exécuter
4. Appliquer automatiquement les corrections connues
Implémentation
Étape 1 : wrapper de test
Enveloppez chaque test avec rappel/stockage mémoire :
[CODE BLOCK]
Étape 2 : logique de test adaptative
Dans le test, vérifiez les échecs connus et appliquez les corrections :
[CODE BLOCK]
Étape 3 : stratégies de récupération
Stockez les stratégies de récupération en mémoire :
[CODE BLOCK]
Étape 4 : intégration CI
[CODE BLOCK]
Étape 5 : tableau de bord d'analyse des échecs
[CODE BLOCK]
Bonnes pratiques
> [!TIP]
> - Stockez les tracebacks — ils contiennent la ligne exacte qui a échoué
> - Taguez par nom de test — permet un filtrage rapide
> - Utilisez la catégorie — sépare des mémoires régulières
> - Définissez la priorité — les échecs ne doivent jamais être oubliés
> - Nettoyage périodique — supprimez les mémoires pour les problèmes résolus
> - Ne stockez pas de données sensibles — identifiants, PII
Schémas d'échec courants à stocker
| Type d'échec | Que stocker |
|--------------|---------------|
| Élément introuvable | Sélecteur essayé, état de la page, capture d'écran |
| Timeout | Temps d'attente, ce qui était attendu |
| Assertion échouée | Valeur attendue vs réelle |
| Erreur réseau | URL, code d'état, corps de réponse |
| Permission refusée | Permission requise, rôle utilisateur actuel |
Prochaines étapes
- Tests automatisés iOS
- Bonnes pratiques mémoire
- Cookbook récupération d'erreurs
────────────────────────────────────────────────────────────
# Automatisation par webhooks
SUMMARY: Déclenchez des systèmes externes quand les mémoires changent — synchronisation, notification, automatisation.
Automatisation par webhooks
Les webhooks permettent de déclencher des systèmes externes quand des événements
Synapse se déclenchent. Ce guide couvre les schémas d'automatisation courants.
Schémas courants
Schéma 1 : notification sur mémoire critique
Envoyez un message Slack quand une mémoire critique est stockée :
[CODE BLOCK]
Enregistrez le webhook :
[CODE BLOCK]
Schéma 2 : synchronisation vers système externe
Synchronisez les mémoires vers Notion, Obsidian ou n'importe quelle KB externe :
[CODE BLOCK]
Schéma 3 : déclencher CI/CD
Déclenchez un déploiement quand une mémoire « release » est stockée :
[CODE BLOCK]
Schéma 4 : réveiller l'agent sur message humain
Déclenchez une exécution d'agent LLM quand un humain envoie un message de chat :
[CODE BLOCK]
Schéma 5 : agréger les métriques
Suivez la croissance de la mémoire, l'activité chat, la complétion des tâches :
[CODE BLOCK]
Vérification de signature
Vérifiez toujours les signatures de webhook pour empêcher l'usurpation :
[CODE BLOCK]
Logique de réessai
Synapse réessaie les webhooks échoués avec un backoff exponentiel. Votre gestionnaire
devrait :
1. Renvoyer 200 rapidement — ne pas faire de travail lourd de manière synchrone
2. Mettre en file le travail — utiliser un système de tâches en arrière-plan
3. Être idempotent — le même événement peut être livré deux fois
[CODE BLOCK]
Débogage des webhooks
Consulter l'historique de livraison
Les livraisons de webhook sont journalisées. Vérifiez les livraisons récentes de votre
webhook :
[CODE BLOCK]
Tester le webhook manuellement
[CODE BLOCK]
Problèmes courants
| Problème | Correction |
|-------|-----|
| Réponses 4xx | Vérifiez que votre gestionnaire renvoie 200 |
| Réponses 5xx | Erreur serveur — vérifiez les logs de votre application |
| Timeout | Renvoyez 200 rapidement, mettez le travail en file asynchrone |
| Livraisons en double | Rendez le gestionnaire idempotent |
| Non-correspondance de signature | Vérifiez que le secret est correct |
Bonnes pratiques
> [!TIP]
> - Toujours vérifier les signatures — ne jamais sauter cela
> - Renvoyer 200 rapidement — ne pas bloquer Synapse
> - Être idempotent — gérer les livraisons en double
> - Utiliser des événements spécifiques — pas
> - Surveiller les échecs de livraison — configurez l'alerting
Prochaines étapes
- API Webhooks
- Cron & Scheduler
- Agent LLM persistant
## CATÉGORIE : CONCEPTS
Architecture et concepts derrière Synapse.
────────────────────────────────────────────────────────────
# Architecture de Synapse
SUMMARY: Comment Synapse est construit — Fastify, PostgreSQL, FTS5, embeddings, serveur MCP.
Architecture de Synapse
Synapse est une API de mémoire multi-tenant construite sur Fastify, PostgreSQL avec
FTS5, et un service d'embeddings optionnel pour la recherche sémantique.
Architecture globale
[CODE BLOCK]
Composants principaux
1. API Synapse (Fastify)
Le serveur HTTP principal. Gère :
- Endpoints REST (, , , etc.)
- Authentification (Mind Key pour les agents, JWT pour les humains)
- Limitation de débit (auth uniquement)
- Service de fichiers statiques (interface web sur , , etc.)
- Dispatch des webhooks
Construit avec Fastify 5 pour la performance. Fonctionne sur le port 12800 en
production.
2. PostgreSQL avec FTS5
Le magasin de données principal. Utilise PostgreSQL avec l'extension FTS5 pour la
recherche en texte intégral.
Tables principales :
| Table | Rôle |
|-------|---------|
| | Comptes utilisateurs |
| | Scopes de mind (chacun a une Mind Key) |
| | Enregistrements de mémoire avec table virtuelle FTS5 |
| | Gestion des tâches |
| | Historique de chat |
| | Scripts persistants |
| | Enregistrements de webhooks |
| | Tâches planifiées |
| | Magasin clé-valeur |
| | Piste d'audit |
FTS5 permet la recherche en texte intégral sub-milliseconde sur tout le contenu
de mémoire. Voir Recherche FTS5 pour plus de détails.
3. Service d'embeddings (optionnel)
Pour la recherche sémantique, Synapse génère des embeddings vectoriels du contenu des
mémoires. Ils sont stockés à côté des mémoires et utilisés pour la recherche de
similarité.
- Fournisseur : configurable (OpenAI, modèle local, etc.)
- Stocké comme colonne dans la table
- Utilisé par l'endpoint
- Voir Recherche sémantique
4. Serveur MCP (service séparé)
Le serveur MCP Synapse s'exécute comme un processus distinct (port 13100). Il :
- Expose 79 outils via Model Context Protocol
- Prend en charge les transports stdio, HTTP/SSE et WebSocket
- Traduit les appels d'outils MCP en appels d'API Synapse
- Multi-tenant : une Mind Key par session
5. Proxy navigateur (service séparé)
Pour l'automatisation de navigateur, un service distinct basé sur Playwright
s'exécute sur le port 13000. Le serveur MCP peut l'appeler pour les outils
.
6. Proxy SSH (service séparé)
Pour les commandes distantes basées sur SSH, un service distinct s'exécute sur le
port 12900.
Modèle multi-tenant
[CODE BLOCK]
Chaque mind est entièrement isolé. Les Mind Keys accordent l'accès à un seul mind.
Les JWT accordent l'accès au compte utilisateur (pour gérer les minds).
Voir Multi-tenancy pour plus de détails.
Flux de requêtes
Requête de stockage mémoire
[CODE BLOCK]
Requête de recherche mémoire
[CODE BLOCK]
Déploiement
Synapse est déployé comme conteneur Docker. Voir :
[CODE BLOCK]
Caractéristiques de performance
| Opération | Latence | Débit |
|-----------|---------|------------|
| Stockage mémoire | 5 ms | 1000+ req/s |
| Rappel mémoire | 20 ms | 500 req/s |
| Recherche FTS5 | 10 ms | 800 req/s |
| Recherche sémantique | 50 ms | 200 req/s |
| Polling chat | 5 ms | 2000 req/s |
Prochaines étapes
- Modèle de mémoire
- Multi-tenancy
- Recherche FTS5
────────────────────────────────────────────────────────────
# Recherche en texte intégral FTS5
SUMMARY: Comment Synapse utilise SQLite FTS5 pour la recherche de mémoire en texte intégral sub-milliseconde.
Recherche en texte intégral FTS5
Synapse utilise FTS5 (Full-Text Search 5) pour une recherche de mémoire rapide et
flexible. Cette page explique son fonctionnement et comment l'utiliser efficacement.
Qu'est-ce que FTS5 ?
FTS5 est une extension SQLite (aussi disponible dans PostgreSQL via des extensions)
qui fournit des capacités de recherche en texte intégral. Elle :
- Indexe le contenu textuel pour la recherche rapide par mot-clé
- Prend en charge les opérateurs booléens (AND, OR, NOT)
- Prend en charge la correspondance de phrases avec des guillemets
- Prend en charge la correspondance par préfixe avec
- Classe les résultats par pertinence
Synapse utilise FTS5 pour indexer tout le contenu des mémoires, ce qui permet une
recherche sub-milliseconde à travers des milliers de mémoires.
Comment Synapse utilise FTS5
Lorsque vous faites :
1. Le contenu de la mémoire est stocké dans la table
2. Le contenu est aussi inséré dans la table virtuelle FTS5
3. FTS5 tokenize et indexe automatiquement le contenu
Lorsque vous faites :
1. Synapse analyse la requête en utilisant la syntaxe FTS5
2. Exécute un contre l'index FTS5
3. Filtre par (isolation tenant)
4. Renvoie les résultats classés
Syntaxe de requête
Recherche simple par mot-clé
[CODE BLOCK]
Renvoie les mémoires contenant « docker ».
Plusieurs mots-clés (AND implicite)
[CODE BLOCK]
Renvoie les mémoires contenant À LA FOIS « docker » ET « swarm ».
Correspondance de phrase
[CODE BLOCK]
Renvoie les mémoires contenant la phrase exacte « docker swarm ».
Correspondance par préfixe
[CODE BLOCK]
Renvoie les mémoires contenant des mots commençant par « docker » (ex. « dockers »,
« dockerfile », « dockerize »).
Booléen OR
[CODE BLOCK]
Renvoie les mémoires contenant « docker » OU « kubernetes ».
Booléen NOT
[CODE BLOCK]
Renvoie les mémoires contenant « docker » mais PAS « swarm ».
Regroupement
[CODE BLOCK]
Renvoie les mémoires contenant « docker » ou « kubernetes », mais pas « test ».
Exemples pratiques
Trouver des mémoires sur un projet
[CODE BLOCK]
Trouver une phrase exacte
[CODE BLOCK]
Exclure les mémoires de test
[CODE BLOCK]
Rechercher par technologie
[CODE BLOCK]
Classement
FTS5 classe les résultats par pertinence en utilisant l'algorithme BM25. Facteurs :
- Fréquence du terme (combien de fois le terme apparaît)
- Fréquence inverse de document (les termes rares sont mieux classés)
- Longueur du document (les documents plus courts avec le terme sont mieux classés)
- Pondération de colonne (titre > contenu)
Les résultats sont renvoyés dans l'ordre de classement (les plus pertinents d'abord).
Performance
| Opération | Latence |
|-----------|---------|
| Recherche dans 100 mémoires | < 5 ms |
| Recherche dans 1 000 mémoires | < 10 ms |
| Recherche dans 10 000 mémoires | < 25 ms |
| Recherche dans 100 000 mémoires | < 100 ms |
FTS5 est hautement optimisé pour les charges de travail à forte lecture.
Limites
Stemming
FTS5 ne fait pas de stemming par défaut. « running » et « run » sont des termes
différents.
Contournement : Utilisez la correspondance par préfixe :
Tolérance aux fautes de frappe
FTS5 ne prend pas en charge la correspondance floue. Une faute de frappe ne renverra
aucun résultat.
Contournement : Utilisez la recherche sémantique
() pour la correspondance conceptuelle.
Mots vides
Les mots courants (the, a, an, is) sont indexés mais peuvent ne pas être utiles pour
la recherche. FTS5 gère cela automatiquement.
FTS5 vs recherche sémantique
| Aspect | FTS5 | Recherche sémantique |
|--------|------|-----------------|
| Vitesse | Sub-milliseconde | 50-100 ms |
| Correspondance | Mots-clés exacts | Conceptuelle |
| Tolérance aux fautes | Aucune | Quelque peu |
| Stemming | Aucun | Implicite |
| Requiert des embeddings | Non | Oui |
| Idéal pour | Termes spécifiques | Concepts |
Utilisez FTS5 lorsque vous connaissez les mots-clés. Utilisez la recherche sémantique
lorsque vous voulez « des mémoires sur X » où X est décrit différemment.
Bonnes pratiques
> [!TIP]
> - Utilisez des termes spécifiques — « docker swarm » bat « container orchestration »
> - Citez les phrases — garantit la correspondance de phrase
> - Utilisez un préfixe pour les variantes — capture « deploy », « deployment », « deploying »
> - Excluez le bruit — filtre les mémoires de test
> - Combinez avec les tags — affine les résultats
Prochaines étapes
- Recherche sémantique
- API Memory
- Bonnes pratiques mémoire
────────────────────────────────────────────────────────────
# Le modèle de mémoire
SUMMARY: Comment les mémoires sont structurées — catégories, clés, tags, priorités, sources, vérification.
Le modèle de mémoire
Le modèle de mémoire de Synapse est conçu pour les agents LLM — suffisamment structuré
pour un rappel fiable, suffisamment flexible pour tout domaine.
Anatomie d'une mémoire
[CODE BLOCK]
Champs
| Champ | Type | Requis | Description |
|-------|------|----------|-------------|
| | string | auto | Identifiant unique (memxxx) |
| | enum | ✅ | Une des 8 catégories |
| | string | ✅ | Identifiant stable (utilisé pour les mises à jour) |
| | string | ✅ | Le contenu de la mémoire (n'importe quel texte) |
| | string[] | – | Pour la recherche et le filtrage |
| | enum | – | low, normal, high, critical (par défaut : normal) |
| | enum | auto | user, agent (qui l'a stockée) |
| | bool | auto | Un humain a-t-il vérifié ceci ? |
| | float | – | 0.0 à 1.0 (par défaut : 1.0 pour user, 0.7 pour agent) |
| | timestamp | – | Quand oublier cette mémoire |
| | string | auto | Quel mind possède ceci |
| | timestamp | auto | Premier stockage |
| | timestamp | auto | Dernière modification |
Catégories
Huit catégories couvrent les cas d'usage courants des agents LLM :
| Catégorie | Rôle | Exemple de contenu |
|----------|---------|-----------------|
| | Qui est l'utilisateur | "User is Michael Schäfer, software engineer in Berlin" |
| | Préférences utilisateur | "Prefers concise technical responses" |
| | Faits vérifiables | "Office is in Berlin, timezone Europe/Berlin" |
| | Statut de projet | "Synapse v1.5.0 deployed, working on v1.6.0 docs" |
| | Compétences de l'utilisateur | "Advanced Python, 10+ years" |
| | Erreurs passées | "Forgot to bump npm version — CI failed" |
| | Contexte de session | "Currently reviewing PR #42" |
| | Notes diverses | "Try Redis for caching next sprint" |
Clés : identifiants stables
Le champ est critique — c'est ainsi que vous mettez à jour les mémoires sans
créer de doublons.
[CODE BLOCK]
Règles de clé :
- Doit être unique dans (catégorie, mind)
- Utilisez
- Préfixez avec la catégorie pour plus de clarté : ,
- Gardez-la stable — ne changez pas les clés après création
Tags : pour la recherche
Les tags permettent le filtrage et la recherche rapides :
[CODE BLOCK]
Bonnes pratiques de tag :
- 2-5 tags par mémoire (ne pas sur-tagger)
- Minuscules pour la cohérence
- Utilisez des noms de projet, sujets, technologies
- Les tags sont insensibles à la casse
Niveaux de priorité
| Priorité | Quand l'utiliser | Comportement de rappel |
|----------|-------------|-----------------|
| | Identité, juridique, irréversible | Toujours en haut du rappel |
| | Projets actifs, préférences clés | Proéminent dans le rappel |
| | La plupart des mémoires (par défaut) | Ordre de rappel standard |
| | Éphémère, utile à savoir | Peut être résumé |
trie par priorité (critical d'abord), puis par récence.
Source : User vs Agent
Les mémoires sont marquées avec :
- — stockée par un humain (via JWT ou interface humaine)
- — stockée par un agent LLM (via Mind Key)
Cela affecte :
- Vérification : les mémoires sont auto-vérifiées, les mémoires ne le sont pas
- Confiance : par défaut à 1.0, à 0.7
- Rappel : marque les mémoires non vérifiées avec « (unverified) »
> [!NOTE]
> Traitez les mémoires avec un scepticisme approprié. Elles peuvent être
> déduites ou supposées plutôt que directement énoncées par l'utilisateur.
Vérification
Le drapeau indique qu'un humain a confirmé la mémoire :
- Mémoires : auto-vérifiées ()
- Mémoires : non vérifiées par défaut ()
Vérifiez les mémoires via :
[CODE BLOCK]
> [!NOTE]
> La vérification nécessite un JWT (auth humaine), pas une Mind Key (auth agent).
> Cela garantit que seuls les humains peuvent marquer des mémoires comme vérifiées.
Confiance
Le champ (0.0 à 1.0) indique la fiabilité de la mémoire :
- 1.0 — directement énoncée par l'utilisateur
- 0.7 — déduite par l'agent
- 0.5 — incertaine, nécessite vérification
- 0.0 — explicitement doutée
Définissez la confiance lors du stockage :
[CODE BLOCK]
Expiration
Définissez pour les mémoires sensibles au temps :
[CODE BLOCK]
Les mémoires expirées ne sont pas renvoyées par (mais existent
toujours en base). Utilisez pour voir les mémoires
expirant bientôt.
Cycle de vie d'une mémoire
[CODE BLOCK]
Comportement de rappel
renvoie un résumé en texte brut optimisé pour le contexte LLM :
[CODE BLOCK]
- Trié par priorité (critical → low), puis par récence
- Mémoires non vérifiées marquées avec
- Tags inclus pour le contexte
- Texte brut (pas d'analyse JSON nécessaire)
Prochaines étapes
- API Memory
- Bonnes pratiques mémoire
- Recherche FTS5
────────────────────────────────────────────────────────────
# Multi-tenancy & isolation
SUMMARY: Comment Synapse isole les données entre utilisateurs et minds — frontières de sécurité expliquées.
Multi-tenancy & isolation
Synapse est multi-tenant : plusieurs utilisateurs, chacun avec plusieurs minds,
entièrement isolés les uns des autres. Cette page explique le modèle d'isolation.
Hiérarchie des tenants
[CODE BLOCK]
Niveaux d'isolation
Niveau 1 : isolation utilisateur
Chaque compte utilisateur est isolé. Alice ne peut pas :
- Voir les minds de Bob
- Accéder aux mémoires de Bob (même avec son JWT)
- Lister les infos de compte de Bob
Appliqué par : colonne sur toutes les tables, le JWT contient ,
toutes les requêtes filtrent par .
Niveau 2 : isolation de mind
Au sein d'un utilisateur, chaque mind est isolé. Le Mind A ne peut pas :
- Voir les mémoires du Mind B
- Accéder aux tâches, chat, scripts du Mind B
Appliqué par : colonne sur toutes les tables de données, la Mind Key
contient , toutes les requêtes filtrent par .
> [!CRITICAL]
> L'isolation par Mind Key est la frontière de sécurité principale. Une Mind Key
> fuite accordant un accès complet aux données de ce mind — mais UNIQUEMENT ce mind.
Jetons d'authentification
| Jeton | Portée | Ce à quoi il peut accéder |
|-------|-------|-------------------|
| Mind Key | Un seul mind | Données de ce mind uniquement |
| JWT | Compte utilisateur | Gestion de compte (créer/lister/supprimer des minds) |
| Computer Token | Un seul ordinateur | Commandes de cet ordinateur |
Accès inter-minds
Au sein du même utilisateur
L'utilisateur peut accéder à tous ses minds via JWT (ex. les liste tous).
Mais pour lire/écrire des données mémoire, il a besoin de la Mind Key spécifique.
Entre utilisateurs
Les utilisateurs ne peuvent pas accéder aux données des autres — SAUF s'ils partagent
explicitement un mind via l'API Sharing :
[CODE BLOCK]
Après le partage, Bob peut accéder au Mind A via son JWT (en lecture seule si
).
Frontières de sécurité
[CODE BLOCK]
Schémas multi-tenant courants
Schéma 1 : utilisateur unique, mind unique
Le plus courant pour les utilisateurs individuels d'agents LLM.
- 1 compte utilisateur
- 1 mind
- 1 Mind Key
- Toutes les mémoires dans un seul scope
Schéma 2 : utilisateur unique, plusieurs minds
Pour les utilisateurs avec plusieurs contextes (travail, personnel, projets).
- 1 compte utilisateur
- N minds (ex. « work », « personal », « project-x »)
- N Mind Keys
- Chaque session LLM utilise une Mind Key
Schéma 3 : mind partagé en équipe
Pour les équipes collaborant sur un projet.
- 1 utilisateur crée le mind (obtient la Mind Key)
- Le créateur partage avec les membres de l'équipe via JWT
- Tous les membres y accèdent via JWT (ou Mind Key partagée)
> [!WARNING]
> Partager une Mind Key donne un accès complet en lecture/écriture. Pour la
> collaboration en équipe, préférez l'API Sharing (basée JWT) au partage direct de
> Mind Keys.
Schéma 4 : fournisseur SaaS
Pour les applications qui intègrent Synapse comme couche mémoire.
- Chaque client = 1 compte utilisateur
- Chaque projet client = 1 mind
- L'application stocke les Mind Keys par client/projet
- Isolation complète entre clients
Vérification de l'isolation
Test : une Mind Key ne peut pas accéder à d'autres minds
[CODE BLOCK]
Test : un JWT ne peut pas lire directement les données de mémoire
[CODE BLOCK]
Bonnes pratiques
> [!TIP]
> - Utilisez un mind par projet/contexte — l'isolation est votre amie
> - Ne partagez jamais de Mind Keys — utilisez l'API Sharing à la place
> - Pivotez les Mind Keys si compromises (supprimer le mind, en créer un nouveau)
> - Auditez les minds partagés — passez en revue périodiquement
> - Utilisez le JWT pour l'interface humaine — n'exposez jamais les Mind Keys aux utilisateurs finaux
Prochaines étapes
- Authentification
- Mind Key vs JWT
- Architecture
────────────────────────────────────────────────────────────
# Recherche sémantique (embeddings)
SUMMARY: Recherche de mémoire conceptuelle utilisant des embeddings vectoriels — trouver par signification, pas seulement par mots-clés.
Recherche sémantique (embeddings)
Synapse prend en charge la recherche sémantique utilisant des embeddings vectoriels.
Contrairement à FTS5 (correspondance par mots-clés), la recherche sémantique trouve
les mémoires par signification — même si aucun mot-clé ne correspond.
Comment ça marche
[CODE BLOCK]
Que sont les embeddings ?
Les embeddings sont des représentations vectorielles numériques du texte. Le texte
avec une signification similaire a des vecteurs similaires. Synapse génère un vecteur
(ex. 1536 dimensions) pour le contenu de chaque mémoire.
Similarité cosinus
Pour trouver les mémoires sémantiquement similaires, Synapse calcule la similarité
cosinus entre le vecteur de requête et chaque vecteur de mémoire. Similarité plus
élevée = plus pertinent.
Quand utiliser la recherche sémantique
Utilisez la recherche sémantique quand :
- Vous voulez « des mémoires sur X » où X est décrit différemment que stocké
- FTS5 ne renvoie aucun résultat (aucune correspondance de mot-clé)
- Vous voulez un regroupement conceptuel (ex. toutes les mémoires « deployment », même si certaines disent « release »)
- La requête est une question : « comment gérons-nous l'authentification ? »
Utilisez FTS5 quand :
- Vous connaissez les mots-clés exacts
- Vous avez besoin de logique booléenne (AND, OR, NOT)
- Vous avez besoin d'une réponse sub-milliseconde
- Vous voulez la correspondance de phrase
Endpoint
GET /memory/semantic-search
[CODE BLOCK]
Réponse :
[CODE BLOCK]
Exemples
Trouver les mémoires de déploiement
[CODE BLOCK]
Renvoie les mémoires sur « deployment », « release », « publishing », « rolling out »,
etc.
Trouver les schémas d'authentification
[CODE BLOCK]
Renvoie les mémoires sur le login, l'auth, le JWT, la gestion de session, OAuth, etc.
Trouver des mémoires similaires
[CODE BLOCK]
Utilise la similarité sémantique (via tags partagés ET vecteurs d'embedding).
Génération d'embeddings
Quand les embeddings sont-ils générés ?
- Au stockage de mémoire — si le service d'embeddings est configuré, l'embedding est généré de manière synchrone
- Génération par lot — génère des embeddings pour les mémoires qui en manquent
- Mises à jour asynchrones — quand le contenu est mis à jour, l'embedding est régénéré
Fournisseurs d'embeddings
Synapse prend en charge des fournisseurs d'embeddings configurables :
- OpenAI (, )
- Modèles locaux (via Ollama ou similaire)
- Personnalisé (implémentez l'interface embeddings)
Configurez via des variables d'environnement :
[CODE BLOCK]
Génération par lot
Pour les minds avec beaucoup de mémoires sans embeddings :
[CODE BLOCK]
Performance
| Opération | Latence |
|-----------|---------|
| Génération d'embedding (OpenAI) | 100-200 ms |
| Recherche sémantique (1k mémoires) | 50-100 ms |
| Recherche sémantique (10k mémoires) | 200-500 ms |
| Génération par lot (100 mémoires) | 10-20 s |
> [!NOTE]
> La recherche sémantique est plus lente que FTS5 en raison du calcul vectoriel.
> Utilisez FTS5 pour les mots-clés connus, sémantique pour les requêtes conceptuelles.
Limites
Coût des embeddings
Si vous utilisez OpenAI, générer des embeddings coûte de l'argent (0,02 $ par 1M
tokens pour text-embedding-3-small). Pour 10 000 mémoires de 100 tokens en moyenne,
cela représente 0,02 $ — négligeable.
Démarrage à froid
Les mémoires stockées avant la configuration des embeddings n'en auront pas. Exécutez
pour les rétroalimenter.
Dépendance au fournisseur
Si le fournisseur d'embeddings est en panne, la recherche sémantique échoue
gracieusement (renvoie des résultats vides ou une erreur). FTS5 fonctionne toujours.
Quand les embeddings ne sont pas disponibles
Si le service d'embeddings n'est pas configuré :
- renvoie 503 Service Unavailable
- fonctionne toujours (simplement aucun embedding généré)
- La recherche FTS5 fonctionne toujours
Bonnes pratiques
> [!TIP]
> - Utilisez sémantique pour les requêtes conceptuelles — « comment gérons-nous X ? »
> - Utilisez FTS5 pour les termes spécifiques — « docker swarm »
> - Rétroalimentez les embeddings régulièrement —
> - Surveillez la santé du fournisseur — la recherche sémantique en dépend
> - Combinez avec les tags — sémantique + filtre de tag affine les résultats
Prochaines étapes
- Recherche FTS5
- API Memory
- Architecture
## CATÉGORIE : LIVRE DE RECETTES LLM
Recettes et motifs pour les agents LLM.
────────────────────────────────────────────────────────────
# Schéma de polling de chat
SUMMARY: Comment polliner les messages humains entre les appels d'outils sans bloquer votre workflow.
Schéma de polling de chat
Le système de chat est asynchrone — les humains peuvent laisser des messages pendant
que vous travaillez. Ce schéma montre comment polliner les messages sans bloquer
votre workflow.
Le schéma
[CODE BLOCK]
Pollinez entre les appels d'outils, pas dans une boucle serrée.
Pourquoi polliner entre les appels d'outils ?
- Ne pas bloquer — le polling en boucle serrée gaspille les appels d'API
- Ne pas manquer de messages — le polling trop peu fréquent signifie des réponses lentes
- Sweet spot — pollinez toutes les 30-60 secondes, ou après chaque appel d'outil
Implémentation
Polling de base
[CODE BLOCK]
Schéma 1 : polliner après chaque appel d'outil
[CODE BLOCK]
Schéma 2 : polling basé sur le temps
[CODE BLOCK]
Schéma 3 : piloté par événements (avec webhooks)
Pour une notification en temps réel, enregistrez un webhook :
[CODE BLOCK]
Puis votre gestionnaire de webhook peut réveiller l'agent :
[CODE BLOCK]
Schémas de gestion des messages
Schéma : accuser réception puis traiter
[CODE BLOCK]
Schéma : file pour traitement par lot
[CODE BLOCK]
Schéma : routage par priorité
[CODE BLOCK]
Fréquence de polling
| Cas d'usage | Fréquence |
|----------|-----------|
| Agent interactif (humain en attente) | Toutes les 5-10 secondes |
| Agent en arrière-plan | Toutes les 30-60 secondes |
| Traitement par lot | Toutes les 5 minutes |
| Piloté par webhook | Ne pas polliner — utilisez des webhooks |
> [!WARNING]
> Polliner plus d'une fois toutes les 5 secondes gaspille des appels d'API. L'endpoint
> renvoie immédiatement si des messages sont en attente, donc il n'y a
> aucun bénéfice à un polling plus rapide.
Chat multi-agent
Pour la communication agent-à-agent :
[CODE BLOCK]
Bonnes pratiques
> [!TIP]
> - Pollinez entre les appels d'outils — pas dans une boucle serrée
> - Accusez réception immédiatement — l'humain sait que vous avez reçu le message
> - Traitez de manière asynchrone — ne bloquez pas sur un travail long
> - Utilisez les webhooks pour le temps réel — le polling a de la latence
> - Ne pollinez pas plus d'une fois toutes les 5 secondes — gaspille des appels d'API
Problèmes courants
Messages qui disparaissent
- marque automatiquement les messages comme lus
- Si vous ne les traitez pas, ils sont perdus
- Correction : Traitez toujours les messages avant de revenir
Réponses en double
- Si votre gestionnaire plante, vous pourriez répondre deux fois
- Correction : Rendez le gestionnaire idempotent (vérifiez si déjà répondu)
Réponses lentes
- Le polling toutes les 60 s signifie jusqu'à 60 s de latence
- Correction : Pollinez toutes les 10-30 s, ou utilisez les webhooks
Prochaines étapes
- API Chat
- Schéma de début de session
- Récupération d'erreurs
────────────────────────────────────────────────────────────
# Récupération d'erreurs pour les agents
SUMMARY: Comment les agents LLM devraient gérer et se remettre des erreurs — réessayer, stocker, apprendre.
Récupération d'erreurs pour les agents
Les erreurs arrivent. Les réseaux tombent, les API renvoient des 500, les Mind Keys
expirent. Ce guide montre comment les agents LLM devraient gérer les erreurs
gracieusement et en tirer des leçons.
Principes de gestion des erreurs
1. Réessayer avec backoff — les erreurs transitoires se résolvent souvent
2. Stocker l'erreur — apprendre des schémas
3. Dégrader gracieusement — ne pas crasher toute la session
4. Notifier l'humain — pour les erreurs que vous ne pouvez pas résoudre
Gestion des erreurs HTTP
Réessayer avec backoff exponentiel
[CODE BLOCK]
Gestion des erreurs d'auth
[CODE BLOCK]
Stocker les erreurs en mémoire
Quand des erreurs se produisent, stockez-les pour que les futures sessions puissent
apprendre :
[CODE BLOCK]
Scénarios d'erreur courants
Scénario 1 : Mind Key invalide
[CODE BLOCK]
Scénario 2 : erreur réseau
[CODE BLOCK]
Scénario 3 : limité en débit
[CODE BLOCK]
Scénario 4 : erreur serveur (5xx)
[CODE BLOCK]
Scénario 5 : échec d'appel d'outil
[CODE BLOCK]
Schéma : disjoncteur
Pour les échecs répétés, arrêter d'essayer temporairement :
[CODE BLOCK]
Bonnes pratiques
> [!TIP]
> - Toujours réessayer les erreurs transitoires — les réseaux tombent, les serveurs hoquettent
> - Ne pas réessayer les erreurs client (4xx) — elles ne se corrigeront pas
> - Stocker les erreurs en mémoire — apprendre des schémas
> - Notifier les humains pour les erreurs critiques — ils doivent savoir
> - Dégrader gracieusement — un travail partiel vaut mieux qu'un crash
> - Utiliser des disjoncteurs — ne pas marteler un service défaillant
Prochaines étapes
- Référence API Erreurs
- Schéma de début de session
- Tests auto-réparables
────────────────────────────────────────────────────────────
# Stratégie de tagging mémoire
SUMMARY: Comment tagger les mémoires pour une recherche et un filtrage efficaces — le système de tagging qui passe à l'échelle.
Stratégie de tagging mémoire
Les tags sont le secret d'une récupération de mémoire qui passe à l'échelle. Ce guide
montre comment tagger les mémoires pour que les bonnes reviennent au bon moment.
Pourquoi les tags comptent
Sans tags, vous avez une recherche en texte intégral plate. Avec les tags, vous avez
une navigation structurée :
[CODE BLOCK]
Les tags permettent :
- Filtrage rapide —
- Recherche scopée —
- Regroupement — trouver toutes les mémoires « mistake » d'un projet
- Référencement croisé — les mémoires partageant des tags sont liées
Schéma de tagging
Tags de projet
Utilisez les noms de projet comme tags :
[CODE BLOCK]
Tags de technologie
Utilisez les noms de technologie :
[CODE BLOCK]
Tags de sujet
Utilisez les catégories de sujet :
[CODE BLOCK]
Tags de statut
Utilisez les indicateurs de statut :
[CODE BLOCK]
Tags de type
Utilisez les indicateurs de type :
[CODE BLOCK]
Règles de tagging
Règle 1 : 2-5 tags par mémoire
Trop peu de tags = mauvaise découvrabilité. Trop = du bruit.
[CODE BLOCK]
Règle 2 : minuscules, avec tirets
[CODE BLOCK]
Règle 3 : utiliser un vocabulaire cohérent
Établissez un vocabulaire de tagging et tenez-vous-y :
[CODE BLOCK]
Règle 4 : tagger avec intention de recherche
Demandez : « Comment vais-je rechercher cette mémoire ? »
[CODE BLOCK]
Schémas
Schéma 1 : projet + sujet
[CODE BLOCK]
Recherche : (toutes les mémoires du projet Synapse)
Recherche : (mémoires de déploiement dans Synapse)
Schéma 2 : type + domaine
[CODE BLOCK]
Recherche : (toutes les erreurs)
Recherche : (erreurs de déploiement)
Schéma 3 : hiérarchique
Pour les sous-projets au sein d'un projet :
[CODE BLOCK]
Recherche : (tout Synapse)
Recherche : (juste le sous-projet docs)
Schéma 4 : suivi de statut
[CODE BLOCK]
Cas d'usage courants
Trouver toutes les décisions sur un projet
[CODE BLOCK]
Trouver toutes les erreurs dans un domaine
[CODE BLOCK]
Trouver le travail actif
[CODE BLOCK]
Trouver des mémoires sur une technologie
[CODE BLOCK]
Maintenance des tags
Revue périodique
[CODE BLOCK]
Fusionner les tags
Si vous avez des tags incohérents ( et ), fusionnez-les :
[CODE BLOCK]
Bonnes pratiques
> [!TIP]
> - Établir le vocabulaire tôt — des tags cohérents dès le jour 1
> - Tagger avec intention de recherche — comment trouverez-vous cela plus tard ?
> - 2-5 tags est le sweet spot — trop peu ou trop est mauvais
> - Minuscules + tirets — pas
> - Revue périodique — fusionner les doublons, supprimer les inutilisés
Prochaines étapes
- Bonnes pratiques mémoire
- Recherche FTS5
- Workflow piloté par les tâches
────────────────────────────────────────────────────────────
# Schéma de début de session
SUMMARY: La séquence canonique de début de session que tout agent LLM devrait suivre.
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.
Schéma de début de session
Chaque session d'agent LLM devrait suivre cette séquence canonique de démarrage.
Sauter des étapes mène à un contexte perdu, des messages manqués et des tâches
oubliées.
Le schéma
[CODE BLOCK]
Implémentation
Étape 1 : rappeler toutes les mémoires
> [!CRITICAL]
> C'est l'appel le plus important. Sans lui, vous n'avez aucune mémoire des sessions
> passées.
[CODE BLOCK]
Renvoie un résumé en texte brut de toutes les mémoires, trié par priorité.
Étape 2 : polliner les messages chat non lus
[CODE BLOCK]
Renvoie les messages non lus de l'humain. Les marque automatiquement comme lus.
Étape 3 : vérifier les tâches en cours
[CODE BLOCK]
Renvoie les tâches sur lesquelles vous travailliez à la dernière session.
Étape 4 : construire le contexte
Combinez les trois réponses dans votre prompt système :
[CODE BLOCK]
Étape 5 : traiter les éléments en attente
[CODE BLOCK]
Exemple complet
[CODE BLOCK]
Erreurs courantes
> [!WARNING]
> - Sauter le rappel — vous commencez sans contexte, répétez les erreurs passées
> - Oublier de polliner le chat — les messages de l'humain restent sans réponse
> - Ignorer les tâches actives — le travail est oublié en cours d'exécution
> - Ne rien stocker — la session ne produit aucune valeur persistante
Variations
Schéma minimal (LLM à faible contexte)
Pour les LLM avec de petites fenêtres de contexte, sautez le rappel complet :
[CODE BLOCK]
Puis recherchez des sujets spécifiques au besoin :
[CODE BLOCK]
Schéma agressif (agents longue durée)
Pour les agents qui tournent pendant des heures, ajoutez un re-rappel périodique :
[CODE BLOCK]
Prochaines étapes
- Stratégie de tagging mémoire
- Workflow piloté par les tâches
- Schéma de polling de chat
────────────────────────────────────────────────────────────
# Workflow piloté par les tâches
SUMMARY: Utilisez les tâches Synapse pour piloter des workflows LLM multi-étapes qui survivent entre les sessions.
Workflow piloté par les tâches
Les tâches ne sont pas juste des todos — elles sont l'épine dorsale des workflows LLM
persistants. En créant des tâches pour le travail multi-étapes, vous garantissez la
continuité entre les sessions et fournissez des pistes d'audit de ce qui a été fait.
Pourquoi piloté par les tâches ?
Sans tâches :
- Le LLM commence chaque session incertain de ce qu'il faut faire
- Le travail multi-étapes est oublié en cours d'exécution
- Aucun enregistrement de ce qui a été fait
Avec des tâches :
- Le LLM reprend les tâches en cours immédiatement
- Le travail multi-étapes survit entre les sessions
- Piste d'audit intégrée de tout le travail
Le schéma
[CODE BLOCK]
Implémentation
Étape 1 : créer une tâche pour un travail multi-étapes
[CODE BLOCK]
Étape 2 : suivre la progression dans la description de tâche
[CODE BLOCK]
Étape 3 : reprendre entre les sessions
[CODE BLOCK]
Étape 4 : compléter et archiver
[CODE BLOCK]
Exemple complet : workflow de déploiement
[CODE BLOCK]
Hiérarchie de tâches
Pour le travail complexe, utilisez des relations parent-enfant :
[CODE BLOCK]
Recherchez les sous-tâches :
[CODE BLOCK]
Workflow de statut
[CODE BLOCK]
Pending
Tâche créée mais non commencée. À utiliser pour le travail planifié.
In Progress
En cours de traitement. Mettez à jour la description avec la progression.
Done
Terminée avec succès. La description devrait inclure un résumé.
Cancelled
Abandonnée. La description devrait inclure la raison.
Bonnes pratiques
> [!TIP]
> - Créez des tâches pour le travail multi-étapes — le travail mono-étape n'a pas besoin de tâche
> - Mettez à jour la description avec la progression — permet la reprise
> - Utilisez une priorité élevée pour le travail actif — apparaît dans le rappel
> - Complétez les tâches quand elles sont terminées — ne les laissez pas inprogress
> - Stockez les résumés de complétion en mémoire — référence longue durée
Schémas courants
Schéma : workflow de correction de bug
[CODE BLOCK]
Schéma : workflow de recherche
[CODE BLOCK]
Prochaines étapes
- Schéma de début de session
- Schéma de polling de chat
- Récupération d'erreurs
## CATÉGORIE : FAQ
Questions fréquentes et problèmes courants.
────────────────────────────────────────────────────────────
# FAQ API
SUMMARY: Questions courantes sur l'API — auth, limites de débit, gestion des erreurs, découverte d'endpoints.
FAQ API
Questions courantes sur l'API Synapse.
Comment m'authentifier ?
Deux méthodes :
1. Mind Key (pour les endpoints de données) :
2. JWT (pour les endpoints de compte) :
Ou via paramètre de requête (limite 60 req/min) :
Voir Authentification.
Quelle est la différence entre Mind Key et JWT ?
- Mind Key : limitée au tenant, n'expire jamais, pour les données memory/chat/tasks
- JWT : limitée à l'utilisateur, expire en 7 jours, pour la gestion compte/mind
Voir Mind Key vs JWT.
Pourquoi est-ce que je reçois 401 Unauthorized ?
Causes courantes :
1. En-tête manquant
2. Mind Key invalide (vérifiez qu'elle commence par )
3. Utilisation d'un JWT là où une Mind Key est requise (ou inversement)
4. La Mind Key a été révoquée
Correction : Vérifiez votre jeton. Voir Authentification.
Pourquoi est-ce que je reçois 404 Not Found ?
Vous avez utilisé un mauvais chemin d'endpoint. Synapse ne possède que les chemins
listés dans .
Correction : Appelez pour voir tous les chemins valides. Ne
devinez pas.
Pourquoi est-ce que je reçois 429 Too Many Requests ?
Vous utilisez l'authentification par paramètre de requête , qui est limitée à
60/min.
Correction : Passez à l'en-tête (sans limite de débit).
Voir Limites de débit.
Comment lister tous les endpoints ?
[CODE BLOCK]
Comment trouver le bon endpoint ?
1. Vérifiez pour la liste lisible par machine
2. Vérifiez pour la documentation complète de l'API
3. Parcourez pour le système de documentation
4. Utilisez pour la spécification OpenAPI 3.0
Puis-je utiliser GET au lieu de POST ?
Certains endpoints POST ont des équivalents GET pour les outils n'utilisant que des
URLs :
- ↔
- ↔
- ↔
Vérifiez pour les variantes GET disponibles.
Comment gérer les erreurs ?
Toutes les erreurs renvoient du JSON :
[CODE BLOCK]
Voir Erreurs & gestion des erreurs.
Quelle est la limite de corps de requête ?
10 Mo. Pour les payloads plus volumineux (ex. envoi de fichiers), utilisez les
endpoints multipart.
L'API prend-elle en charge CORS ?
Oui. Tous les endpoints renvoient :
[CODE BLOCK]
Y a-t-il un SDK ?
Oui :
- Node.js :
- MCP :
Voir Vue d'ensemble de l'API pour plus de détails.
Comment paginer ?
Utilisez et :
[CODE BLOCK]
Limite par défaut : 100. Max : 500.
Puis-je filtrer les mémoires par catégorie ou tag ?
Oui :
[CODE BLOCK]
Comment rechercher des mémoires ?
Deux façons :
1. Recherche par mots-clés FTS5 :
2. Recherche sémantique :
Voir Recherche FTS5 et Recherche sémantique.
Comment mettre à jour une mémoire ?
POST avec la même + — la mémoire existante est mise à
jour, pas dupliquée.
[CODE BLOCK]
Comment supprimer une mémoire ?
[CODE BLOCK]
Puis-je supprimer en masse ?
Oui :
[CODE BLOCK]
Prochaines étapes
- Vue d'ensemble de l'API
- Erreurs & gestion des erreurs
- Authentification
────────────────────────────────────────────────────────────
# FAQ générale
SUMMARY: Questions courantes sur Synapse — ce que c'est, comment ça marche, pour qui.
FAQ générale
Questions courantes sur Synapse.
Qu'est-ce que Synapse ?
Synapse est une API de mémoire persistante pour les agents LLM. Elle donne à votre
assistant IA un cerveau permanent et interrogeable qui survit entre les sessions. Au
lieu de tout oublier quand le chat se ferme, le LLM stocke et récupère des mémoires
via une simple API HTTP.
En savoir plus : Qu'est-ce que Synapse ?
Pour qui est Synapse ?
- Développeurs d'agents LLM qui ont besoin d'état persistant
- Utilisateurs avancés exécutant des LLM locaux avec des agents personnalisés
- Équipes construisant des assistants IA avec mémoire partagée
- Ingénieurs d'automatisation enchaînant des appels LLM entre sessions
Synapse est-il gratuit ?
Synapse est hébergé sur et gratuit pour un usage
personnel. Pour l'auto-hébergement, voir le dépôt.
En quoi Synapse diffère-t-il de la mémoire ChatGPT ?
| Fonctionnalité | Mémoire ChatGPT | Synapse |
|---------|---------------|---------|
| Stockage | Serveurs OpenAI | Votre serveur |
| Accès API | Non | Oui (REST + MCP) |
| Multi-tenant | Non | Oui (minds) |
| Catégories personnalisées | Non | Oui (8 catégories) |
| Recherche en texte intégral | Limité | FTS5 + sémantique |
| Auto-hébergeable | Non | Oui |
Quels LLM fonctionnent avec Synapse ?
N'importe quel LLM qui peut faire des appels HTTP ou utiliser MCP :
- Claude (Anthropic) — via MCP ou API directe
- GPT-4 / GPT-3.5 (OpenAI) — via function calling + API
- Gemini (Google) — via function calling + API
- Llama / Mistral (local) — via intégration personnalisée
- N'importe quel LLM via le serveur MCP Synapse
Dois-je héberger Synapse moi-même ?
Non. La version hébergée sur est disponible pour un
usage public. L'auto-hébergement est optionnel (pour la confidentialité, la
personnalisation ou les environnements isolés).
Combien de données puis-je stocker ?
Il n'y a pas de limites strictes sur la version hébergée. Usage typique :
- 100-1000 mémoires par mind
- 1-10 Ko par mémoire (champ content)
- Total : 10 Mo par mind
Pour une échelle supérieure, auto-hébergez.
Mes données sont-elles privées ?
Oui. Chaque mind est isolé (voir Multi-tenancy). Les
autres utilisateurs ne peuvent pas voir vos données. Le fournisseur d'hébergement
(Schäfer Services) y a accès mais ne consulte pas les données utilisateur.
Pour une confidentialité maximale, auto-hébergez.
Puis-je exporter mes données ?
Oui. Utilisez pour exporter toutes les mémoires en JSON.
Voir Sauvegarde & restauration.
Que se passe-t-il si je perds ma Mind Key ?
Les Mind Keys ne sont affichées qu'une fois à la création. Si perdue :
1. Connectez-vous avec votre email/mot de passe pour obtenir un JWT
2. Créez un nouveau mind via
3. Sauvegardez la nouvelle Mind Key
4. (Optionnel) Supprimez l'ancien mind via
Vous ne pouvez pas récupérer les mémoires d'un mind dont la clé est perdue.
Plusieurs agents LLM peuvent-ils partager un mind ?
Oui. Tous les agents utilisant la même Mind Key partagent les données de ce mind. Pour
le travail multi-agent coordonné, voir Coordination multi-agent.
Synapse fonctionne-t-il hors ligne ?
Non, Synapse nécessite une connexion internet au serveur (hébergé ou auto-hébergé).
Pour les LLM hors ligne, exécutez Synapse localement.
Quelle est la vitesse de la recherche mémoire ?
- Recherche par mots-clés FTS5 : < 10 ms pour 1000 mémoires
- Recherche sémantique : 50-100 ms pour 1000 mémoires
- Rappel complet : < 50 ms pour 1000 mémoires
Voir Recherche FTS5 pour plus de détails.
Puis-je utiliser Synapse sans LLM ?
Oui. Synapse est une API de mémoire générique. Vous pouvez l'utiliser depuis
n'importe quelle application qui bénéficie d'un stockage clé-valeur persistant et
recherchable avec catégories et tags.
Prochaines étapes
- Qu'est-ce que Synapse ?
- Démarrage rapide
- FAQ API
────────────────────────────────────────────────────────────
# FAQ MCP
SUMMARY: Questions courantes sur l'intégration MCP — outils, transports, dépannage.
FAQ MCP
Questions courantes sur le serveur MCP Synapse.
Qu'est-ce que MCP ?
MCP (Model Context Protocol) est un standard ouvert d'Anthropic pour l'intégration
LLM-outil. Au lieu de coller la documentation de l'API dans les prompts, vous
enregistrez des outils auprès d'un serveur MCP, et le LLM les appelle comme des
fonctions natives.
Voir Qu'est-ce que MCP ?.
Combien d'outils le MCP Synapse expose-t-il ?
79 outils répartis en 12 catégories : memory, chat, scheduler, tasks, scripts,
computers, push, user, utility, visualization, sharing, webhooks, browser.
Voir Qu'est-ce que MCP ? pour la liste complète.
Quels clients MCP sont pris en charge ?
- Claude Desktop (macOS, Windows)
- Claude Code (terminal)
- Cursor (IDE)
- Continue.dev (VS Code, JetBrains)
- Cline (VS Code)
- Tout client compatible MCP
Voir Configuration Claude Desktop pour des exemples de
configuration.
Quels transports sont pris en charge ?
1. stdio (local, recommandé pour desktop)
2. HTTP/SSE (distant, multi-tenant)
3. WebSocket (mobile, haut volume)
Comment configurer Claude Desktop ?
Éditez :
[CODE BLOCK]
Voir Configuration Claude Desktop.
Pourquoi les outils n'apparaissent-ils pas dans Claude Desktop ?
1. Redémarrez Claude Desktop complètement (Cmd+Q sur macOS)
2. Vérifiez que le fichier de config est du JSON valide
3. Vérifiez Node.js 18+ installé
4. Consultez les logs MCP :
Voir Dépannage MCP.
Comment utiliser un mind différent ?
Changez dans votre config MCP et redémarrez le client.
Pour plusieurs minds, exécutez plusieurs instances du serveur MCP avec différentes
Mind Keys.
Puis-je limiter les outils exposés ?
Oui, utilisez les Tool Profiles :
- : 8 outils composites (500 tokens)
- : 25 outils (2 500 tokens)
- : 119 outils (8 250 tokens, par défaut)
Définissez via la variable d'environnement ou l'en-tête
.
Comment déboguer les problèmes MCP ?
1. Exécutez le serveur MCP manuellement :
2. Consultez les logs client (varie selon le client)
3. Vérifiez que la Mind Key fonctionne :
4. Vérifiez la santé de Synapse :
Voir Dépannage MCP.
Le serveur MCP est-il gratuit ?
Oui. Le paquet npm est open source. Le serveur MCP hébergé sur
est gratuit pour un usage public.
Puis-je auto-héberger le serveur MCP ?
Oui :
[CODE BLOCK]
En quoi MCP diffère-t-il des appels API directs ?
| Aspect | API directe | MCP |
|--------|-----------|-----|
| Le LLM doit connaître | URLs, en-têtes, auth | Juste les noms d'outils |
| Gestion de l'auth | Manuelle | Automatique (var d'env) |
| Découverte des outils | Lire /endpoints | Automatique via protocole MCP |
| Gestion des erreurs | Manuelle | Standardisée |
| Idéal pour | Intégrations personnalisées | Agents LLM |
Puis-je construire mon propre client MCP ?
Oui. Utilisez le SDK MCP officiel :
- TypeScript :
- Python :
Voir Client MCP personnalisé.
Comment signaler des bugs MCP ?
Ouvrez un ticket :
Incluez :
- Version du serveur MCP
- Nom et version du client
- Système d'exploitation
- Logs pertinents
- Étapes pour reproduire
Prochaines étapes
- Qu'est-ce que MCP ?
- Configuration Claude Desktop
- Dépannage MCP
────────────────────────────────────────────────────────────
# FAQ dépannage
SUMMARY: Solutions aux problèmes courants de Synapse — auth, réseau, données, déploiement.
FAQ dépannage
Solutions aux problèmes courants de Synapse.
Je ne peux pas me connecter
Symptômes
- renvoie 401
- "Invalid email or password"
Solutions
1. Vérifiez que l'email est correct — sensible à la casse
2. Vérifiez le mot de passe — minimum 6 caractères
3. Inscrivez-vous d'abord si vous n'avez pas de compte :
4. Réinitialisez le mot de passe (si SMTP configuré) via l'interface web
J'ai perdu ma Mind Key
Symptômes
- Impossible d'accéder aux mémoires
- La Mind Key a été supprimée/perdue
Solutions
Les Mind Keys ne peuvent pas être récupérées. Vous devez :
1. Vous connecter pour obtenir un JWT :
2. Lister les minds : (avec JWT)
3. Créer un nouveau mind :
4. Sauvegarder la nouvelle Mind Key
5. (Optionnel) Supprimer l'ancien mind :
Les données dans l'ancien mind sont perdues sauf si vous retrouvez la Mind Key.
Les appels API renvoient 401
Symptômes
- Tous les appels API renvoient 401 Unauthorized
- "Mind Key fehlt oder ungültig"
Solutions
1. Vérifiez le format de l'en-tête :
2. Vérifiez que la Mind Key commence par (pas qui est un JWT)
3. Testez directement :
[CODE BLOCK]
4. La Mind Key est peut-être révoquée — créez un nouveau mind
Voir Authentification.
Les appels API renvoient 404
Symptômes
- 404 Not Found
- "Route not found"
Solutions
> [!CRITICAL]
> Ne devinez pas les chemins d'endpoints. Seuls les chemins dans
> existent.
1. Vérifiez les endpoints valides :
2. Comparez l'URL exactement — sensible à la casse, pas de barre oblique finale
3. Vérifiez la méthode HTTP — vs sont différents
Les appels API renvoient 429
Symptômes
- 429 Too Many Requests
- "Rate limit exceeded"
Solutions
1. Passez à l'auth par en-tête (sans limite de débit) :
[CODE BLOCK]
2. Attendez secondes si vous devez utiliser
Voir Limites de débit.
La recherche mémoire ne renvoie aucun résultat
Symptômes
- renvoie vide
- Vous savez que des mémoires existent
Solutions
1. Vérifiez que les mémoires existent :
2. Vérifiez la syntaxe de recherche — FTS5 a une syntaxe spécifique
3. Essayez une requête plus simple — au lieu de
4. Utilisez la recherche sémantique pour les requêtes conceptuelles :
Voir Recherche FTS5.
Les mémoires ne persistent pas
Symptômes
- POST /memory renvoie un succès
- GET /memory/recall ne les affiche pas
Solutions
1. Vérifiez que vous utilisez la même Mind Key — des clés différentes = des minds différents
2. Vérifiez la réponse — POST renvoie
3. Essayez GET /memory (liste JSON) au lieu de /memory/recall (texte)
4. Vérifiez le filtre — ou peut les masquer
Les outils n'apparaissent pas dans Claude Desktop
Symptômes
- Claude Desktop affiche 0 outils
- Pas d'icône 🔌
Solutions
1. Redémarrez Claude Desktop complètement (Cmd+Q)
2. Vérifiez que le fichier de config est du JSON valide
3. Vérifiez Node.js 18+ installé
4. Exécutez MCP manuellement :
5. Consultez les logs :
Voir Dépannage MCP.
Synapse est hors ligne
Symptômes
- Impossible d'atteindre synapse.schaefer.zone
- curl expire
Solutions
1. Vérifiez votre internet — essayez un autre site
2. Vérifiez la santé de Synapse :
3. Attendez — peut être une panne temporaire ou un déploiement
4. Vérifiez la page de statut (si disponible)
Pour l'auto-hébergement : vérifiez le statut du conteneur Docker, la connexion à la
base de données.
Erreurs de base de données
Symptômes
- 500 Internal Server Error
- "Database connection failed"
Solutions
Pour l'auto-hébergement :
1. Vérifiez que PostgreSQL fonctionne :
2. Vérifiez DATABASEURL dans l'environnement
3. Vérifiez les migrations :
4. Vérifiez l'espace disque :
Pour l'hébergement : signalez au support.
Le webhook ne se déclenche pas
Symptômes
- Webhook enregistré mais pas de rappels reçus
- Pas de POST vers votre URL
Solutions
1. Vérifiez que l'URL est accessible :
2. Vérifiez le filtre d'événements — correspond à tous les événements de mémoire
3. Testez le webhook :
4. Vérifiez que le webhook est activé :
5. Vérifiez le SSL — Synapse requiert un HTTPS valide pour les URLs de webhook
Voir API Webhooks.
La tâche cron ne s'exécute pas
Symptômes
- Tâche cron créée mais ne se déclenche pas
- ne se met pas à jour
Solutions
1. Vérifiez la syntaxe de planification — doit être un cron à 5 champs valide OU un entier en secondes
2. Vérifiez que l'endpoint est autorisé — doit être http(s), pas d'IP privées
3. Vérifiez que la tâche est activée :
4. Attendez la prochaine heure planifiée — cron n'est pas instantané
Voir Cron & Scheduler.
Besoin d'aide supplémentaire ?
1. Consultez la documentation existante :
2. Recherchez dans les docs :
3. Ouvrez un ticket :
4. Contact : voir la page
Prochaines étapes
- Erreurs & gestion des erreurs
- FAQ API
- Dépannage MCP