# Stratégie de tagging mémoire

Les tags sont le secret d'une récupération de mémoire qui passe à l'échelle. Ce guide
montre comment tagger les mémoires pour que les bonnes reviennent au bon moment.

## Pourquoi les tags comptent

Sans tags, vous avez une recherche en texte intégral plate. Avec les tags, vous avez
une navigation structurée :

```bash
# Sans tags : tout chercher
GET /memory/search?q=docker

# Avec tags : filtrer par projet + technologie
GET /memory/search?q=deployment&tag=synapse&tag=docker
```

Les tags permettent :

- **Filtrage rapide** — `GET /memory/by-tag?tag=production`
- **Recherche scopée** — `?q=auth&tag=project-x`
- **Regroupement** — trouver toutes les mémoires « mistake » d'un projet
- **Référencement croisé** — les mémoires partageant des tags sont liées

## Schéma de tagging

### Tags de projet

Utilisez les noms de projet comme tags :

```
synapse, synapse-mcp, synapse-chat, synapse-sdk
```

### Tags de technologie

Utilisez les noms de technologie :

```
docker, kubernetes, postgres, fastify, react, typescript
```

### Tags de sujet

Utilisez les catégories de sujet :

```
deployment, ci-cd, auth, database, frontend, backend, security
```

### Tags de statut

Utilisez les indicateurs de statut :

```
active, completed, blocked, deprecated
```

### Tags de type

Utilisez les indicateurs de type :

```
decision, mistake, pattern, reference, todo
```

## Règles de tagging

### Règle 1 : 2-5 tags par mémoire

Trop peu de tags = mauvaise découvrabilité. Trop = du bruit.

```json
// Bien : 3 tags pertinents
{ "tags": ["synapse", "deployment", "docker"] }

// Mal : 1 tag (trop étroit)
{ "tags": ["synapse"] }

// Mal : 10 tags (bruit)
{ "tags": ["synapse", "deployment", "docker", "vps1", "2026", "june", "ssh", "git", "main", "production"] }
```

### Règle 2 : minuscules, avec tirets

```
✅ ci-cd, api-key, mind-key
❌ CI-CD, APIKey, MindKey
```

### Règle 3 : utiliser un vocabulaire cohérent

Établissez un vocabulaire de tagging et tenez-vous-y :

```
# Vocabulaire de projet
synapse, synapse-mcp, synapse-chat

# PAS : synapse_project, synapseProject, SYNAPSE
```

### Règle 4 : tagger avec intention de recherche

Demandez : « Comment vais-je rechercher cette mémoire ? »

```json
// Stockage d'une décision de déploiement
{
  "content": "Decided to use Docker Swarm for Synapse deployment",
  "tags": ["synapse", "deployment", "docker", "swarm", "decision"]
}

// Vous chercherez probablement : ?q=docker+swarm ou ?tag=deployment
```

## Schémas

### Schéma 1 : projet + sujet

```json
{ "tags": ["synapse", "deployment"] }
{ "tags": ["synapse", "auth"] }
{ "tags": ["synapse-mcp", "tools"] }
```

Recherche : `?tag=synapse` (toutes les mémoires du projet Synapse)
Recherche : `?tag=synapse&q=deployment` (mémoires de déploiement dans Synapse)

### Schéma 2 : type + domaine

```json
{ "tags": ["mistake", "deployment"] }
{ "tags": ["decision", "database"] }
{ "tags": ["pattern", "auth"] }
```

Recherche : `?tag=mistake` (toutes les erreurs)
Recherche : `?tag=mistake&q=deployment` (erreurs de déploiement)

### Schéma 3 : hiérarchique

Pour les sous-projets au sein d'un projet :

```json
{ "tags": ["synapse", "synapse-docs", "markdown"] }
{ "tags": ["synapse", "synapse-mcp", "mcp"] }
{ "tags": ["synapse", "synapse-admin", "ui"] }
```

Recherche : `?tag=synapse` (tout Synapse)
Recherche : `?tag=synapse-docs` (juste le sous-projet docs)

### Schéma 4 : suivi de statut

```json
// Projet actif
{ "tags": ["synapse", "active"], "priority": "high" }

// Projet terminé
{ "tags": ["synapse-v1", "completed"], "priority": "low" }

// Bloqué
{ "tags": ["synapse-v2", "blocked"], "priority": "high" }
```

## Cas d'usage courants

### Trouver toutes les décisions sur un projet

```bash
curl -H "Authorization: Bearer $KEY" \
     ".../memory/search?q=decision&tag=synapse"
```

### Trouver toutes les erreurs dans un domaine

```bash
curl -H "Authorization: Bearer $KEY" \
     ".../memory/search?q=mistake&tag=deployment"
```

### Trouver le travail actif

```bash
curl -H "Authorization: Bearer $KEY" \
     ".../memory/by-tag?tag=active"
```

### Trouver des mémoires sur une technologie

```bash
curl -H "Authorization: Bearer $KEY" \
     ".../memory/search?q=postgres+performance&tag=database"
```

## Maintenance des tags

### Revue périodique

```python
# Trouver les tags rarement utilisés (candidats au nettoyage)
tags = requests.get(f"{URL}/memory/tags",
    headers={"Authorization": f"Bearer {KEY}"}).json()

for tag, count in tags.items():
    if count < 2:
        print(f"Rare tag: {tag} ({count} memories)")
```

### Fusionner les tags

Si vous avez des tags incohérents (`docker` et `Docker`), fusionnez-les :

```python
# Trouver toutes les mémoires avec le tag "Docker"
mems = requests.get(f"{URL}/memory/by-tag?tag=Docker",
    headers={"Authorization": f"Bearer {KEY}"}).json()

# Mettre à jour chacune pour utiliser "docker" à la place
for mem in mems["results"]:
    tags = [t.lower() for t in mem["tags"]]
    update_memory(mem["id"], tags=list(set(tags)))
```

## Bonnes pratiques

> [!TIP]
> - **Établir le vocabulaire tôt** — des tags cohérents dès le jour 1
> - **Tagger avec intention de recherche** — comment trouverez-vous cela plus tard ?
> - **2-5 tags est le sweet spot** — trop peu ou trop est mauvais
> - **Minuscules + tirets** — `ci-cd` pas `CI/CD`
> - **Revue périodique** — fusionner les doublons, supprimer les inutilisés

## Prochaines étapes

- [Bonnes pratiques mémoire](/docs/guides/memory-best-practices)
- [Recherche FTS5](/docs/concepts/fts5-search)
- [Workflow piloté par les tâches](/docs/llm-cookbook/task-driven-workflow)