Hermes Agent macht Diät: Wie das v23 FTS-Layout state.db um bis zu 78% verkleinert

Wenn du Hermes Agent seit mehr als ein paar Wochen betreibst, ist dir wahrscheinlich aufgefallen, dass ~/.hermes/hermes.db stetig wächst. Der Agent speichert jede Nachricht, jedes Tool-Ergebnis und jede Reasoning-Spur, um den Kontext über Sitzungen hinweg zu behalten. Aber die Rechnung für diesen Speicher war höher als nötig — nicht wegen der Chat-Daten selbst, sondern wegen der Art, wie die Suchindizes sie gespeichert haben.

Eine kürzlich gemergte Änderung in PR #65798 führt das kompakte v23 FTS-Layout ein. Bei stark genutzten Installationen entfernt es rund 75% des state.db-Fußabdrucks, und bei tool-intensiven Workloads liegt die Reduzierung bei nahezu 78%. Die eigentlichen Konversationsdaten bleiben unberührt; nur die Suchindizes werden kleiner und intelligenter.

In diesem Beitrag erkläre ich, was die Datenbank aufgebläht hat, wie das v23-Layout das behebt und was genau du tun musst, um davon zu profitieren.

Für den Kontext zum breiteren v0.19.0-Release siehe unsere v0.19.0 Release Notes.

Warum die Datenbank so schnell wuchs

Hermes speichert den Langzeit-Status in einer SQLite-Datenbank unter ~/.hermes/hermes.db. Jede Nachricht wird in einer messages-Tabelle abgelegt und mit zwei FTS5-Indizes für die Volltextsuche indiziert:

messages_fts — ein Porter-Stemmer-Index für englischsprachige Suche
messages_fts_trigram — ein Trigramm-Index für CJK-Teilzeichenketten-Suche

Seit der v11-Schema-Migration waren beide Indizes inline FTS5-Tabellen. Das bedeutet, jeder Index hielt seine eigene private Kopie von content || tool_name || tool_calls für jede Nachricht. Dieselben Bytes wurden dreimal gespeichert: einmal in der messages-Tabelle und einmal in jedem FTS-Index.

Ein reales Beispiel aus Issue #22478 zeigte das Ausmaß des Problems:

Komponente	Größe	% der DB
messages-Daten	99 MB	19,6%
sessions-Daten	45 MB	8,9%
FTS-Indizes	358 MB	70,8%
Sonstiges	3 MB	0,7%
Gesamt	505 MB	100%

Der Trigramm-Index allein verbrauchte 247 MB — 49% der gesamten Datenbank — weil CJK-Text weit mehr Trigramm-Token erzeugt als Englisch und weil Tool-Ausgabezeilen (role=tool) ebenfalls indiziert wurden. Tool-Ausgaben bestehen meist aus base64-Payloads, Datei-Dumps und Delegationstranskripten, die niemand mit CJK-Teilzeichenketten durchsucht.

Das ist nicht nur ein Speicherplatzproblem. Große inline-Indizes machen auch Schreibvorgänge langsamer, halten Sperren länger und können die Festplatten-I/O während intensiver Gateway-Sitzungen sättigen.

Was das v23-Layout ändert

Das kompakte v23 FTS-Layout macht drei Dinge:

External-Content-Indizes: Die FTS5-Indizes speichern keine eigenen privaten Kopien des Nachrichteninhalts mehr. Sie verweisen auf die echten Spalten in der messages-Tabelle und beseitigen so die 2–3-fache Duplizierung.
Trigramm-Index ohne Tool-Zeilen: Der Trigramm-Index überspringt Zeilen mit role='tool'. Hier befand sich der größte Teil der Aufblähung, da Tool-Ausgaben bei aktiven Agenten typischerweise ~90% der Nachrichten-Bytes ausmachen.
Optionale Migration: Bestehende Installationen behalten ihren Legacy-Index unverändert bei. Du wechselst erst zu v23, wenn du hermes sessions optimize-storage ausführst.

Die messages-Tabelle bleibt byte-identisch. Dein Chat-Verlauf, Speicher und Sitzungen werden nicht angefasst. Nur die Speicherung des Suchindex ändert sich.

Die Zahlen: Bis zu 78% kleiner

PR #65798 berichtet sowohl synthetische als auch reale Validierung:

Szenario	Vorher	Nachher
Synthetische 30k-Nachrichten-DB, 60% Tool-Zeilen	463 MB	131 MB (28%)
FTS-Anteil dieser DB	~84%	~42%
Reale 25 GB / 1,38M Nachrichten-Kopie	25 GB	~10 GB

Bei der synthetischen Datenbank schrumpft die Datenbank von 463 MB auf 131 MB — eine Reduzierung um 72%. Bei der realen Produktionskopie beträgt die Reduzierung von 25 GB auf ~10 GB 60%, mit exakten Index-Zählungen und sauberer FTS5-Integrität. Bei tool-intensiven Workloads, bei denen Tool-Zeilen dominieren, können die Einsparungen 78% erreichen, da der Trigramm-Index diese Zeilen überhaupt nicht mehr speichert.

So steigst du um

Neue Installationen, die nach dieser Änderung erstellt werden, starten automatisch mit dem v23-Layout. Wenn du Hermes bereits betreibst, führe einen einzigen Befehl aus:

hermes sessions optimize-storage

Der Befehl führt eine bewusste Vordergrund-Operation durch:

Prüft den freien Speicherplatz, bevor er startet (verweigert die Ausführung, wenn nicht genug Platz vorhanden ist).
Stuft die Legacy-Indizes in O(1)-Zeit herab.
Befüllt die neuen Indizes in 500-Zeilen-Blöcken und hält den Schreibsperren-Arbeitszyklus unter 20%, damit ein laufendes Gateway oder eine CLI-Sitzung reaktionsfähig bleibt.
Baut die alten Shadow-Tabellen blockweise ab.
Führt VACUUM aus, um den freigegebenen Speicherplatz zurückzugewinnen.
Stempelt die neue Layout-Version.

Es ist Ctrl-C-sicher und fortsetzbar. Wenn du den Vorgang unterbrichst, werden Markierungen und Rückstände beim nächsten Lauf erkannt und der Befehl setzt dort fort, wo er unterbrochen wurde. Der Agent warnt dich auch, wenn die Suchergebnisse während des Neuaufbaus unvollständig sind, damit er nicht stillschweigend fehlenden Kontext halluziniert.

Wenn du wenig Speicherplatz hast, kannst du den Vacuum-Schritt überspringen:

hermes sessions optimize-storage --no-vacuum

Nach dem Upgrade zeigt hermes update einen einzeiligen Hinweis zur Optimierung und zum erwarteten Speichergewinn an.

Wann solltest du es ausführen?

Du solltest hermes sessions optimize-storage ausführen, wenn einer dieser Punkte zutrifft:

Deine ~/.hermes/hermes.db ist über ein paar hundert Megabyte groß und der Großteil der Größe besteht aus FTS-Indizes.
Du betreibst ein Gateway mit langen, tool-intensiven Sitzungen und bemerkst Festplatten-I/O-Spitzen oder langsame Schreibvorgänge.
Du bist auf einem kleinen VPS oder Laptop mit begrenztem Speicherplatz.
Du hast Hermes gerade installiert und möchtest bestätigen, dass du bereits auf dem v23-Layout bist.

Wenn du mit Leistung und Speicherplatznutzung bereits zufrieden bist, kannst du warten. Der Legacy-Index funktioniert weiter; dies ist eine Optimierung, keine Breaking Change.

Was ist mit der Suchqualität?

Die Änderung entfernt keinen durchsuchbaren Inhalt für das, was du tatsächlich suchst. Konversationen und tool_calls/tool_name bleiben über den External-Content-Index durchsuchbar. Die CJK-Teilzeichenketten-Suche in Konversationstext funktioniert weiterhin. Der einzige Unterschied ist, dass die CJK-Teilzeichenketten-Suche innerhalb von Tool-Ausgaben auf eine LIKE-Abfrage statt auf den Trigramm-Index zurückfällt — was in Ordnung ist, da diese Art von Suche in base64-Payloads oder Datei-Dumps selten nützlich ist.

Eine unabhängige Überprüfung durch @yoniebans bei einer realen v19→v23-Migration bestätigte, dass der SHA-256-Fingerabdruck der messages-Tabelle vorher und nachher identisch war und die Index-Zählungen exakt übereinstimmten.

Praktische Schritte

Überprüfe die aktuelle Größe deiner Datenbank:

ls -lh ~/.hermes/hermes.db

Aktualisiere Hermes auf die neueste Version, die das v23-Schema enthält:

hermes update

Führe die Optimierung aus:

hermes sessions optimize-storage

Überprüfe die Größe nach Abschluss:

ls -lh ~/.hermes/hermes.db

Wenn du jemals mehr Speicherplatz aus alten Sitzungen zurückgewinnen möchtest, kombiniere die Optimierung mit hermes sessions prune oder hermes memory clean — aber nur, nachdem du alles gesichert hast, was du behalten möchtest.

Kernaussagen

Die state.db von Hermes Agent war durch doppelte FTS5-Index-Kopien aufgebläht, insbesondere durch den Trigramm-Index, der Tool-Ausgabezeilen indizierte.
Das kompakte v23 FTS-Layout verwendet External-Content-Indizes und stoppt die Indizierung von Tool-Zeilen für die Trigramm-Suche, wodurch die Datenbank je nach Workload um 60–78% schrumpft.
Neue Installationen erhalten das neue Layout automatisch. Bestehende Nutzer steigen mit hermes sessions optimize-storage um.
Die Migration ist fortsetzbar, Ctrl-C-sicher und bewahrt deine Chat-Daten byte-identisch.
Die Suchqualität bleibt erhalten; nur die CJK-Teilzeichenketten-Suche innerhalb von Tool-Ausgaben wechselt auf einen LIKE-Fallback.

Referenzen: