Hermes Agent fait régime : comment le layout v23 FTS réduit state.db jusqu'à 78%

Si vous utilisez Hermes Agent depuis plus de quelques semaines, vous avez probablement remarqué que ~/.hermes/hermes.db ne cesse de grossir. L’agent stocke chaque message, résultat d’outil et trace de raisonnement pour conserver le contexte entre les sessions. Mais la facture de cette mémoire était plus élevée qu’elle n’aurait dû l’être — non pas à cause des données de chat elles-mêmes, mais à cause de la façon dont les index de recherche les stockaient.

Un changement récent intégré dans la PR #65798 introduit le layout compact v23 FTS. Sur les installations lourdes, il supprime environ 75% de l’empreinte de state.db, et sur certaines charges de travail intensives en outils, la réduction avoisine 78%. Les enregistrements de conversation réels ne sont pas touchés ; seuls les index de recherche deviennent plus petits et plus intelligents.

Dans cet article, je vais expliquer ce qui gonflait la base de données, comment le layout v23 y remédie, et exactement ce que vous devez faire pour en bénéficier.

Pour le contexte de la version v0.19.0 plus large, consultez nos notes de version v0.19.0.

Pourquoi la base de données grossissait si vite

Hermes conserve l’état à long terme dans une base de données SQLite située dans ~/.hermes/hermes.db. Chaque message est stocké dans une table messages et indexé pour la recherche plein texte à l’aide de deux index FTS5 :

messages_fts — un index à stemmer Porter pour la recherche en anglais
messages_fts_trigram — un index de trigrammes pour la recherche de sous-chaînes CJK

Depuis la migration du schéma v11, les deux index étaient des tables FTS5 inline. Cela signifie que chaque index conservait sa propre copie privée de content || tool_name || tool_calls pour chaque message. Les mêmes octets étaient stockés trois fois : une fois dans la table messages et une fois dans chaque index FTS.

Un exemple réel issu de l’issue #22478 a montré l’ampleur du problème :

Composant	Taille	% de la BDD
données messages	99 Mo	19,6%
données sessions	45 Mo	8,9%
index FTS	358 Mo	70,8%
Autres	3 Mo	0,7%
Total	505 Mo	100%

L’index de trigrammes consommait à lui seul 247 Mo — 49% de toute la base de données — parce que le texte CJK génère bien plus de tokens de trigramme que l’anglais, et parce que les lignes de sortie d’outils (role=tool) étaient également indexées. Les sorties d’outils sont principalement des payloads base64, des dumps de fichiers et des transcriptions de délégation que personne ne recherche avec des requêtes de sous-chaînes CJK.

Ce n’est pas seulement un problème d’espace disque. Les grands index inline ralentissent également les écritures, maintiennent les verrous plus longtemps et peuvent saturer les E/S disque lors de sessions gateway lourdes.

Ce que le layout v23 change

Le layout compact v23 FTS fait trois choses :

Index à contenu externe : les index FTS5 ne stockent plus leurs propres copies privées du contenu des messages. Ils pointent vers les colonnes réelles de la table messages, éliminant la duplication de 2 à 3x.
Index de trigrammes sans lignes d’outils : l’index de trigrammes ignore les lignes où role='tool'. C’est là que résidait l’essentiel du gonflement, car les sorties d’outils représentent généralement ~90% des octets de messages sur les agents très sollicités.
Migration optionnelle : les installations existantes conservent leur index legacy fonctionnant exactement comme avant. Vous ne passez à la v23 que lorsque vous exécutez hermes sessions optimize-storage.

La table messages reste identique octet pour octet. Votre historique de chat, votre mémoire et vos sessions ne sont pas touchés. Seul le stockage de l’index de recherche change.

Les chiffres : jusqu’à 78% plus petit

La PR #65798 rapporte une validation à la fois synthétique et réelle :

Scénario	Avant	Après
BDD synthétique de 30k messages, 60% lignes tool	463 Mo	131 Mo (28%)
Part FTS de cette BDD	~84%	~42%
Copie réelle de 25 Go / 1,38M messages	25 Go	~10 Go

Sur la base de données synthétique, la base passe de 463 Mo à 131 Mo — une réduction de 72%. Sur la copie de production réelle, la baisse de 25 Go à ~10 Go est une réduction de 60%, avec des comptages d’index exacts et une intégrité FTS5 propre. Sur les charges de travail intensives en outils où les lignes tool dominent, les économies peuvent atteindre 78% car l’index de trigrammes ne stocke plus du tout ces lignes.

Comment migrer

Les nouvelles installations créées après ce changement naissent automatiquement avec le layout v23. Si vous utilisez déjà Hermes, exécutez une seule commande :

hermes sessions optimize-storage

La commande effectue une opération délibérée au premier plan :

Vérifie l’espace disque disponible avant de démarrer (elle refuse de s’exécuter s’il n’y a pas assez d’espace).
Rétrograde les index legacy en temps O(1).
Remplit les nouveaux index par blocs de 500 lignes, en maintenant le cycle de travail du verrou d’écriture sous 20% pour qu’un gateway ou une session CLI en direct reste réactif.
Supprime les anciennes tables fantômes par blocs.
Exécute VACUUM pour récupérer l’espace libéré.
Estampille la nouvelle version du layout.

C’est sûr face à Ctrl-C et reprenable. Si vous l’interrompez, les marqueurs et résidus sont détectés lors de la prochaine exécution, et la commande reprend là où elle s’était arrêtée. L’agent vous avertit également si les résultats de recherche sont incomplets pendant la reconstruction, afin de ne pas halluciner silencieusement du contexte manquant.

Si vous manquez d’espace disque, vous pouvez sauter l’étape de vacuum :

hermes sessions optimize-storage --no-vacuum

Après la mise à niveau, hermes update affiche un avis d’une ligne concernant l’optimisation et le gain d’espace attendu.

Quand devriez-vous l’exécuter ?

Vous devriez exécuter hermes sessions optimize-storage si l’un de ces cas s’applique :

Votre ~/.hermes/hermes.db dépasse quelques centaines de mégaoctets et la majeure partie de la taille provient des index FTS.
Vous exécutez un gateway avec de longues sessions intensives en outils et remarquez des pics d’E/S disque ou des écritures lentes.
Vous êtes sur un petit VPS ou un ordinateur portable avec un stockage limité.
Vous venez d’installer Hermes et souhaitez confirmer que vous êtes déjà sur le layout v23.

Si vous êtes déjà satisfait des performances et de l’utilisation du disque, vous pouvez attendre. L’index legacy continue de fonctionner ; il s’agit d’une optimisation, pas d’un changement cassant.

Qu’en est-il de la qualité de recherche ?

Le changement ne supprime aucun contenu recherchable pour ce que vous recherchez réellement. Les conversations et tool_calls/tool_name restent recherchables via l’index à contenu externe. La recherche de sous-chaînes CJK dans le texte de conversation fonctionne toujours. La seule différence est que la recherche de sous-chaînes CJK dans les sorties d’outils bascule vers une requête LIKE au lieu de l’index de trigrammes — ce qui est acceptable, car ce type de recherche est rarement utile dans des payloads base64 ou des dumps de fichiers.

Un examen indépendant par @yoniebans sur une migration réelle v19→v23 a confirmé que l’empreinte SHA-256 de la table messages était identique avant et après, et que les comptages d’index correspondaient exactement.

Étapes pratiques

Vérifiez la taille actuelle de votre base de données :

ls -lh ~/.hermes/hermes.db

Mettez à niveau Hermes vers la dernière version incluant le schéma v23 :

hermes update

Exécutez l’optimisation :

hermes sessions optimize-storage

Vérifiez la taille une fois l’opération terminée :

ls -lh ~/.hermes/hermes.db

Si vous souhaitez un jour récupérer plus d’espace des anciennes sessions, combinez l’optimisation avec hermes sessions prune ou hermes memory clean — mais seulement après avoir sauvegardé tout ce que vous souhaitez conserver.

Points clés

La state.db de Hermes Agent était gonflée par des copies dupliquées d’index FTS5, en particulier l’index de trigrammes qui indexait les lignes de sortie d’outils.
Le layout compact v23 FTS utilise des index à contenu externe et cesse d’indexer les lignes d’outils pour la recherche par trigrammes, réduisant la base de données de 60 à 78% selon la charge de travail.
Les nouvelles installations bénéficient automatiquement du nouveau layout. Les utilisateurs existants migrent avec hermes sessions optimize-storage.
La migration est reprenable, sûre face à Ctrl-C et préserve vos données de chat à l’octet près.
La qualité de recherche est préservée ; seule la recherche de sous-chaînes CJK dans les sorties d’outils bascule vers un fallback LIKE.

Références :