Cycle de vie de la mémoire et de la charge utile

ZeroClaw transporte plusieurs types d’informations « mémorisées » pendant un tour. Elles n’ont pas toutes le même propriétaire, la même durabilité, la même frontière de confidentialité ni le même risque de revue.

Utilisez cette page lorsqu’une modification touche la mémoire, l’historique, la persistance de session, les résultats d’outils, les fichiers, les pièces jointes multimédias, les résumés, l’élagage de contexte ou l’assemblage de prompts. La question la plus importante n’est pas « l’agent s’en souvient-il ? » mais « quelle surface possède ces données, et combien de temps vivent-elles ? »

Qui possède quoi

Surface	Propriétaire	Durabilité	Ce que les relecteurs doivent vérifier
Mémoire à long terme	`zeroclaw-memory` derrière `Arc<dyn Memory>`	Spécifique au backend : SQLite/Postgres/Lucid/Qdrant/stockages partagés, ou fichiers Markdown par agent	Les stockages et rappels doivent rester scopés à l’agent. Un résultat d’outil, une ligne de log ou une ligne de session n’est pas de la mémoire à long terme à moins qu’une écriture en mémoire n’ait eu lieu.
Mémoire de relation	`knowledge` outil et graphe de connaissances	Backend de graphe, une fois activé	La capture est explicite. L’activation du graphe n’ingère pas automatiquement les conversations, les fichiers ou les données de canal.
Historique de session	`zeroclaw-infra` backends de session, store ACP et maps RPC/session live	L’historique Chat/ACP peut persister ; les handles RPC actifs sont locaux au processus	L’historique préserve la continuité de la conversation. Il n’est pas le dépôt canonique pour les préférences utilisateur, la configuration ou les fichiers.
Contexte du prompt actuel	Assemblage des prompts de la boucle agent	Requête de fournisseur éphémère	La mémoire rappelée, le RAG matériel, l’entrée actuelle, le prompt système, les compétences et les résultats d’outils peuvent être envoyés au fournisseur. Cela ne les rend pas durables.
Nettoyage de l’historique	`agent::history` et `agent::history_trim`	Modification avec perte de la structure de l’historique des requêtes/sessions	L’élagage doit être visible, préserver l’appariement tool-call/tool-result, et éviter de prétendre que l’ancien contexte est toujours disponible.
Charges utiles des résultats d’outils	`ToolResult`, `ToolResultMessage` et le répartiteur d’outils	Tour actuel et historique de session persisté qui enregistre le tour	Limitez la taille et la provenance. Les sorties volumineuses doivent être limitées ou résumées de manière intentionnelle ; la promotion des chemins d’image ne doit intervenir que pour les outils de production, et non pour les outils de liste de chemins.
Fichiers et espaces de travail	Politique de sécurité de l’espace de travail par agent	Les fichiers persistent au niveau du système de fichiers, et non en mémoire	Le contenu des fichiers ne constitue pas une mémoire simplement parce qu’un outil les a lus. Les écritures doivent être effectuées dans l’espace de travail de l’agent, sauf si la politique l’autorise explicitement davantage.
Pièces jointes multimédia	Pipeline multimédia canal/passerelle et `MediaAttachment`	Charge utile entrante par défaut ; la persistance dépend du chemin de réception	Les octets bruts doivent rester bornés et validés par le chemin. Stockez des résumés ou des références de manière délibérée plutôt que de copier silencieusement les médias en mémoire.
Journaux et événements d’observateur	`zeroclaw-log`, `ObserverEvent`, trace d’exécution	Trace d’exécution optionnelle et observateurs en direct	Les logs sont des preuves et des informations de diagnostic, et non une mémoire de référence. Nettoyez ou limitez les charges utiles utilisateur/outil avant la journalisation.
Enregistrements des coûts et de l’utilisation	Suivi des coûts et événements d’utilisation des fournisseurs	Grand livre des coûts lorsqu’il est activé	Les enregistrements d’utilisation décrivent les appels au modèle. Ils ne doivent pas contenir les corps de prompts, les sorties d’outils ou le contenu de la mémoire.

Ce tableau complète État d’exécution et persistance. Cette page indique où se trouve l’état ; la présente page indique comment les charges utiles destinées à l’utilisateur transitent par la mémoire, l’historique, les outils, les fichiers, les médias et les requêtes aux fournisseurs.

Mémoire à long terme

Un agent reçoit son descripteur de mémoire de l’usine de mémoire. Les backends partagés et le stockage Markdown ont des organisations concrètes différentes, mais la règle de vérification est la même : l’accès à la mémoire doit rester lié à l’identité de l’agent et à la liste d’autorisation des pairs configurée, décrite dans Runtime internals.

Il existe deux façons normales pour que l’information devienne une mémoire durable :

l’agent appelle un outil de mémoire tel que memory_store;
le code d’exécution stocke explicitement une entrée de mémoire, telle que le chemin d’autosauvegarde de conversation configuré.

Ne pas considérer le contexte du prompt, la sortie des outils, les fichiers ou les logs comme une mémoire persistante par défaut. Une PR qui rend l’une de ces surfaces persistante doit préciser la catégorie de mémoire, la portée de la session, la portée de l’agent, le comportement de rétention et le contrôle visible par l’opérateur.

Contexte de prompt et rappel

Au début de tour, le runtime peut récupérer les mémoires pertinentes et injecter un bloc [Memory context] borné dans le contexte d’invite visible par l’utilisateur. Les points d’entrée connexes n’appliquent pas tous les mêmes filtres. La boucle de canal/interactif filtre le bruit d’autosauvegarde généré, les blocs <tool_result> obsolètes et les entrées Conversation lorsque le tour ne dispose pas d’une portée de session sécurisée ou n’est pas initié par l’utilisateur. Le chargement générique de la mémoire filtre le bruit d’autosauvegarde et la pertinence, mais n’impose pas à lui seul cette exclusion des Conversation de la boucle de canal.

La requête au fournisseur peut donc contenir de la mémoire rappelée sans faire du tour actuel une nouvelle mémoire. Examinez les modifications d’assemblage de prompt en demandant :

quel backend de mémoire et quelle portée d’agent ont été interrogés ;
si la requête est à portée de session lorsque les entrées de conversation sont autorisées ;
si le bruit d’enregistrement automatique, les blocs de résultats d’outils obsolètes et les entrées à faible pertinence restent filtrés ;
si l’utilisateur ou l’opérateur peut voir quand le contexte plus ancien a été supprimé.

Historique de session et élagage

L’historique de session est le registre de continuité d’une conversation. Il peut inclure des messages de chat, des appels d’outils de l’assistant et des résultats d’outils. Ce n’est pas la même chose que la mémoire à long terme.

Gestion de l’historique gère les mécanismes de troncature. Cette page ne nomme que la frontière du cycle de vie : la troncature est une modification avec perte du contexte visible par le fournisseur/visible par la session, pas une suppression de mémoire, et elle doit être visible plutôt que de prétendre silencieusement que l’ancien contexte reste disponible.

L’appariement des appels d’outils est plus important que les économies d’octets. Un changement d’historique ne doit pas laisser une requête de fournisseur avec un tool_use orphelin sans le tool_result correspondant, ou l’inverse.

Résultats des outils

Les outils renvoient un petit résultat structuré : success, output et error. Le dispatcher convertit ces résultats en messages de fournisseur pour le prochain appel de modèle, tandis que les clients en streaming peuvent recevoir des événements ToolCall et ToolResult corrélés pendant le tour.

Les charges utiles des résultats d’outils sont faciles à trop préserver. Les relecteurs doivent vérifier :

taille maximale du résultat, y compris max_tool_result_chars;
si la troncature préserve les enveloppes structurées et les marqueurs d’image ;
si les outils de recherche/listage évitent de transformer les chemins d’images fortuits en charges utiles multimédias ;
si les reçus, les journaux et les événements d’observateur portent des preuves bornées et nettoyées plutôt que des sorties sensibles brutes ;
si le résultat se trouve uniquement dans l’historique du tour/session en cours ou s’il est également écrit intentionnellement en mémoire.

Si une PR indique qu’un résultat d’outil est “mémorisé”, exigez qu’il précise s’il s’agit d’un historique visible par le fournisseur, d’un historique de session persisté, d’une ligne du backend de mémoire, d’un artefact de fichier, d’un reçu ou d’un événement de journal.

Fichiers et médias

Le contenu des fichiers et les octets multimédias sont des charges utiles, pas des mémoires. Le propriétaire du système de fichiers est la politique d’espace de travail par agent décrite dans Filesystem components et Runtime internals. Une lecture de fichier peut placer du contenu dans un résultat d’outil ou un prompt ; une écriture de fichier peut créer un état persistant du système de fichiers ; aucun des deux ne crée automatiquement une ligne de mémoire.

Les messages entrants du canal peuvent contenir des valeurs MediaAttachment contenant un nom de fichier, des octets et un type MIME optionnel. MediaKind est dérivé du type MIME ou de l’extension du fichier. Le chargeur de pièces jointes de bas niveau lit les chemins fournis par l’appelant tels quels, de sorte que les appelants qui acceptent des chemins non fiables doivent valider ou restreindre ces chemins avant le chargement.

Pour les fichiers et les médias, les réviseurs doivent rechercher :

application des politiques d’espace de travail avant les lectures et écritures ;
validation de chemin lorsqu’un chemin provient d’un utilisateur, d’une requête HTTP, d’une charge utile de canal ou d’un argument d’outil ;
gestion bornée des octets et comportement d’échec clair pour les fichiers manquants ou illisibles ;
résumés explicites ou références lorsque des charges utiles volumineuses/binaires entrent dans les prompts ;
Pas de copie silencieuse depuis une pièce jointe ou le contenu d’un fichier dans la mémoire à long terme.

Logs et observabilité

Les événements Observer et les journaux d’exécution aident à expliquer ce qui s’est passé. Ils ne doivent pas devenir des stockages de payload cachés. Les événements de rappel mémoire contiennent un résumé de requête nettoyé/tronqué et des compteurs. Les événements de stockage mémoire contiennent des identifiants de catégorie et de backend limités.

L’observabilité des appels d’outils nécessite une attention particulière car les sinks ne partagent pas un seul contrat de payload. Les événements d’observateur d’appels d’outils typés actuels peuvent transporter les arguments complets et la sortie de résultat complète nettoyée des identifiants, et OTel transmet ces valeurs dans les attributs de span. Ne décrivez pas ce chemin comme des « résumés » à moins que le code ne le borne ou ne le résume réellement. La nouvelle télémétrie devrait privilégier les identifiants bornés, les comptages, les durées, les indicateurs de succès et les résumés utiles aux opérateurs. Placez le contenu brut dans les journaux ou les événements d’observateur uniquement lorsque la fonctionnalité l’exige explicitement et que la frontière de confidentialité est documentée.

Liste de contrôle du relecteur

Pour les modifications de mémoire, de payload, d’historique, de fichier ou de médias, répondez à ces points avant la validation par le relecteur :

Quel est le propriétaire canonique des données ?
Est-ce uniquement pour le tour actuel, persistant entre les sessions, persistant dans le système de fichiers, persistant en mémoire ou persistant dans les journaux ?
Quelle portée d’agent, de session, de canal ou d’espace de travail limite l’accès ?
Un appelant peut-il étendre le rappel de la mémoire au-delà de la liste autorisée configurée ?
Les tâches autonomes peuvent-elles accéder à la mémoire de conversation issue du chat ?
Qu’est-ce qui limite la sortie des outils, les octets de fichiers, les octets de médias et la taille du prompt ?
Le tronçonnage ou la troncature rend-il la perte visible au lieu de la laisser silencieuse ?
Les payloads visibles par le fournisseur sont-ils séparés des écritures mémoire durables ?
Les journaux et les événements de l’observateur sont-ils nettoyés et limités ?
Si la PR modifie un payload généré ou dérivé, met-elle à jour le propriétaire de la source plutôt que de modifier manuellement la sortie générée ?

Pointeurs source

Documentation Canonical :

Principaux points d’entrée du code :

Trait Memory et forme de l’entrée : crates/zeroclaw-api/src/memory_traits.rs
Usine de mémoire et scoping des agents : crates/zeroclaw-memory/src/lib.rs, crates/zeroclaw-memory/src/agent_scoped.rs et crates/zeroclaw-memory/src/agent_scoped_markdown.rs
Registre des outils mémoire et exemples : crates/zeroclaw-tools/src/lib.rs (MEMORY_TOOL_NAMES), crates/zeroclaw-tools/src/memory_store.rs, et crates/zeroclaw-tools/src/memory_recall.rs
Rappel et injection de prompt : crates/zeroclaw-runtime/src/agent/memory_inject.rs (politique de rappel plus le renderer [Memory context]), injecté côté moteur dans crates/zeroclaw-runtime/src/agent/turn/mod.rs ; le handle mémoire par tour est transmis via crates/zeroclaw-runtime/src/agent/loop_.rs
Découpage de l’historique et mise en forme du payload des résultats d’outil : crates/zeroclaw-runtime/src/agent/history.rs, crates/zeroclaw-runtime/src/agent/history_trim.rs, et crates/zeroclaw-runtime/src/agent/turn/results_collect.rs
Formes des messages d’outil et de fournisseur : crates/zeroclaw-api/src/tool.rs et crates/zeroclaw-api/src/model_provider.rs
Attachements du canal : crates/zeroclaw-api/src/channel.rs et crates/zeroclaw-api/src/media.rs

Keyboard shortcuts

ZeroClaw Docs