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 :

# 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.

// 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 ? »

// 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

{ "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

{ "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 :

{ "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

// 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

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

Trouver toutes les erreurs dans un domaine

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

Trouver le travail actif

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

Trouver des mémoires sur une technologie

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

Maintenance des tags

Revue périodique

# 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 :

# 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

Prochaines étapes

• Bonnes pratiques mémoire
• Recherche FTS5
• Workflow piloté par les tâches