# 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 `GET /memory/recall` 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 |
|----------|----------|
| `identity` | Nom de l'utilisateur, rôle, infos de contact, préférences sur soi |
| `preference` | Goûts, aversions, style de travail, préférences de communication |
| `fact` | Faits vérifiables (détails de projet, dates, URLs) |
| `project` | Statut de projet, jalons, architecture |
| `skill` | Choses dont l'utilisateur est bon |
| `mistake` | Erreurs passées — à éviter de répéter |
| `context` | Contexte pertinent à la session |
| `note` | Notes diverses |

## Priorités

- `low` — utile de savoir
- `normal` — par défaut
- `high` — important
- `critical` — à 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.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/recall
```

Réponse (text/plain) :

```
Mind: Michael's Mind
Memories: 12 total (10 verified)

[001] identity (CRITICAL)
  user_name
  Michael Schäfer
  Tags: person, identity

...
```

### POST /memory

Stocke une nouvelle mémoire ou met à jour une mémoire existante (même catégorie +
clé = mise à jour).

```bash
curl -X POST https://synapse.schaefer.zone/memory \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "fact",
    "key": "user_name",
    "content": "The user's name is Michael Schäfer",
    "tags": ["person", "identity"],
    "priority": "critical"
  }'
```

Réponse : `{ "id": "mem_001", "status": "stored" }`

### GET /memory

Liste les mémoires avec filtres optionnels.

```bash
# Toutes les mémoires (JSON)
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory?limit=50&offset=0"

# Filtrer par catégorie
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory?category=project"

# Filtrer par tag
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory?tag=docker"
```

### PUT /memory/:id

Met à jour une mémoire spécifique par ID.

```bash
curl -X PUT https://synapse.schaefer.zone/memory/mem_001 \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "Updated content", "priority": "high"}'
```

### DELETE /memory/:id

Supprime une seule mémoire.

```bash
curl -X DELETE -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/mem_001
```

## Endpoints de recherche

### GET /memory/search

Recherche en texte intégral utilisant FTS5.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/search?q=docker+swarm"
```

Syntaxe FTS5 :

- Plusieurs mots = AND : `docker swarm`
- Phrase : `"docker swarm"`
- Préfixe : `docker*`
- Booléen : `docker OR kubernetes`
- Exclusion : `docker -swarm`

### GET /memory/semantic-search

Recherche conceptuelle utilisant des embeddings (plus lente que FTS5 mais comprend
le sens).

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/semantic-search?q=container+orchestration"
```

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.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/by-tag?tag=docker
```

### GET /memory/related/:id

Trouve les mémoires liées à une mémoire spécifique (via des tags partagés).

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/related/mem_001
```

## Sync & Diff

### GET /memory/diff

Synchronisation incrémentale — renvoie les mémoires modifiées depuis un horodatage.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/diff?since=1700000000"
```

Réponse : `{ "added": [...], "updated": [...], "deleted": [...] }`

### POST /memory/sync

Applique un diff depuis une autre instance (pour la synchronisation auto-hébergée).

```bash
curl -X POST https://synapse.schaefer.zone/memory/sync \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"added": [...], "updated": [...], "deleted": [...]}'
```

## Opérations en masse

### POST /memory/bulk-delete

Supprime plusieurs mémoires par ID.

```bash
curl -X POST https://synapse.schaefer.zone/memory/bulk-delete \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ids": ["mem_001", "mem_002", "mem_003"]}'
```

### POST /memory/embed-batch

Génère des embeddings pour les mémoires qui n'en ont pas encore (pour la recherche
sémantique).

```bash
curl -X POST https://synapse.schaefer.zone/memory/embed-batch \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit": 100}'
```

### GET /memory/embed-batch-status

Vérifie la progression de la génération d'embeddings.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/embed-batch-status
```

## Vérification

Les mémoires ont un indicateur `verified`. Les mémoires stockées par l'agent sont non
vérifiées par défaut (`source=agent`) ; les mémoires stockées par l'humain sont
vérifiées (`source=user`).

### POST /memory/verify

Marque une mémoire comme vérifiée (nécessite un JWT, pas une Mind Key).

```bash
curl -X POST https://synapse.schaefer.zone/memory/mem_001/verify \
  -H "Authorization: Bearer YOUR_JWT"
```

### POST /memory/unverify

Marque une mémoire comme non vérifiée (nécessite un JWT).

```bash
curl -X POST https://synapse.schaefer.zone/memory/mem_001/unverify \
  -H "Authorization: Bearer YOUR_JWT"
```

### GET /memory/unverified

Liste les mémoires en attente de vérification humaine.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/unverified?limit=100"
```

## Statistiques & Audit

### GET /memory/stats

Statistiques agrégées pour le mind courant.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/stats
```

Renvoie : `{ "total": 12, "verified": 10, "unverified": 2, "by_category": {...}, "by_priority": {...} }`

### GET /memory/audit

Journal d'audit de toutes les opérations modifiant l'état.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/audit?limit=100&action=store"
```

### GET /memory/contradictions

Détecte les contradictions potentielles dans les mémoires stockées.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/contradictions
```

### GET /memory/expiring

Liste les mémoires dont la date d'expiration approche.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/expiring?within=7d"
```

## Santé & Export

### GET /memory/health

Vérification rapide de la santé du système de mémoire.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/health
```

### GET /memory/mind-export

Export JSON complet de toutes les mémoires (pour sauvegarde).

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

### POST /memory/compact

Compacte les mémoires similaires (résumé automatique).

```bash
curl -X POST https://synapse.schaefer.zone/memory/compact \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"dry_run": true}'
```

## Prochaines étapes

- [Démarrage rapide pour les LLM](/docs/getting-started/quick-start-llm)
- [Bonnes pratiques mémoire](/docs/guides/memory-best-practices)
- [Recherche FTS5](/docs/concepts/fts5-search)
- [Recherche sémantique](/docs/concepts/semantic-search)