Memory System.fr

Système de mémoire (Graphiti)

Un des atouts majeurs de WorkPilot AI : les agents retiennent ce qu'ils apprennent d'une session à l'autre, grâce au moteur de mémoire graphe Graphiti.

---

🧠 Pourquoi une mémoire ?

Sans mémoire, chaque tâche part de zéro : l'agent redécouvre votre architecture, vos conventions, vos décisions passées… Cela coûte cher en tokens et produit des résultats incohérents entre tâches.

Avec Graphiti, les agents peuvent :

• Retrouver les décisions prises dans les specs précédentes (« nous avons choisi JWT, pas OAuth »)
• Connaître les conventions du projet (naming, structure, patterns)
• Comprendre les relations entre entités (quelle classe appelle quelle API)
• Se souvenir des rappels utilisateur (« n'utilise pas mock dans les tests d'intégration »)

---

🕸 C'est quoi un graphe sémantique ?

Graphiti stocke les connaissances comme un graphe orienté :

• Nœuds = entités (fichier, classe, fonction, concept, spec, décision)
• Arêtes = relations (importe, appelle, dépend de, remplace, contredit)
• Labels temporels = quand la connaissance a été acquise / est-elle toujours valable

Exemple simplifié :

[spec 001 "OAuth login"] ──(utilise)──▶ [fichier auth.py]
[spec 001]               ──(décision)──▶ [JWT over OAuth]
[fichier auth.py]        ──(appelé par)──▶ [fichier routes.py]
[spec 002 "Logout"]      ──(dépend de)──▶ [spec 001]

---

⚙️ Activation

Via l'UI (application de bureau)

1. Paramètres → Mémoire → Graphiti
2. Activez le toggle
3. Choisissez le fournisseur LLM pour la mémoire (souvent Claude ou GPT-4)
4. Choisissez le fournisseur d'embeddings (OpenAI, Voyage AI, Ollama, Google, OpenRouter)

Via les variables d'environnement (CLI)

# .env-files/.env
GRAPHITI_ENABLED=true
GRAPHITI_LLM_PROVIDER=anthropic   # ou openai, ollama, google, openrouter
GRAPHITI_EMBEDDER_PROVIDER=openai # ou voyage, ollama, google, openrouter

# Credentials du fournisseur (voir Fournisseurs-IA)
OPENAI_API_KEY=sk-xxx
# ou
ANTHROPIC_API_KEY=sk-ant-xxx

Vérifier l'état

python -c "from integrations.graphiti.client import check_connection; print(check_connection())"

---

🔄 Cycle de vie

Ingestion

À chaque fin de tâche, l'agent Memory Manager ingère :

• Les décisions prises (du spec + qa_report)
• Les fichiers touchés et leurs rôles
• Les commentaires humains (HUMAN_INPUT.md)
• Les observations du Coder (patterns repérés)

Requêtage

Quand une nouvelle spec démarre, le système interroge le graphe :

• « Quelles décisions passées concernent l'authentification ? »
• « Quel style de test préfère l'utilisateur ? »
• « Ce fichier a-t-il été modifié récemment pour une raison précise ? »

Les réponses sont injectées dans le contexte des agents, réduisant la redondance.

Oubli / invalidation

Certaines connaissances deviennent obsolètes (ex : décision révoquée dans une spec ultérieure). Graphiti gère l'invalidation temporelle : les nœuds périmés sont marqués et exclus des requêtes par défaut.

---

🔍 Questions typiques que Graphiti aide à répondre

Question	Ce que le graphe fournit
« Pourquoi ce fichier utilise-t-il un pattern singleton ? »	Spec 003 — performance — décision du 2025-10-12
« Quelles sont les conventions de nommage des endpoints ? »	« camelCase pour les handlers, kebab-case pour les routes » (spec 001)
« Quels modules dépendent d'auth.py ? »	routes.py, middleware.py, session.py
« Quelle lib de tests utilisons-nous ? »	« pytest + pytest-asyncio, interdiction de mocker la DB » (feedback humain)
« Quelles specs ont modifié ce fichier ? »	Specs 001, 005, 012 — avec dates et motifs

---

🧩 Architecture interne

Code : apps/backend/integrations/graphiti/

Composants :

• Client (client.py) — interface avec Graphiti core
• Ingester — transforme les events (spec completed, qa done) en nœuds/arêtes
• Retriever — requêtes sémantiques avec ranking
• Embedder — génération des embeddings pour chaque nœud
• Scheduler — tâches de maintenance (invalidation, compaction)

Graphiti lui-même s'appuie sur une base graphe (Neo4j ou alternatives compatibles) + un embedder + un LLM pour la résolution d'entités (ex : fusionner deux nœuds qui désignent la même chose).

---

🎚 Configuration avancée

Variable	Défaut	Description
GRAPHITI_ENABLED	true	Active/désactive le système
GRAPHITI_LLM_PROVIDER	anthropic	LLM pour résolution d'entités
GRAPHITI_EMBEDDER_PROVIDER	openai	Embedder (voyage recommandé pour le code)
GRAPHITI_DB_URI	local	URI de la base graphe
GRAPHITI_INGEST_BATCH_SIZE	50	Taille de batch à l'ingestion
GRAPHITI_MAX_RETRIEVAL	20	Nombre max de nœuds récupérés par requête

Consultez .env-files/.env.example pour la liste complète.

---

💬 Comparaison avec d'autres approches

Approche	Forces	Faiblesses
Graphiti (WorkPilot AI)	Relations explicites, invalidation temporelle, requêtes sémantiques	Nécessite un embedder + LLM
Fichier markdown (CLAUDE.md)	Simple, versionné dans git	Pas de recherche sémantique, vite trop long
Vector DB plate	Recherche sémantique rapide	Pas de relations, pas d'historique
Fine-tuning	Très performant	Coûteux, pas temps réel, perte de flexibilité

Graphiti combine le meilleur de la recherche vectorielle et du graphe de connaissances.

---

🔐 Données stockées et vie privée

• Par défaut, Graphiti est 100 % local (base graphe + embeddings sur votre machine)
• Seuls les appels LLM pour la résolution d'entités passent par votre fournisseur (Claude / OpenAI / local)
• Aucune donnée n'est envoyée à Anthropic / OpenAI au-delà de ce qui est strictement nécessaire à la résolution
• Pour garantir le zéro cloud, utilisez un LLM local (Ollama) et un embedder local

---

🧹 Maintenance

Recalculer les embeddings

Utile après un changement de fournisseur d'embeddings :

python -m integrations.graphiti.maintenance --rebuild-embeddings

Compaction

Supprime les nœuds obsolètes et défragmente :

python -m integrations.graphiti.maintenance --compact

Export / Import

# Export
python -m integrations.graphiti.maintenance --export backup.json

# Import (ex : migration de machine)
python -m integrations.graphiti.maintenance --import backup.json

---

🐞 Dépannage

Problème	Solution
Les agents « oublient » des décisions	Vérifiez GRAPHITI_ENABLED=true et check_connection()
Ingestion lente	Réduire GRAPHITI_INGEST_BATCH_SIZE, changer d'embedder
Réponses incohérentes	Lancer une compaction (--compact)
Erreur d'auth LLM	Vérifier les credentials du fournisseur Graphiti

---

Prochaine étape

➡️ Architecture technique