# 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

```json
{
  "id": "mem_abc123",
  "category": "project",
  "key": "project_synapse_status",
  "content": "Synapse v1.5.0 deployed on vps1. CI green.",
  "tags": ["synapse", "deployment", "v1.5.0"],
  "priority": "high",
  "source": "agent",
  "verified": false,
  "confidence": 0.85,
  "expires_at": null,
  "mind_id": "m_xyz789",
  "created_at": "2026-06-27T...",
  "updated_at": "2026-06-27T..."
}
```

## Champs

| Champ | Type | Requis | Description |
|-------|------|----------|-------------|
| `id` | string | auto | Identifiant unique (mem_xxx) |
| `category` | enum | ✅ | Une des 8 catégories |
| `key` | string | ✅ | Identifiant stable (utilisé pour les mises à jour) |
| `content` | string | ✅ | Le contenu de la mémoire (n'importe quel texte) |
| `tags` | string[] | – | Pour la recherche et le filtrage |
| `priority` | enum | – | low, normal, high, critical (par défaut : normal) |
| `source` | enum | auto | user, agent (qui l'a stockée) |
| `verified` | bool | auto | Un humain a-t-il vérifié ceci ? |
| `confidence` | float | – | 0.0 à 1.0 (par défaut : 1.0 pour user, 0.7 pour agent) |
| `expires_at` | timestamp | – | Quand oublier cette mémoire |
| `mind_id` | string | auto | Quel mind possède ceci |
| `created_at` | timestamp | auto | Premier stockage |
| `updated_at` | 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 |
|----------|---------|-----------------|
| `identity` | Qui est l'utilisateur | "User is Michael Schäfer, software engineer in Berlin" |
| `preference` | Préférences utilisateur | "Prefers concise technical responses" |
| `fact` | Faits vérifiables | "Office is in Berlin, timezone Europe/Berlin" |
| `project` | Statut de projet | "Synapse v1.5.0 deployed, working on v1.6.0 docs" |
| `skill` | Compétences de l'utilisateur | "Advanced Python, 10+ years" |
| `mistake` | Erreurs passées | "Forgot to bump npm version — CI failed" |
| `context` | Contexte de session | "Currently reviewing PR #42" |
| `note` | Notes diverses | "Try Redis for caching next sprint" |

## Clés : identifiants stables

Le champ `key` est critique — c'est ainsi que vous mettez à jour les mémoires sans
créer de doublons.

```python
# Premier stockage
store("project", "project_synapse_status", "v1.4.0 deployed", priority="high")

# Mise à jour avec la même clé (écrase, ne duplique pas)
store("project", "project_synapse_status", "v1.5.0 deployed", priority="high")
```

**Règles de clé :**

- Doit être unique dans (catégorie, mind)
- Utilisez `snake_case`
- Préfixez avec la catégorie pour plus de clarté : `preference_communication`, `mistake_npm_version`
- 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 :

```bash
# Trouver toutes les mémoires avec le tag "docker"
GET /memory/by-tag?tag=docker

# Recherche FTS5 dans un sous-ensemble tagué
GET /memory/search?q=swarm&tag=docker
```

**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 |
|----------|-------------|-----------------|
| `critical` | Identité, juridique, irréversible | Toujours en haut du rappel |
| `high` | Projets actifs, préférences clés | Proéminent dans le rappel |
| `normal` | La plupart des mémoires (par défaut) | Ordre de rappel standard |
| `low` | Éphémère, utile à savoir | Peut être résumé |

`/memory/recall` trie par priorité (critical d'abord), puis par récence.

## Source : User vs Agent

Les mémoires sont marquées avec `source` :

- `user` — stockée par un humain (via JWT ou interface humaine)
- `agent` — stockée par un agent LLM (via Mind Key)

Cela affecte :

- **Vérification** : les mémoires `user` sont auto-vérifiées, les mémoires `agent` ne le sont pas
- **Confiance** : `user` par défaut à 1.0, `agent` à 0.7
- **Rappel** : `/memory/recall` marque les mémoires non vérifiées avec « (unverified) »

> [!NOTE]
> Traitez les mémoires `agent` 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 `verified` indique qu'un humain a confirmé la mémoire :

- Mémoires `user` : auto-vérifiées (`true`)
- Mémoires `agent` : non vérifiées par défaut (`false`)

Vérifiez les mémoires via :

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

> [!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 `confidence` (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 :

```json
{
  "category": "preference",
  "key": "prefers_dark_mode",
  "content": "User seems to prefer dark mode (based on their IDE screenshots)",
  "confidence": 0.5,
  "source": "agent"
}
```

## Expiration

Définissez `expires_at` pour les mémoires sensibles au temps :

```json
{
  "category": "context",
  "key": "current_meeting_topic",
  "content": "Discussing Q3 roadmap",
  "expires_at": "2026-06-28T00:00:00Z"
}
```

Les mémoires expirées ne sont pas renvoyées par `/memory/recall` (mais existent
toujours en base). Utilisez `/memory/expiring?within=7d` pour voir les mémoires
expirant bientôt.

## Cycle de vie d'une mémoire

```
                  ┌─────────────────┐
                  │     Create      │
                  │  POST /memory   │
                  └────────┬────────┘
                           │
                           ▼
                  ┌─────────────────┐
                  │     Active      │ ◀──── PUT /memory/:id (update)
                  │  (in recall)    │
                  └────────┬────────┘
                           │
              ┌────────────┼────────────┐
              │            │            │
              ▼            ▼            ▼
        ┌──────────┐ ┌──────────┐ ┌──────────┐
        │ Expired  │ │ Verified │ │ Deleted  │
        │ (in DB)  │ │ (flag)   │ │ (gone)   │
        └──────────┘ └──────────┘ └──────────┘
```

## Comportement de rappel

`GET /memory/recall` renvoie un résumé en texte brut optimisé pour le contexte LLM :

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

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

[002] preference (HIGH) [verified]
  communication_style
  Prefers concise technical responses
  Tags: communication

[003] project (HIGH) [unverified]
  synapse_status
  v1.5.0 deployed, working on v1.6.0 docs
  Tags: synapse, deployment

...
```

- Trié par priorité (critical → low), puis par récence
- Mémoires non vérifiées marquées avec `[unverified]`
- Tags inclus pour le contexte
- Texte brut (pas d'analyse JSON nécessaire)

## Prochaines étapes

- [API Memory](/docs/api/memory)
- [Bonnes pratiques mémoire](/docs/guides/memory-best-practices)
- [Recherche FTS5](/docs/concepts/fts5-search)