# 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