# 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 |
|----------|---------|---------|
| `identity` | Nom d'utilisateur, rôle, infos de contact | `"user_name": "Michael Schäfer"` |
| `preference` | Goûts, aversions, style de travail | `"communication": "Prefers concise responses"` |
| `fact` | Faits vérifiables | `"office_location": "Berlin, Germany"` |
| `project` | Statut de projet, décisions | `"project_synapse": "v1.5.0 deployed"` |
| `skill` | Compétences de l'utilisateur | `"skill_python": "Advanced, 10+ years"` |
| `mistake` | Erreurs passées à éviter | `"mistake_npm_version": "Always bump version"` |
| `context` | Contexte pertinent à la session | `"current_focus": "Working on docs system"` |
| `note` | Notes diverses | `"note_idea": "Try Redis for caching"` |

> [!TIP]
> En cas de doute, utilisez `fact` pour les infos vérifiables et `note` pour tout le
> reste. Ne sur-catégorisez pas — mieux vaut avoir un `fact` clair qu'un `context`
> confus.

## Clés : identifiants significatifs

Le champ `key` est l'identifiant de la mémoire. Utilisez des clés significatives et
stables :

**Bonnes clés :**
- `user_name`
- `project_synapse_status`
- `preference_communication_style`
- `mistake_npm_version_bump`

**Mauvaises clés :**
- `mem_001` (non significative)
- `temp` (non descriptive)
- `2026-06-27-note` (la date n'aide pas le rappel)

### Conventions de nommage des clés

- `snake_case` (minuscules avec tirets bas)
- Préfixez avec la catégorie : `preference_*`, `project_*`, `mistake_*`
- 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 :

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

### Schémas de tags

- **Noms de projet** : `synapse`, `synapse-mcp`, `synapse-chat`
- **Sujets** : `deployment`, `ci`, `database`, `auth`
- **Statut** : `active`, `completed`, `blocked`
- **Indicateurs de priorité** : `urgent`, `long-term`

> [!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 |
|----------|---------|---------------|
| `critical` | Identité utilisateur, infos légales, décisions irréversibles | ~5 % |
| `high` | Projets actifs, préférences importantes | ~20 % |
| `normal` | La plupart des faits, notes, contexte | ~65 % |
| `low` | Éphémère, utile à savoir | ~10 % |

> [!WARNING]
> Ne marquez pas tout `critical`. Si tout est critique, rien ne l'est. Réservez
> `critical` 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 `context` avec priorité basse)

## Mettre à jour les mémoires

POST `/memory` avec la même `category` + `key` met à jour la mémoire existante :

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

# Plus tard : mise à jour avec la même clé
store("project", "project_synapse_status", "v1.5.0 deployed. CI green.", priority="high")
```

> [!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

```
Create → Active → Stale → Archive → Delete
```

- **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 `low`, conserver pour référence historique
- **Delete** : DELETE /memory/:id quand plus pertinent

### Nettoyage périodique

```python
# Trouver les mémoires non mises à jour depuis 90 jours
old_memories = requests.get(
    f"{URL}/memory/search?q=*",
    headers={"Authorization": f"Bearer {KEY}"}
)

for mem in old_memories["results"]:
    if is_stale(mem, days=90):
        # Soit supprimer, soit abaisser la priorité
        if is_obsolete(mem):
            delete_memory(mem["id"])
        else:
            update_memory(mem["id"], priority="low")
```

## Schéma : héritage de mémoire

Pour un contexte hiérarchique (projet → sous-projet → tâche) :

```python
# Projet parent
store("project", "project_synapse", "Main Synapse project", 
      tags=["synapse", "parent"], priority="high")

# Sous-projet (les tags lient au parent)
store("project", "project_synapse_docs", "Docs system for Synapse",
      tags=["synapse", "docs", "synapse-parent"], priority="high")

# Tâche spécifique (les tags lient au sous-projet)
store("project", "task_docs_loader", "Implement docs-loader.ts",
      tags=["synapse", "docs", "task"], priority="normal")
```

Le LLM peut alors chercher `q=synapse+docs` 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 :

```python
store("fact", "decision_postgres_over_sqlite",
      "Chose PostgreSQL over SQLite for production. Reason: concurrent writes, "
      "FTS5 native support, better backup story. Date: 2026-06-15. Decided by: Michael.",
      tags=["decision", "database", "postgres", "sqlite"],
      priority="high")
```

## Schéma : évitement des erreurs

Stockez les erreurs avec des instructions d'évitement spécifiques :

```python
store("mistake", "mistake_forget_version_bump",
      "Forgot to bump package.json version after changes. npm publish failed. "
      "FIX: Always run `npm version patch` before pushing. "
      "CI fails with 'version already exists' if you forget.",
      tags=["npm", "ci", "publish", "version"],
      priority="high")
```

## 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](/docs/api/memory)
- [Agent LLM persistant](/docs/guides/persistent-llm-agent)
- [Stratégie de tagging mémoire](/docs/llm-cookbook/memory-tagging-strategy)