# 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 `GET /memory/recall` 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)

```
GET /memory/recall
Authorization: Bearer YOUR_MIND_KEY
```

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 :

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

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

[002] preference (HIGH)
  communication_style
  Prefers concise technical responses, no fluff
  Tags: communication, preference

[003] project (HIGH)
  project_synapse
  Synapse v1.5.0 deployed on vps1.schaefer.zone. Admin panel at /admin.
  Tags: synapse, deployment
  ...
```

## Étape 2 : stocker une nouvelle mémoire

Quand vous apprenez quelque chose qui mérite d'être retenu :

```
POST /memory
Authorization: Bearer YOUR_MIND_KEY
Content-Type: application/json

{
  "category": "fact",
  "key": "user_name",
  "content": "The user's name is Michael Schäfer",
  "tags": ["person", "identity"],
  "priority": "critical"
}
```

**Catégories :** `identity`, `preference`, `fact`, `project`, `skill`, `mistake`, `context`, `note`, `credentials`

**Priorités :** `low`, `normal`, `high`, `critical`

> [!TIP]
> Incluez toujours un champ `key` — 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

```
GET /memory/search?q=Docker+Swarm
Authorization: Bearer YOUR_MIND_KEY
```

> [!TIP]
> Syntaxe FTS5 : plusieurs mots = recherche AND. Phrases entre guillemets :
> `"docker swarm"`. Recherche par préfixe : `docker*`. Booléen : `docker OR kubernetes`.

## 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 `?key=` :

```
GET /memory/recall?key=YOUR_MIND_KEY
POST /memory?key=YOUR_MIND_KEY (+ JSON body)
GET /memory/search?key=YOUR_MIND_KEY&q=suchbegriff
```

> [!WARNING]
> `?key=` 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 :** `GET /memory/recall` — charger toutes les mémoires
2. **Pendant le travail :** `GET /memory/search?q=...` — trouver des faits spécifiques
3. **Sur nouvelle info :** `POST /memory` — la stocker (avec catégorie, clé, tags, priorité)
4. **Périodiquement :** `GET /chat/poll` — vérifier les messages humains
5. **Fin de session :** Stocker tout apprentissage final via `POST /memory`

## Schémas courants

### Mettre à jour une mémoire existante

POST `/memory` avec la même `category` et `key` — la mémoire existante est mise à
jour, pas dupliquée.

### Stocker un statut de projet

```json
{
  "category": "project",
  "key": "project_synapse_status",
  "content": "Synapse v1.5.0 deployed. Next: v1.6.0 with docs system. CI green.",
  "tags": ["synapse", "deployment", "status"],
  "priority": "high"
}
```

### Enregistrer une erreur (pour ne pas la répéter)

```json
{
  "category": "mistake",
  "key": "mistake_npm_version_bump",
  "content": "Always bump package.json version after changes — npm publish fails otherwise.",
  "tags": ["npm", "ci", "deployment"],
  "priority": "high"
}
```

### Vérifier les messages humains

```
GET /chat/poll
Authorization: Bearer YOUR_MIND_KEY
```

Renvoie les messages non lus de l'humain. Répondez avec :

```
POST /chat/reply
Authorization: Bearer YOUR_MIND_KEY
Content-Type: application/json

{"content": "Got it! Working on it now."}
```

## Prochaines étapes

- [Authentification](/docs/getting-started/authentication) — Mind Key vs JWT
- [Référence API Memory](/docs/api/memory) — tous les 22 endpoints mémoire
- [API Chat](/docs/api/chat) — communication asynchrone avec les humains
- [Cookbook LLM](/docs/llm-cookbook/session-start-pattern) — schémas pratiques