07 - Mémoire persistante : comment Hermes se souvient

Mémoire persistante : comment Hermes se souvient

La plupart des agents IA sont amnésiques : chaque conversation démarre de zéro, sans aucun souvenir des sessions précédentes. Hermes Agent brise ce cycle grâce à un système de mémoire persistante qui lui permet de retenir vos préférences, vos projets, et les leçons apprises au fil des sessions. Cette mémoire est injectée automatiquement dans chaque nouvelle conversation, donnant à l'agent un contexte immédiat sans que vous n'ayez à répéter quoi que ce soit.

Cet article détaille le fonctionnement complet de la mémoire persistante d'Hermes Agent : les deux magasins de mémoire (MEMORY.md et USER.md), les meilleures pratiques pour rédiger des entrées utiles, la recherche dans les sessions passées, la gestion des capacités, et les pièges courants à éviter.

Le principe fondamental

Hermes Agent maintient une mémoire bornée et curatée — c'est-à-dire délibérément limitée en taille et gérée activement par l'agent. Ce n'est pas un stockage illimité : c'est un espace précieux où seuls les faits les plus importants trouvent leur place.

Concrètement, la mémoire fonctionne ainsi :
- Deux fichiers Markdown stockés dans ~/.hermes/ : MEMORY.md et USER.md
- Injection automatique dans le prompt système au démarrage de chaque session
- Gestion via le tool memory (ajout, remplacement, suppression)
- Snapshot gelé en début de session (les modifications n'apparaissent qu'à la session suivante)

Ce design garantit une empreinte token constante et prévisible, tout en offrant à l'agent une mémoire à long terme fiable.

Les deux cibles de mémoire

Hermes Agent distingue deux magasins de mémoire, chacun avec sa vocation et ses limites :

memory — Notes personnelles de l'agent

La cible memory stocke tout ce que l'agent doit retenir sur votre environnement, vos projets et les leçons apprises :
- Faits d'environnement : OS installé, outils disponibles, structure du projet
- Conventions de projet : style de code, outils de build, commandes de test
- Découvertes techniques : particularités d'un outil, contournements identifiés
- Journal des tâches : migrations effectuées, bugs corrigés, déploiements réalisés
- Techniques éprouvées : approches qui ont bien fonctionné dans le passé

Limite par défaut : 2 200 caractères (environ 8 à 15 entrées).

user — Profil utilisateur

La cible user conserve tout ce qui concerne votre identité, vos préférences et votre style de communication :
- Identité : nom, rôle, fuseau horaire
- Style de communication : réponses concises ou détaillées, format préféré
- Préférences techniques : langage favori, éditeur utilisé, workflow habituel
- À éviter : irritants, formulations à ne pas employer

Limite par défaut : 1 375 caractères (environ 5 à 10 entrées).

Le tool memory en action

L'agent utilise le tool memory avec trois actions :

• add — Ajouter une nouvelle entrée de mémoire
• replace — Remplacer une entrée existante (recherche par sous-chaîne via old_text)
• remove — Supprimer une entrée obsolète (recherche par sous-chaîne via old_text)

Il n'existe pas d'action read : le contenu de la mémoire est automatiquement injecté dans le prompt système au démarrage de chaque session. L'agent « voit » ses souvenirs comme partie intégrante de son contexte de conversation.

Recherche par sous-chaîne

Les actions replace et remove utilisent un mécanisme de sous-chaîne unique. Pas besoin de fournir l'entrée complète — juste un extrait suffisamment spécifique pour identifier une seule entrée :

# Si la mémoire contient "User prefers dark mode in all editors"
memory(action="replace", target="memory",
       old_text="dark mode",
       content="User prefers light mode in VS Code, dark mode in terminal")

Si la sous-chaîne correspond à plusieurs entrées, une erreur est retournée demandant une correspondance plus précise.

Le snapshot gelé

Un point crucial : l'injection dans le prompt système est capturée une seule fois au démarrage de la session et ne change pas en cours de session. C'est intentionnel — cela préserve le cache de préfixe du LLM pour des performances optimales. Quand l'agent ajoute ou retire des entrées pendant une session, les modifications sont immédiatement écrites sur disque, mais n'apparaîtront dans le prompt système qu'au démarrage de la session suivante.

Ce qu'il faut sauvegarder — et ce qu'il faut éviter

À sauvegarder (proactivement)

L'agent sauvegarde automatiquement — vous n'avez pas besoin de le demander :

• Préférences utilisateur : « Je préfère TypeScript à JavaScript » → cible user
• Faits d'environnement : « Ce serveur tourne sous Debian 12 avec PostgreSQL 16 » → cible memory
• Corrections : « Ne pas utiliser sudo pour Docker, l'utilisateur est dans le groupe docker » → cible memory
• Conventions : « Le projet utilise des tabs, largeur de ligne 120, docstrings Google-style » → cible memory
• Travaux terminés : « Migration de MySQL vers PostgreSQL effectuée le 15/01/2026 » → cible memory
• Requêtes explicites : « Retiens que la rotation de mes clés API est mensuelle » → cible memory

À éviter absolument

• Info triviale : « L'utilisateur a posé une question sur Python » — trop vague
• Faits facilement retrouvables : « Python 3.12 supporte l'imbrication de f-strings » — une recherche web suffit
• Dumps de données brutes : gros blocs de code, fichiers de log, tableaux — trop volumineux
• Éphémères de session : chemins de fichiers temporaires, contexte de débug ponctuel
• Déjà dans les fichiers de contexte : tout ce qui figure dans SOUL.md ou AGENTS.md

Faits vs instructions : les deux types d'entrées

Les meilleures entrées mémoire se divisent en deux catégories complémentaires :

Les faits sont des informations neutres que l'agent utilise pour adapter ses réponses :

« Le serveur staging est à 10.0.1.50, port SSH 2222. Clé : ~/.ssh/staging_ed25519. »

Les instructions sont des directives que l'agent doit suivre :

« Toujours vérifier les dépendances avec pnpm outdated avant tout déploiement. »

La combinaison des deux est puissante : les faits donnent le contexte, les instructions guident l'action. Mais attention — une instruction vague ou obsolète est pire que pas d'instruction du tout.

Exemples concrets de bonnes entrées mémoire

Bonnes entrées (compactes et denses en informations) :

User runs macOS 14 Sonoma, uses Homebrew, has Docker Desktop and Podman. Shell: zsh with oh-my-zsh. Editor: VS Code with Vim keybindings.

Project ~/code/api uses Go 1.22, sqlc for DB queries, chi router. Run tests with 'make test'. CI via GitHub Actions.

The staging server (10.0.1.50) needs SSH port 2222, not 22. Key is at ~/.ssh/staging_ed25519.

Mauvaises entrées :

User has a project.

Too vague — aucune information actionnable.

On January 5th, 2026, the user asked me to look at their project which is located at ~/code/api. I discovered it uses Go version 1.22 and...

Trop verbeux — gaspille de précieux caractères.

Gestion de la capacité : ne pas remplir la mémoire inutilement

La mémoire a des limites strictes pour garder le prompt système sous contrôle :

• memory : 2 200 caractères (~800 tokens)
• user : 1 375 caractères (~500 tokens)

Quand vous essayez d'ajouter une entrée qui dépasserait la limite, le tool retourne une erreur avec la liste des entrées actuelles et le pourcentage d'utilisation. L'agent doit alors consolider les entrées existantes avant d'en ajouter de nouvelles.

Bonne pratique : quand la mémoire dépasse 80 % de sa capacité (visible dans l'en-tête injecté dans le prompt), consolidez les entrées avant d'en ajouter. Par exemple, fusionnez trois entrées « le projet utilise X » en une seule description complète du projet.

Détection et nettoyage des entrées obsolètes

Au fil du temps, certaines mémoires deviennent obsolètes. L'agent doit régulièrement :
1. Relire ses entrées mémoire au début de chaque session
2. Identifier les informations potentiellement périmées (dates anciennes, références à des versions logicielles dépassées)
3. Utiliser replace pour mettre à jour ou remove pour supprimer

Le système intègre aussi une prévention des doublons : si vous tentez d'ajouter un contenu qui existe déjà, le tool retourne un succès avec un message « aucun doublon ajouté ».

La mémoire procédurale : le système de skills

Au-delà de la mémoire déclarative (MEMORY.md / USER.md), Hermes Agent possède une mémoire procédurale via son système de skills. Un skill est un ensemble de connaissances et de procédures que l'agent a appris à travers l'expérience et qui lui permet d'accomplir des tâches complexes de manière autonome.

Les skills sont stockés dans ~/.hermes/skills/ et vont plus loin que la mémoire classique :
- Ils peuvent inclure des scripts, des templates et des workflows complets
- Ils sont activés automatiquement quand le contexte le requiert
- Ils évoluent au fil du temps grâce au système de Curator

La distinction est importante : la mémoire déclarative dit « quoi » (faits et préférences), la mémoire procédurale dit « comment » (procédures et workflows). Les deux systèmes fonctionnent en tandem pour offrir un agent de plus en plus compétent.

session_search : retrouver les conversations passées

Au-delà de MEMORY.md et USER.md, l'agent peut chercher dans toutes ses conversations passées grâce au tool session_search :

• Toutes les sessions CLI et de messagerie sont stockées dans SQLite (~/.hermes/state.db) avec recherche plein texte FTS5
• Les requêtes retournent les conversations pertinentes avec résumé par Gemini Flash
• L'agent peut retrouver des échanges datant de plusieurs semaines

Mémoire persistante vs session_search

Mémoire persistante :
- ~1 300 tokens au total
- Instantanée (dans le prompt système)
- Faits critiques toujours disponibles
- Curatée manuellement par l'agent
- Coût token fixe par session

Session search :
- Capacité illimitée (toutes les sessions)
- Requiert recherche + résumé LLM
- Trouve des conversations spécifiques du passé
- Stockage automatique
- Coût token à la demande

La mémoire est pour les faits critiques toujours en contexte. La recherche de sessions est pour les requêtes du type « avons-nous discuté de X la semaine dernière ? ».

Différence entre mémoire, fichiers de contexte et sessions

Trois mécanismes distincts cohabitent dans Hermes Agent, chacun avec son rôle :

Fichiers de contexte (HERMES.md, AGENTS.md, SOUL.md) : instructions projectuelles et personnalité. Ils sont découverts automatiquement dans l'arborescence du projet et définissent le comportement attendu. Voir notre article sur les fichiers de contexte pour en savoir plus.

Mémoire persistante (MEMORY.md, USER.md) : faits appris au fil des sessions. L'agent les gère lui-même — vous n'intervenez pas directement. C'est la mémoire « vivante » qui évolue avec votre utilisation.

Sessions (state.db) : historique complet des conversations. Accessible via session_search pour retrouver des détails précis d'échanges passés. Pour comprendre le système de sessions, consultez notre article sur les sessions et contexte.

Cas concrets d'utilisation

Cas 1 : Développeur full-stack avec plusieurs projets

Un développeur travaille sur un projet Next.js et un projet Python FastAPI. Grâce à la mémoire, Hermes sait automatiquement quel framework utiliser selon le répertoire de travail, quelles commandes lancer pour les tests, et quelles conventions respecter dans chaque projet.

Cas 2 : Administrateur système multi-serveurs

L'admin gère des serveurs avec des configurations différentes (ports SSH, distributions, versions de base de données). La mémoire retient les particularités de chaque serveur, évitant les erreurs coûteuses de connexion au mauvais port ou avec la mauvaise clé.

Cas 3 : Équipe avec des préférences divergentes

Sur une machine partagée, chaque utilisateur peut avoir un profil différent dans USER.md. L'agent adapte son style de réponse et ses recommandations selon la personne avec qui il interagit.

Pièges courants et comment les éviter

Piège 1 : Trop de mémoire = tokens gaspillés

Chaque caractère en mémoire consomme des tokens à chaque session. Remplir la mémoire avec des informations triviales réduit l'espace disponible pour les faits vraiment importants. Soyez sélectif : ne gardez que ce qui est difficilement retrouvable autrement.

Piège 2 : Informations obsolètes

Une mémoire non entretenue devient un handicap. Si l'entrée « le projet utilise React 17 » persiste alors que vous êtes passé à React 19, l'agent vous proposera des solutions inadaptées. Nettoyez régulièrement.

Piège 3 : Dupliquer les fichiers de contexte

Ne stockez pas dans la mémoire ce qui figure déjà dans vos fichiers de contexte. Hermes lit HERMES.md et AGENTS.md automatiquement — les répéter dans MEMORY.md est un gaspillage.

Piège 4 : Instructions contradictoires

Si une entrée en mémoire dit « utiliser npm » et une autre « utiliser pnpm », l'agent sera confus. Assurez la cohérence de vos entrées.

Sécurité : scan automatique des entrées

Les entrées mémoire sont automatiquement scannées pour détecter les tentatives d'injection de prompt, l'exfiltration d'identifiants et les portes dérobées SSH. Le contenu correspondant à des menaces est bloqué avant d'être accepté. Cette protection est cruciale puisque le contenu mémoire est injecté dans le prompt système.

Configuration

La mémoire se configure dans ~/.hermes/config.yaml :

memory:
  memory_enabled: true
  user_profile_enabled: true
  memory_char_limit: 2200   # ~800 tokens
  user_char_limit: 1375     # ~500 tokens

Les limites par défaut sont équilibrées pour la plupart des usages, mais vous pouvez les ajuster selon vos besoins — gardez en tête que plus de mémoire = plus de tokens consommés par session.

Providers de mémoire externe

Pour aller au-delà des capacités natives, Hermes Agent supporte 8 providers de mémoire externe via des plugins : Honcho, OpenViking, Mem0, Hindsight, Holographic, RetainDB, ByteRover et Supermemory. Ces providers fonctionnent en complément de la mémoire intégrée et ajoutent des capacités comme les graphes de connaissances, la recherche sémantique et l'extraction automatique de faits.

Configurez un provider externe avec :

hermes memory setup      # choisir et configurer un provider
hermes memory status     # vérifier ce qui est actif

Conclusion

La mémoire persistante est l'une des fonctionnalités les plus transformatrices d'Hermes Agent. Elle transforme un assistant ponctuel en un véritable partenaire qui apprend et s'adapte au fil du temps. La clé est la discipline : des entrées concises, régulièrement nettoyées, bien séparées entre faits et instructions. Combinée au système de skills (mémoire procédurale) et à la recherche dans les sessions, elle crée une base de connaissances vivante qui rend chaque session plus productive que la précédente.

Pour aller plus loin dans la maîtrise d'Hermes Agent, découvrez nos articles précédents :
- Présentation et installation
- Configurer les modèles et providers
- Les outils disponibles
- Maîtriser le CLI
- Sessions et contexte
- Fichiers de contexte