Hermes Compaction: Tune The Trigger, Tail And prepare_ahead

Hermes compaction is the step where Hermes Agent squeezes a long conversation into a structured summary so the session keeps running inside your model's context window.

It fires on its own at half the window by default, you can force it with /compress, and since 2 November 2026 it can write the next summary early in the background.

That new switch is compression.prepare_ahead, it ships off, and it landed in the stable v0.22.6 tag.

Here is the order I would set every compaction key in, with each config block copied straight from the official docs.

If you would rather have my team map out where an always-on agent fits your business, book a free SEO strategy session.

How Hermes Compaction Works: Four Phases, One Summary Call

The built-in engine is called compressor, and the developer guide on context compression splits each run into four phases.

Phase 1 is free: old tool results longer than 200 characters outside the protected tail get swapped for [Old tool output cleared to save context space].

Phase 2 draws the lines: a protected head, a middle that gets summarised, and a tail that stays word for word.

Phase 3 sends the middle to a separate summary model with a fixed template: Goal, Constraints & Preferences, Progress, Key Decisions, Relevant Files, Next Steps and Critical Context.

Phase 4 stitches head, summary and tail back together and cleans up any tool call that lost its result.

On the next run the old summary is handed back to the model to update, so finished work moves from "In Progress" to "Done" instead of being rewritten from scratch.

The docs show a worked example where 45 messages at roughly 95K tokens come out as 25 messages at roughly 45K.

Step 1: Read The Trigger Before You Change It

Every compression key lives in ~/.hermes/config.yaml, and the configuration reference says there are no environment variables for them.

The docs' own minimal setup is just this:

compression:
  enabled: true
  threshold: 0.50

threshold: 0.50 means compaction fires once the prompt reaches half of the main model's context window.

It is always the main model's window, never the summary model's.

If you want a hard ceiling, set threshold_tokens: the docs give 256000 as the way to compact a 1M-window model at 256K instead of 500K.

Hermes uses whichever of the two triggers is lower, and that cap survives model switches and fallbacks.

Watch the context pressure bar while you test: it turns cyan at 60% of the way to the trigger and bold yellow at 85%.

Switch between models a lot? Use model_thresholds, which matches on part of the model name, and the longest key wins:

compression:
  threshold: 0.50
  model_thresholds:
    "glm-5.2": 0.40
    "glm-5.2-1M": 0.25
    "claude-sonnet": 0.35
    "openai-codex:astra": 0.85   # only on the Codex OAuth route (272K cap)

Step 2: Give The Summary A Model With Enough Window

The summary is its own LLM call, configured under auxiliary.compression, not under compression.

auxiliary:
  compression:
    model: ""                                       # Empty = use main chat model. Override with e.g. "google/gemini-3-flash-preview" for cheaper/faster compression.
    provider: "auto"                                # Provider: "auto", "openrouter", "nous", "codex", "main", etc.
    base_url: null                                  # Custom OpenAI-compatible endpoint (overrides provider)

An empty model means Hermes reuses your main chat model.

To pin a provider, the docs use this block:

auxiliary:
  compression:
    provider: nous
    model: gemini-3-flash

Here is the trap that wrecks most setups.

The developer guide says your summariser's window must match or exceed the main model's, since the entire middle ships in a single request.

If it is smaller, the call errors and the middle turns are dropped without a summary.

The docs call that the most common cause of poor compaction quality, so check the window before you pick a cheap summariser.

🔥 Want Hermes compaction already tuned inside a working agent? Inside the AI Profit Boardroom you get step-by-step video trainings, the installable Agent OS with Hermes wired in, four coaching calls a week and 3,400+ members running long agent sessions every day. → Join the AI Profit Boardroom

Step 3: Size The Uncompressed Tail

The tail is the stretch of recent messages that never gets summarised.

These are the tail and head keys, line for line from the full reference:

compression:
  threshold: 0.50                                   # Compress at this % of context limit
  threshold_tokens: null                            # Absolute token cap (optional) — takes lower of ratio vs absolute
  target_ratio: 0.20                                # Fraction of threshold to preserve as recent tail
  protect_last_n: 20                                # Min recent messages to keep uncompressed
  protect_first_n: 3                                # Non-system head messages pinned across compactions (0 = pin nothing)
  in_place: true                                    # Compact on the same session id (no rotation) — see below
  idle_compact_after_seconds: 0                     # Opt-in idle compaction (0 = disabled) — see below
  prepare_ahead: false                              # Opt-in: prepare the next summary in the background — see below

protect_last_n: 20 is the floor on recent messages kept verbatim.

tail_mode: lean is the default, and it keeps a tail of 2.5% of the window, clamped between 10K and 25K tokens and never above 20% of the window.

Lean mode carries continuity in the summary instead: a detailed session log, an anchor index of PR numbers, SHAs, paths and error strings, every real user message quoted, and a session_search pointer to dig back into anything summarised.

On 500K-token real sessions the docs report about 49K tokens kept with lean against about 162K with legacy.

If tool output crowds out your instructions, raise min_tail_user_messages from 1 to 3 so the last three real user turns stay word for word.

Step 4: Keep One Session ID With in_place

in_place: true is the default and I would leave it alone.

Compaction rewrites the live message list on the same session ID, and the old turns are soft-archived, still searchable through session_search, never deleted.

The developer guide says this fixed a cluster of rotation bugs, including lost /goal state and orphaned sessions.

Only set in_place: false if a hook or script of yours depends on the old behaviour where each compaction made a new linked session ID.

Step 5: Switch On prepare_ahead

Here is the new line exactly as the full reference prints it:

compression:
  prepare_ahead: false                              # Opt-in: prepare the next summary in the background — see below

Change false to true to opt in.

It arrived in commit 32a636bc8d and shipped in the v0.22.6 release on 2 November 2026.

Once the last provider-reported prompt count sits within 12% below the trigger, the turn loop starts one background pass, either before a tool batch runs or at the end of a turn.

That pass plans the same window a normal compaction would and runs the same summariser on a copy, so your live transcript, system prompt and prompt cache stay untouched.

When automatic compaction fires and the summarised messages are still the same ones, Hermes splices in the ready summary instead of making a fresh call.

Every message that arrived after the pass started stays in the uncompressed tail.

If the pass is still writing, compaction waits for it within the normal time limit rather than starting a second summary.

The flag is read when the agent is built, so it takes effect on the next session or the next gateway agent rebuild.

Where prepare_ahead Gives You Nothing

The developer guide lists every case that still runs inline, exactly as if the flag were off:

Manual /compress and focus compaction.
Provider-overflow recovery.
Plugin context engines, Codex app-server sessions and native Responses compaction.
Micro-compaction.
A candidate that no longer matches, for example after a dropped message, an inserted one or a rewind.

Turn-end passes are also skipped for cron runs, delegated children and one-shot hermes chat -q or -z sessions, since those agents end with the turn.

A -q --resume chain builds a fresh agent every run, so it never gets a head start either.

If your memory provider adds context to compaction summaries, the option switches itself off after the first compaction because every prepared summary would be thrown away.

And the state is in memory only: a gateway eviction or a restart just means the next compaction runs inline.

Step 6: Run /compress When You Want It Now

Type /compress to compact on demand.

It runs under context_timeout_seconds, which defaults to 120 seconds of no summary output before Hermes gives up on a silent summariser.

It also clears the per-session failure cooldown and retries, which makes it the fastest way to unstick a session after the summary backend had a bad patch.

Its feedback always shows on chat platforms, even when routine notices are hidden.

Step 7: Add Idle Compaction For Chat Threads

idle_compact_after_seconds is off at 0.

The docs give 1800 as the example: a thread that comes back after 30 minutes of quiet gets compacted before the first reply, so it stops re-reading stale history on every turn.

It never fires when the context already sits at or below threshold × target_ratio.

On Telegram, Discord or Slack, automatic compaction is silent by design.

Set progress_notices: true if you want to see "Compacting context…" and the completion notice in the chat.

Long summary calls stream like any other reply, so if your gateway drops slow streams, read my Hermes agent streaming setup before you blame compaction.

Step 8: Prune Tool Output Without Any LLM Call

On big-window models the 50% trigger rarely fires, so bulky terminal dumps and file reads get re-sent turn after turn.

proactive_prune_tokens fixes that with a no-LLM prune, off at 0, and the docs suggest 48000 to turn it on.

It dedupes identical results, summarises older oversized tool results, protects the last protect_last_n messages and never touches tool-call arguments.

It only runs under the built-in compressor engine.

Micro-Compaction: Pay The Bill Every Turn Instead

The micro-compaction guide describes a different rhythm: after each finished turn, Hermes folds the single oldest unsummarised exchange into one running summary.

compression:
  micro_compact: true             # default: false
  micro_compact_every_n_turns: 1  # cadence — how often a pass runs
  micro_compact_defrag_threshold_tokens: 2000

It is off by default.

What you typed is never summarised, the head and the tail stay verbatim, and the running summary is defragged once it passes 2,000 tokens.

The catch is the prompt cache: every pass rewrites history the provider already saw, so the cached prefix breaks every turn instead of once per batch compaction.

Raise micro_compact_every_n_turns to 5 and you get a fifth of the breaks.

The guide recommends a small, fast, non-reasoning instruct model for these passes, since each one runs at the end of a turn.

📞 Running agents for clients and not sure which compaction settings fit? Book a free SEO strategy session and my team will look at what you run and where an agent saves you hours. → Get your free strategy session

Plugin Context Engines Swap Out The Whole Thing

The context engine section lets a plugin replace the built-in summariser.

context:
  engine: "compressor"    # default — built-in lossy summarization

To move to a plugin engine such as LCM for lossless context management, you name it:

context:
  engine: "lcm"          # must match the plugin's name

Plugin engines are never switched on for you, and you can browse them under hermes plugins → Provider Plugins → Context Engine.

Remember that prepare_ahead and the proactive prune do nothing once a plugin engine is in charge.

Update To v0.22.6 Before You Look For The Key

The release notes list four routes:

CLI: run hermes update or re-run the installer one-liner.
Microsoft Store app: it updates through the Store.
Desktop from the .exe or .dmg installer: no change in this release, it updates with the next bundled release.
Docker and Hermes Cloud: nousresearch/hermes-agent:stable.

On a running gateway, edits to any compression.* key apply on the next message with no restart, according to the configuration docs.

The Gotchas I Would Check First

A summary model with a smaller window than your main model silently drops the middle.
Delegated subagents compact at the parent's threshold; delegation.compression_threshold_tokens caps them separately and stays off at 0.
prepare_ahead spends an auxiliary summary call that may never be used.
Skills summarised away get a [SKILL_PRUNED] marker, so the agent reloads them with skill_view before relying on them.
Legacy keys like compression.summary_model migrate to auxiliary.compression.* on first load.

For more on how children compact, the delegation docs cover the subagent side.

Want the full walkthroughs on video and the Agent OS that runs it? Join the AI Profit Boardroom.

Also On Our Network

FAQ: Hermes Compaction

Where do I turn on prepare_ahead?

In ~/.hermes/config.yaml under compression. Set prepare_ahead to true; it is false by default and takes effect on the next session or gateway agent rebuild.

Does /compress use the prepared summary?

No. Manual /compress always runs inline. The prepared summary is only spliced in at the next automatic threshold compaction.

Why did my compaction lose half the conversation?

The most common cause in the docs is a summary model with a smaller context window than the main model. The call fails and the middle is dropped without a summary.

Do I need to restart the gateway after editing compression keys?

No. The configuration docs say compression.* edits on a running gateway apply on the next message.

Is micro-compaction the same as prepare_ahead?

No. Micro-compaction folds one exchange per turn into a running summary and breaks the prompt cache each pass. prepare_ahead writes one batch summary early and leaves the cache alone.

📺 Video notes + links to the tools 👉

🎥 Learn how I make these videos 👉

🆓 Get a FREE AI Course + Community + 1,000 AI Agents 👉

About Julian

I'm Julian Goldie, an SEO entrepreneur, author and founder of the AI Profit Boardroom, which has 3,400+ members.

I help business owners scale with AI agents, automation and SEO.

I've built a 7-figure SEO and link building agency, Goldie Agency, with a team of 70+ SEO experts.
I've grown a YouTube channel to 400,000+ subscribers.
I wrote "Link Building Mastery".
My Udemy courses have taught over 29,000 students.

→ Get my best AI training inside the AI Profit Boardroom

Set the trigger, size the tail, then flip prepare_ahead on one long-running session first, and if you want help planning the rollout, book a free SEO strategy session before you change Hermes compaction everywhere.