Architecture mémoire à trois couches pour le contexte persistant de l'agent OpenClaw

Architecture de mémoire pour un contexte d'agent persistant

Un développeur exécutant une opération multi-agents OpenClaw pour l'immobilier a rencontré une perte de contexte persistante où les agents démarraient chaque session à zéro, nécessitant de réexpliquer le travail précédent. Cela a entraîné des coûts commerciaux concrets, notamment des agents traitant des pistes chaudes comme des inconnus et manquant des délais par manque d'état.

La solution est une architecture de mémoire à 3 couches construite sur l'infrastructure existante d'espace de travail et de mémoire d'OpenClaw. L'information circule vers le bas à travers les couches et n'est jamais dupliquée entre elles.

Couche 1 : Cerveau (fichiers d'espace de travail)

OpenClaw injecte automatiquement un ensemble fixe de fichiers d'espace de travail comme contexte de projet à chaque tour. Ces sept fichiers forment le système d'exploitation de l'agent :

• SOUL.md : personnalité, voix, valeurs
• AGENTS.md : rôle, règles, voie
• MEMORY.md : ce qui est actif en ce moment (une ligne par élément, présent)
• USER.md : comment l'utilisateur pense et ce dont il a besoin
• TOOLS.md : commandes spécifiques à la machine et solutions de contournement
• IDENTITY.md : nom, rôle, référence rapide
• HEARTBEAT.md : tâches permanentes pour vérifications récurrentes

Le développeur a établi une règle de budget : bien qu'OpenClaw autorise jusqu'à 20 000 caractères par fichier, ils visent 500-1 000 tokens par fichier, gardant le total L1 sous 7 000 tokens. Cela garantit que les agents lisent réellement tout au lieu de survoler des fichiers gonflés. Une commande trim applique cette limite.

Règle de stabilité : seul l'utilisateur ou un point de contrôle met à jour les fichiers L1. Les agents ne changent pas aléatoirement leurs propres règles, à l'exception que MEMORY.md peut être mis à jour pour refléter l'état actuel.

Couche 2 : Mémoire (recherche sémantique)

Il s'agit du rappel à long terme utilisant l'outil intégré memory_search d'OpenClaw qui recherche sémantiquement dans MEMORY.md et tout ce qui se trouve dans le répertoire memory/. Quand un agent est interrogé sur un travail antérieur, des décisions ou un contexte, il recherche automatiquement dans L2.

Deux types de fichiers résident ici :

• Notes quotidiennes : memory/YYYY-MM-DD.md (convention OpenClaw) contenant l'historique des sessions, décisions prises, travail accompli et corrections
• Fichiers de miettes de pain : memory/[nom-du-sujet].md (ajout du développeur) contenant des faits organisés par situation, avec 4 Ko maximum par fichier, un fait par ligne

Chaque fait clé dans les fichiers de miettes de pain inclut un pointeur vers L3 : → Plongée profonde : reference/nom-du-fichier.md. Cela crée un pont entre L2 et L3 pour que les agents n'aient pas besoin de charger des documents de référence complets juste pour se souvenir d'un fait pertinent.

Insight critique : la précision de L2 dépend entièrement de ce qui y est écrit. Si un agent effectue une action et ne la capture pas avant de passer à autre chose, le fichier d'état commence à renvoyer des informations obsolètes.

Couche 3 : Référence (à la demande)

Ceci est entièrement un ajout du développeur, pas une convention OpenClaw. Un répertoire reference/ contient un contexte approfondi : SOPs, cadres, playbooks et recherches.

Les agents accèdent à L3 à la demande quand une tâche spécifique nécessite de la profondeur. Il n'est pas recherché par memory_search par conception pour éviter de brûler du contexte en chargeant des choses qui importent rarement.

Le flux complet : L1 (toujours chargé) → recherche L2 (mémoire) → ouverture L3 (référence) à la demande.