Guide

La mémoire dans LangGraph, threads et store durable

La mémoire dans LangGraph : checkpoints par thread, store entre threads, PostgresSaver, identifiant de thread, concurrence, time travel et alternatives externes.

L'équipe CodeWorlds13 min de lecture ·

Pratique Python dans des leçons interactives avec un éditeur de code.

Crée un compte gratuit→
Dans cet article11

LangGraph sépare la mémoire d'un agent en deux couches qui résolvent des problèmes différents et qu'on confond : les checkpoints liés à un thread, et un store qui opère entre les threads. La version actuelle est la 1.2.10, sous licence MIT, avec Python 3.10 minimum requis.

Comprendre cette séparation est en pratique tout le contenu de ce texte, car presque tous les problèmes de mémoire de cette bibliothèque viennent de l'usage d'une couche là où l'autre était nécessaire.

Deux couches et ce que fait chacune

Un checkpoint enregistre l'état du graphe et appartient à un thread. Un thread est une conversation ou une tâche, identifiée par un identifiant fourni lors de l'appel.

Un store durable contient des données destinées à survivre à une seule conversation, identifiées par un namespace, généralement lié à un utilisateur. La même personne qui revient dans un nouveau thread accède toujours à ce qui y a été stocké.

Les symptômes de la confusion sont caractéristiques et valent la peine d'être connus.

Si un utilisateur revient après une semaine, commence une nouvelle conversation et que l'agent ne se souvient pas de ses préférences, c'est que tu les stockais dans l'état du graphe. L'état appartient à un thread, et le thread est nouveau.

Dans le cas inverse, une conversation qui ne reprend pas là où elle avait été interrompue, soit aucun checkpoint n'existe, soit tu fournis un identifiant de thread différent de celui d'avant.

Une application typique a besoin des deux couches à la fois, et c'est le bon arrangement plutôt qu'un compromis. Les checkpoints portent le déroulement de la conversation en cours ; le store contient ce que l'on sait de la personne.

Les checkpoints en pratique

Python
from langgraph.checkpoint.postgres import PostgresSaver
from langgraph.graph import StateGraph

with PostgresSaver.from_conn_string(CONNECTION) as saver:
    saver.setup()
    graph = builder.compile(checkpointer=saver)

    result = graph.invoke(
        {"messages": [{"role": "user", "content": "let us continue"}]},
        config={"configurable": {"thread_id": "conversation-123"}},
    )

L'identifiant de thread est la seule chose qui décide de la continuité ici. En fournir le même reprend depuis le dernier état enregistré ; en fournir un nouveau repart de zéro.

Ce qui compte, c'est que l'écriture a lieu après chaque étape du graphe plutôt qu'à la fin d'un appel. Trois conséquences en découlent, toutes à connaître.

La première est la tolérance aux pannes. Un processus mort en plein traitement reprend après le redémarrage à partir de la dernière étape enregistrée au lieu de recommencer.

La deuxième est la possibilité de mettre un graphe en pause pour attendre une décision humaine. Le graphe s'arrête avant une étape choisie, l'état est enregistré, et la reprise peut avoir lieu dans une heure ou dans deux jours.

La troisième est la taille. Écrire après chaque étape signifie qu'une conversation de vingt tours à travers un graphe de cinq nœuds produit cent enregistrements plutôt que vingt. La base grossit plus vite que ne le suggère le nombre de messages, et une politique de suppression des anciens threads est ici obligatoire plutôt que facultative.

Choisir où écrire

Les variantes disponibles diffèrent assez par leur finalité pour que se tromper coûte cher.

La variante qui garde tout dans la mémoire du processus existe uniquement pour le développement. Elle fonctionne tant que le processus vit et un second processus ne peut pas la voir. La faire tourner en production avec deux instances de l'application produit un symptôme qui ressemble à des conversations qui disparaissent au hasard : l'utilisateur tombe sur une instance, puis sur l'autre.

La variante à base de fichier convient aux expériences locales, car elle survit à un redémarrage, et ne convient pas à plusieurs processus à la fois.

La production appelle la variante adossée à une base de données relationnelle. Elle exige une préparation unique du schéma, et c'est l'étape qu'on oublie facilement, car sans elle le premier appel échoue avec une erreur de table manquante.

Un conseil pratique : règle la variante de production dès le départ, y compris dans l'environnement de test. L'écart de comportement entre la mémoire du processus et une base de données est assez large pour que les bugs n'apparaissent qu'après le basculement, c'est-à-dire au pire moment.

Le store entre threads

La seconde couche est plus simple à utiliser et plus difficile à concevoir.

Écrire signifie fournir un namespace, une clé et une valeur. Le namespace contient généralement un identifiant d'utilisateur, ce qui sépare les données d'une personne de celles d'une autre.

Python
store.put(("user", user_id, "preferences"), "language", {"value": "english"})
result = store.search(("user", user_id, "preferences"), query="communication language")

La difficulté se situe ailleurs que dans l'interface. Tu dois décider de ce qu'il faut enregistrer, et c'est une décision de produit plutôt qu'une décision technique.

Deux approches sont raisonnables. La première est d'enregistrer ce que l'utilisateur a énoncé explicitement : langue préférée, heures de contact, format des réponses. Simple, prévisible, et suffisante dans la plupart des cas.

La seconde est de laisser le modèle décider, en lui donnant un outil qui écrit dans le store. Plus riche et moins prévisible, car un modèle enregistre des broutilles et perd ce qui compte. Avec cette variante, inspecter le contenu du store après une semaine de travail est obligatoire.

Une troisième approche, enregistrer tout ce qui a été dit dans une conversation, est tentante et presque toujours mauvaise. Le store se remplit de bruit, la recherche renvoie des fragments dénués de sens, et le coût grimpe.

Ce qui arrive dans le prompt

La mémoire elle-même est inutile tant qu'elle n'influence pas une réponse, et cette étape est négligée.

Les checkpoints entrent automatiquement dans le modèle, puisque l'historique des messages fait partie de l'état du graphe. Ici le problème est inverse : sur une longue conversation, l'historique cesse de tenir dans la fenêtre et doit être tronqué ou résumé.

La troncature simple, qui garde les N derniers messages, fonctionne dans la plupart des cas et ne coûte rien. Résumer la partie ancienne donne plus de contexte et coûte des appels supplémentaires au modèle. Le choix dépend de la question de savoir si les conversations remontent vraiment à des choses dites cinquante messages plus tôt.

Les données du store n'entrent pas d'elles-mêmes dans le prompt. Tu dois les récupérer et les insérer, et la même règle s'applique qu'à toute mémoire : quelques faits pertinents aident plus que vingt faits arbitraires. Chercher selon le contenu de la question en cours bat généralement le fait de tirer un namespace entier.

Décris aussi dans le prompt d'où viennent ces faits. Des phrases collées sans titre sont traitées au même niveau que la question de l'utilisateur, alors qu'une section étiquetée comme connaissance sur la personne donne des résultats nettement meilleurs.

L'identifiant de thread comme décision de conception

Cela ressemble à un détail technique et c'est l'une des décisions les plus lourdes de conséquences quand on construit sur cette bibliothèque.

Le choix se ramène à ce que tu considères comme une conversation. Un identifiant égal à l'identifiant d'utilisateur signifie que chaque personne a un thread sans fin : tout l'historique toujours disponible, tout l'historique toujours croissant. Un identifiant généré chaque fois qu'une fenêtre de chat s'ouvre signifie que les conversations restent séparées et que rien ne passe de l'une à l'autre.

Les deux variantes ont leur place. Un assistant de support, où chaque signalement est un dossier distinct, convient à la seconde. Un assistant personnel, où la continuité est l'intérêt du produit, convient à la première, à condition d'avoir un plan pour tronquer l'historique.

Une troisième variante, le plus souvent la bonne, est un identifiant de session à durée de vie limitée : une nouvelle conversation après quelques heures d'inactivité, ce qui doit survivre allant dans le store entre threads. Elle combine une taille d'état prévisible et une continuité là où elle est nécessaire.

Prends cette décision avant le premier déploiement, car changer le schéma d'identifiants ensuite rend inaccessibles les threads existants. L'historique ne disparaît pas de la base ; personne n'y retombera jamais.

Concurrence et ce qui se passe avec deux requêtes

Un thread servi par deux appels parallèles est une situation facile à négliger et plus courante qu'une conception ne le suppose.

Le scénario typique : un utilisateur envoie un message, ne voit pas de réponse, en envoie un autre. Ou l'interface relance une requête après un délai d'expiration alors que la précédente tourne encore. Les deux appels travaillent sur le même thread et écrivent tous deux des checkpoints.

Le résultat dépend de l'ordre d'écriture et peut être difficile à reproduire : certaines étapes d'une exécution, certaines de l'autre, et un état final qui ne correspond à aucune. Les symptômes ressemblent à des bugs aléatoires dans la logique de l'agent.

Il existe deux réponses, toutes deux de ton côté. Tu peux verrouiller les appels parallèles sur le même thread, en rejetant le second avec un message lisible. Ou tu peux générer un nouvel identifiant pour une requête relancée, en acceptant que les flux se séparent.

Avec une interface en streaming, il vaut aussi la peine de s'assurer qu'un utilisateur qui coupe la connexion ne laisse pas le thread dans un état intermédiaire. Un graphe interrompu à mi-chemin enregistre ce qu'il a réussi à faire, et à la reprise repart de là, ce qui est parfois souhaitable et parfois une surprise.

LangGraph face aux solutions externes

OptionCe qu'elle couvreOù se trouvent les donnéesÀ choisir quand
Les couches intégréesThreads et faits simplesDans ta base de donnéesLe choix par défaut dans ce framework
Mem0Faits avec rechercheChez un fournisseur ou chez toiTu veux une extraction de faits prête à l'emploi
ZepUn graphe avec un axe temporelChez un fournisseur ou chez toiLes faits changent avec le temps
LettaTout un runtime d'agentChez toi ou chez un fournisseurTu construis un agent de zéro

Considère la première ligne comme un point de départ plutôt que comme une mesure provisoire. Un store avec namespaces et recherche de contenu couvre la plupart des cas réels, et les données restent dans ta base à côté du reste de l'application.

Recourir à des couches externes a du sens quand tu as besoin de quelque chose que la couche intégrée ne fait pas : l'extraction automatique de faits à partir d'une conversation sans écrire ta propre logique, ou la résolution de contradictions entre des faits de moments différents. Ce sont des besoins précis plutôt que des besoins par défaut.

La dernière ligne est un autre genre de choix, car elle concerne l'architecture de toute l'application plutôt qu'une couche de mémoire. Avec un graphe qui fonctionne dans ce framework, y passer signifie une réécriture.

Time travel et reprise

Écrire après chaque étape offre une capacité précieuse pour le diagnostic.

L'historique des états d'un thread peut être lu et rembobiné jusqu'à n'importe quel point, puis le graphe est relancé à partir de là avec une configuration ou une entrée différente. Face à « pourquoi l'agent a-t-il pris cette décision », cela te permet de reconstituer le déroulement plutôt que de deviner.

La même capacité permet la mise en pause pour une décision humaine. Un graphe arrêté avant une étape qui effectue une opération irréversible attend, et la reprise suit l'approbation, y compris depuis un autre processus et après n'importe quel délai.

Associe-la à un outil de traçage, LangSmith ou Arize Phoenix par exemple. Les checkpoints montrent l'état tandis que les traces montrent exactement ce qui est parti vers le modèle et ce qui est revenu. L'un sans l'autre laisse un trou dans la reconstitution du déroulement.

Erreurs courantes

La première est la variante en mémoire du processus en production. Avec deux instances de l'application, le symptôme ressemble à des conversations qui disparaissent au hasard.

La deuxième est de confondre les couches. Les préférences d'utilisateur stockées dans l'état du graphe disparaissent avec le thread, et l'historique de conversation stocké dans le store ne reprend pas le déroulement.

La troisième est de n'avoir aucune politique de suppression des anciens threads. Écrire après chaque étape fait grossir la base bien plus vite que ne le suggère le nombre de conversations.

La quatrième est de sauter la préparation du schéma de base de données. Le premier appel échoue alors avec une erreur de table manquante, et la cause ressemble à un problème de connexion.

La cinquième est d'envoyer tout l'historique au modèle sans le tronquer. Sur des conversations plus longues, cela finit par dépasser la fenêtre de contexte ou par une facture qui croît de façon quadratique.

La sixième est d'écrire dans le store tout ce qu'un utilisateur a dit. La recherche renvoie alors du bruit, et avec des données sensibles l'enregistrement survit à la conversation.

FAQ

En quoi un checkpointer diffère-t-il d'un store ?

Par la portée. Les checkpoints enregistrent l'état du graphe et appartiennent à un thread, donc ils gèrent la continuité au sein d'une conversation. Un store contient des données entre les threads, généralement dans un namespace lié à un utilisateur, donc il gère ce qui doit survivre d'une conversation à l'autre.

Pourquoi l'agent ne se souvient-il pas d'un utilisateur qui revient ?

Le plus souvent parce que l'information a été écrite dans l'état du graphe plutôt que dans le store. L'état appartient à un thread, et un utilisateur qui revient démarre généralement un nouveau thread, donc il reçoit un historique vide.

Quelle variante d'écriture la production doit-elle utiliser ?

Celle adossée à une base de données relationnelle, car elle survit à un redémarrage et fonctionne avec plusieurs processus. La variante en mémoire du processus existe pour le développement, et celle à base de fichier pour des expériences locales sur un seul processus.

Comment gérer un long historique de conversation ?

En tronquant aux messages les plus récents ou en résumant la partie ancienne. La troncature est peu coûteuse et suffisante dans la plupart des cas ; résumer donne plus de contexte au prix d'appels supplémentaires au modèle.

Ai-je besoin d'une couche de mémoire externe ?

Généralement pas pour commencer. Le store intégré avec namespaces couvre les cas typiques, et les données restent dans ta base. Mem0 ou Zep valent la peine quand tu as besoin d'extraction automatique de faits ou de résolution de contradictions dans le temps.

La documentation sur la persistance se trouve sur le site du projet, et le code et les versions dans le dépôt GitHub.

À lire aussi