Das Gate, das sich weigert zu compacten: was compression.checkpoint_required wirklich schützt

Drei Stunden in einer Session füllt sich das Kontextfenster, Hermes compacted, und du arbeitest weiter. Zwei Tage später fragst du, warum eine Entscheidung gefallen ist, und bekommst eine selbstsichere Antwort, die sich als Zusammenfassung einer Zusammenfassung entpuppt. Kaputt ist genau genommen nichts — aber das, was du gebraucht hättest, stand nirgends dauerhaft, und das Transkript, das es enthielt, ist umgeschrieben.
Diesen Fehler soll compression.checkpoint_required verhindern. Es ist ein grobes Werkzeug: Mit scharfem Gate compacted Hermes lieber gar nicht, als deine Historie ohne Backup umzuschreiben.
Die Idee in einem Satz
Compaction ist per Definition verlustbehaftet — aus einem langen Transkript wird eine kürzere Zusammenfassung plus ein aktueller Rest. Das Gate sagt: Bevor diese Umschreibung passiert, muss jemand eine dauerhafte Kopie des unkomprimierten Transkripts abgelegt und mir gesagt haben, dass sie abgelegt ist.
Wer ist „jemand“? Ein Memory-Provider-Plugin. Nicht der Summarizer, nicht die Session-Datenbank, nicht das Modell.
Einschalten
compression:
checkpoint_required: true # Standard: false
oder gleichwertig:
hermes config set compression.checkpoint_required true
hermes config get compression.checkpoint_required
Das ist die ganze Operator-Oberfläche. Alles Folgende dreht sich darum, was es ändert, denn die Konsequenzen sind größer, als ein einzelnes Boolean vermuten lässt.
Was das Gate blockiert
Mit scharfem Gate scheitert ein Compaction-Versuch fail-closed vor jeder verlustbehafteten Umschreibung:
- das unkomprimierte Transkript bleibt exakt erhalten;
- der Versuch endet mit
BLOCKED_MISSING_PREREQUISITEund einer Begründung, die benennt, was fehlte; - er kann wiederholt werden, sobald sich dein Archiv-Store erholt hat.
Das Gate bindet außerdem jede Compaction-Instanz, nicht nur den Hermes-Summarizer. Serverseitige native Compaction wird unterdrückt, solange das Gate scharf ist, Post-Turn-Micro-Compaction wird beim Agent-Init zwangsweise abgeschaltet (sie saugt alte Austausche in eine rollierende Zusammenfassung, ohne Checkpoint-Hook in ihrem Pfad), und der API-Modus codex_app_server wird beim Start verweigert — diese Runtime compacted ihren eigenen Thread ohne wahrhaftige Pre-Compaction-Grenze, ein geforderter Checkpoint lässt sich dort also nicht garantieren. Der checkpoint-fähige Hermes-Compressor bleibt die einzige verlustbehaftete Instanz.
Der letzte Punkt ist der ehrliche Kompromiss: Das Gate einzuschalten macht Compaction strenger und auf manchen Runtimes unmöglich. Es ist eine Datenintegritäts-Einstellung, keine Performance-Einstellung.
Was ein Provider implementieren muss
Der Vertrag ist klein und explizit. Ein Provider steigt ein, indem er API-Version 2 deklariert:
from agent.memory_provider import MemoryProvider
class MyArchivingProvider(MemoryProvider):
pre_compress_checkpoint_api_version = 2
def on_pre_compress(self, messages, *, require_checkpoint=False):
ids = self._archive(messages) # muss dauerhaft sein, bevor die Methode zurückkehrt
return f"checkpoint: {ids}" # wird in den Summary-Prompt weitergereicht
require_checkpoint spiegelt die Einstellung des Operators: Ist es True, blockiert ein Raise aus dieser Methode die verlustbehaftete Umschreibung. Zurückkehren heißt „die dauerhafte Kopie ist abgelegt“ — Teilerfolg ist also keine Option, und die Docs sagen explizit, dass du bei jedem Fehler raisen musst, statt optimistisch zurückzukehren.
Provider der Version 2 bekommen außerdem normalisierte direkte Evidenz statt der rohen Liste: nur Text-Zeilen von User und Assistant. Tool-Ergebnisse, System-Nachrichten, das tool_calls-Payload von Assistant-Nachrichten und frühere Compaction-Zusammenfassungen werden hostseitig gefiltert. Frühere Zusammenfassungen werden über einen persistenten Marker erkannt, sodass eine fortgesetzte Session niemals abgeleitete Zusammenfassungen in dein Archiv zurückfüttert, als wären sie originale Evidenz.
Eine weitere Anforderung, die Leute überrascht: Checkpoints müssen idempotent sein. Nach einem Fail-Closed-Block ruft der nächste Versuch on_pre_compress() erneut mit demselben Transkript auf, und ein leicht gewachsenes Transkript erzeugt weitgehend überlappende Evidenz. Schlüssel deine Archiv-Writes nach Inhalt — etwa über einen Transkript-Digest — und upsert, sonst stapeln sich bei Wiederholungen Duplikate.
Was sich am 6. November geändert hat
Das Gate kam früher, hatte aber eine scharfe Kante, die einen Nachtrag brauchte (PR #149763, gemergt am 6. November 2026). Zwei Probleme:
- Subagenten und Forks wurden mit deaktiviertem Memory gebaut.
delegate_task, der Curator, der Batch-Runner und Feishu-Comment-Turns führen jeweils ihr eigenes Transkript, und diese Forks wurden mitskip_memory=Truekonstruiert. Mit scharfem Gate scheiterte ihre erste Compaction mitBLOCKED_MISSING_PREREQUISITE— nicht weil mit deinem Provider etwas falsch war, sondern weil der Fork nie einen bekommen hatte. - Das proaktive Pruning von Tool-Ergebnissen ignorierte das Gate. Es verwirft große Tool-Ergebnisse, um Tokens ohne LLM-Call zurückzugewinnen, und verwarf sie ohne vorherigen Checkpoint — es löschte also still Evidenz, die das Gate schützen sollte.
Beides ist behoben. Forks behalten jetzt den Provider, solange das Gate scharf ist, und der Host unterdrückt ihre Writes und ihren Recall (sie laufen in einem Subagenten-Kontext, statt sich als du auszugeben). Das Pruning wird an seiner Aufrufstelle zurückgehalten, bis ein Checkpoint existiert.
Wenn du das Gate vor diesem Fix eingeschaltet hast und Subagenten-Turns bei ihrer ersten Compaction gestorben sind, liegt es daran — und es lohnt sich, es jetzt erneut zu versuchen.
Solltest du es einschalten
Stell eine Frage: Ist ein compacted Transkript für dich heute wiederherstellbar?
Lautet deine Antwort „die Zusammenfassung reicht“, lass das Gate aus. Es ist standardmäßig aus, und keiner der mit Hermes gebündelten Provider bewirbt Checkpoint-API v2 — aktivierst du das Gate ohne v2-Provider, blockierst du jeden Compaction-Versuch, den manuellen wie den automatischen. Der Agent-Init loggt eine Warnung, die den aktiven Provider nennt, und jede Verweigerung nennt compression.checkpoint_required als den Schlüssel zum Abschalten — es scheitert also laut, nicht still.
Lautet deine Antwort „wir haben ein Archiv jeder Konversation und brauchen es vollständig“, verwandelt das Gate einen stillen Verlust in einen lauten Stopp, was in einem regulierten oder langlebigen Deployment meist genau das ist, was du willst. Kombiniere es mit einem Provider, der per Digest upsertet, und plane ein, dass das Compaction-Verhalten deterministisch wird statt Best-Effort.
Für das Drumherum — wie viel deines Fensters Compaction zurückgewinnt und wo die Tokens tatsächlich hingehen — ist der Context-Token-Optimization-Guide die passende Lektüre. Und wenn du sowieso upgradest, listet die v0.23.0-Release-Seite die anderen Compression-Änderungen in diesem Zyklus, inklusive optional vorbereiteter Compaction, die die nächste Zusammenfassung im Hintergrund schreibt.