The gate that refuses to compact: what compression.checkpoint_required actually protects


Three hours into a session, the context window fills up, Hermes compresses, and you keep working. Two days later you ask why a decision was made and get a confident answer that turns out to be a summary of a summary. Nothing is corrupt exactly — but the thing you needed was never written down anywhere durable, and the transcript that held it has been rewritten.

That is the failure compression.checkpoint_required exists to prevent. It is a blunt instrument: with the gate armed, Hermes would rather refuse to compact than rewrite your history without a backup.

The idea in one sentence

Compaction is lossy by definition — a long transcript becomes a shorter summary plus a recent tail. The gate says: before that rewrite happens, somebody must have committed a durable copy of the uncompressed transcript, and told me it was committed.

Who is “somebody”? A memory provider plugin. Not the summarizer, not the session database, not the model.

Turning it on

compression:
  checkpoint_required: true   # default: false

or, equivalently:

hermes config set compression.checkpoint_required true
hermes config get compression.checkpoint_required

That is the whole operator surface. Everything below is about what it changes, because the consequences are larger than one boolean suggests.

What the gate blocks

With the gate armed, a compaction attempt fails closed before any lossy rewrite:

  • the uncompressed transcript is preserved exactly as it is;
  • the attempt errors with BLOCKED_MISSING_PREREQUISITE and a reason naming what was missing;
  • it can be retried once your archive store recovers.

The gate also binds every compaction authority, not just the Hermes summarizer. Server-side native compaction is suppressed while the gate is armed, post-turn micro-compaction is forced off at agent init (it absorbs old exchanges into a rolling summary with no checkpoint hook in its path), and the codex_app_server API mode is refused at startup — that runtime compacts its own thread with no truthful pre-compaction boundary, so a required checkpoint cannot be guaranteed there. The checkpoint-aware Hermes compressor stays the only lossy authority.

That last part is the honest trade: turning the gate on makes compaction stricter and, on some runtimes, impossible. It is a data-integrity setting, not a performance setting.

What a provider has to implement

The contract is small and explicit. A provider opts in by declaring API version 2:

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)   # must be durable before returning
        return f"checkpoint: {ids}"     # forwarded into the summary prompt

require_checkpoint mirrors the operator’s setting: when it is True, raising from this method is what blocks the lossy rewrite. Returning means “the durable copy is committed” — so partial success is not an option, and the docs are explicit that you must raise on any failure rather than return optimistically.

Version 2 providers also receive normalized direct evidence instead of the raw list: user and assistant text rows only. Tool results, system messages, the tool_calls payload of assistant messages, and prior compaction summaries are filtered host-side. Prior summaries are recognized through a persistent marker, so a resumed session never feeds derivative summaries back into your archive as if they were original evidence.

One more requirement that surprises people: checkpoints must be idempotent. After a fail-closed block, the next attempt calls on_pre_compress() again with the same transcript, and a transcript that grew slightly produces largely overlapping evidence. Key archive writes by content — a transcript digest, for example — and upsert, or retries will pile up duplicates.

What changed on November 6

The gate shipped earlier, but it had a sharp edge that took a follow-up to fix (PR #149763, merged November 6, 2026). Two problems:

  • Subagents and forks were built with memory disabled. delegate_task, the curator, the batch runner and Feishu comment turns each run their own transcript, and those forks were constructed with skip_memory=True. With the gate armed, their first compaction failed with BLOCKED_MISSING_PREREQUISITE — not because anything was wrong with your provider, but because the fork was never given one.
  • The proactive tool-result prune ignored the gate. It drops large tool results to reclaim tokens without an LLM call, and it was dropping them with no checkpoint first — quietly deleting evidence the gate was supposed to protect.

Both are fixed. Forks now keep the provider while the gate is armed, and the host suppresses their writes and recall (they run under a subagent context rather than pretending to be you). The prune is withheld at its call site until a checkpoint exists.

If you turned the gate on before that fix and saw subagent turns dying on their first compaction, this is why — and it is worth retrying now.

Should you turn it on

Ask one question: is a compacted transcript recoverable for you today?

If your answer is “the summary is enough”, leave the gate off. It is off by default, and none of the providers bundled with Hermes advertise checkpoint API v2 — enable the gate without a v2 provider and you block every compaction attempt, manual and automatic. Agent init logs a warning naming the active provider, and each refusal names compression.checkpoint_required as the key to disable, so it fails loudly rather than silently.

If your answer is “we have an archive of every conversation and we need it to be complete”, the gate converts a silent loss into a loud stop, which is usually what you want in a regulated or long-lived deployment. Pair it with a provider that upserts by digest, and budget for the fact that compaction behaviour becomes deterministic rather than best-effort.

For the surrounding picture — how much of your window compaction reclaims, and where the tokens actually go — the context token optimization guide is the companion read. And if you are upgrading anyway, the v0.23.0 release page lists the other compression changes in this cycle, including opt-in prepared compaction that writes the next summary in the background.