Hermes Agent
Open navigation menu

How-To Guide

Configure Context Compression — Handle Long Conversations

Set Hermes context compression thresholds, understand lean vs legacy tails, preserve session history, and verify recall without resetting a working conversation.

Quick answer

Run /context, then edit the owning profile’s config.yaml: compression.enabled: true and compression.threshold: 0.50 are the documented baseline. Current docs default to tail_mode: lean; target_ratio is not a promise that the whole request will shrink to 20%. Use /compress once, then verify the goal, constraints and next action against saved notes. Do not delete memory or reset a healthy session merely to apply these settings.

Compression controls what the model sees next, not how much RAM your server has or which facts are saved permanently. This guide separates the trigger, retained conversation and auxiliary model so you can change one thing at a time. Instructions follow the official configuration reference, checked October 15, 2026; older installations may expose different defaults.

Get Hermes running without the setup →

$49/mo or $39/mo billed yearly · AI included · 14‑day guarantee

Before you start:

  • ☑A working Hermes installation and access to the profile that owns the affected session; record hermes --version before comparing settings.
  • ☑A non-sensitive long conversation and a saved note containing its goal, exact file or artifact path, unresolved constraint and next action.
  • ☑Access to the configured model provider; compression itself makes an auxiliary model request and can incur usage charges.

Steps

  1. 1

    Identify the context that is actually growing

    Run /context and /context all in the affected conversation. Record the large categories before changing anything. If tools, project instructions or file output dominate, follow the token-overhead diagnosis; repeated compression is not a substitute for narrowing oversized inputs.

  2. 2

    Find the owning configuration and set the trigger

    Run hermes config path under the same account/profile that owns the conversation, then use hermes config edit. Under the existing compression mapping, set enabled: true and threshold: 0.50; do not paste dotted keys as a new YAML root or duplicate the mapping. The ratio controls when compression starts, not the final request size. For another profile, use hermes -p PROFILE config path and hermes -p PROFILE config edit with its real name.

  3. 3

    Use an absolute token trigger when the window varies

    Optionally set threshold_tokens inside that same mapping. Hermes uses the lower of the ratio-based trigger and this token count, clamped to the model window. Leave it null to use only the ratio. A token trigger is not a dollar budget: output, cached input, auxiliary calls and retries still need separate cost accounting.

  4. 4

    Choose lean or legacy retention deliberately

    Current docs set tail_mode: lean by default. Lean retains a smaller bounded recent tail plus summary/recovery pointers. legacy uses target_ratio as a fraction of the compression threshold for the verbatim tail, not a fraction of the whole model window and not a hard total-output target. Do not change both the trigger and tail mode in one comparison; first verify which mode your installed version uses.

  5. 5

    Protect the right messages and keep the session ID

    The documented protect_last_n: 20 protects recent messages. protect_first_n: 3 pins non-system head messages; the system prompt is preserved separately. Setting the latter to zero is an intentional choice for rolling sessions, not a general optimization. Leave in_place: true to keep the session ID and soft-archive pre-compression turns. For detailed earlier evidence, use session search rather than assuming the summary contains everything.

  6. 6

    Check the auxiliary route before buying more capacity

    The summarizer is configured under auxiliary.compression, separately from the compression mapping. Leave model empty for the documented main-model default or choose a supported route with enough context for the material it must summarize. Inspect provider credentials, balance and timeout before changing hardware. The provider fallback guide explains route recovery; do not send sensitive history to an unapproved fallback provider. Before adding capacity, distinguish a request-format error from rejected credentials. Current compression failure docs separate transcript-preserving aborts from specific degraded fallback paths; record which outcome occurred.

  7. 7

    Apply settings without an unnecessary reset

    Current official docs say a running gateway applies compression.* and model.context_length edits on the next message by rebuilding the cached agent. That is not a promise that every setting or older release hot-reloads. Record the session ID, send one harmless continuation, and check /context again. Use /new for a deliberate new task boundary, not as the default way to apply these compression settings.

  8. 8

    Verify useful recall, not just a smaller meter

    Save the goal, artifact path, constraint and next action, run /compress once, then ask Hermes to restate those four items and continue one bounded step. Compare against the saved artifact, not the summary’s own confidence. Recover missing detail from session search or the handoff checklist. This is a proposed acceptance test, not a measured recall benchmark.

  9. 9

    Separate durable memory and hosting decisions

    Use the memory setup test for facts that should survive a new session. If compression fails or a conversation disappears, use memory and session recovery before touching storage. Self-hosted versus managed operation is a maintenance decision: more hosting RAM does not enlarge a remote model’s context window. This independent guide promotes FlyHermes commercially; managed hosting does not remove model limits or provider charges.

Pro Tips

  • 💡Change one control at a time and retain a copy of the previous configuration. A smaller context is useful only if the next task still completes correctly.
  • 💡Do not raise the declared model context length beyond what the provider actually accepts. A larger configuration number does not grant a larger model window.
  • 💡Use the current slash-command reference for your interface. Compression summarizes the live context; durable memory and searchable session history remain separate.
  • 💡Preserve temporary task evidence in files or a handoff, not automatically in MEMORY.md. Durable memory should hold stable facts, not every old tool result.

Troubleshooting

❌ The context is still large after compression

✅ Inspect /context all. System instructions, tool schemas, pinned messages, recent turns and the summary can still consume space. target_ratio is a tail-retention control, not a guaranteed final size. Reduce the largest avoidable category and rerun the same acceptance check.

❌ Compression starts earlier than expected

✅ Check both threshold and threshold_tokens in the owning profile. The lower trigger wins. Verify the active model’s real context limit and any existing override before changing the ratio.

❌ The summarizer stalls or fails

✅ Check the auxiliary provider and its logs for authentication, credits, context rejection or timeout. Current docs distinguish inactivity budgets from total ceilings and gateway turn-hold limits; increasing every timeout can hide a broken route. Recover the route first, preserve the session, then try one manual compression.

❌ The answer forgets an exact path or old decision

✅ Compare with the saved handoff and recover the original turn using session search. A successful compression can still be lossy. Restore the missing evidence before resuming work; do not interpret a smaller context meter as proof of correctness.

❌ A tool loop continues with plenty of free context

✅ Stop treating it as a compression problem. Reproduce one tiny task in a fresh test session with the same model and tools, then vary one factor. Preserve the original session and use the memory/context troubleshooting guide to distinguish tool, runtime and provider failures.

❌ OpenAI Responses request is missing input

✅ Preserve the session and record the build before retrying. PR 139050 repairs an auxiliary Relay codec mismatch; it merged after v0.22.2 was published and our October 20 source check found it absent from that tag. More provider credit does not fix the request format. Follow the compression failure diagnosis, verify release contents, and only use another summary provider when its billing and access to this conversation are authorized.

❌ Compression aborted with revoked OAuth

✅ Repair the credential used by auxiliary.compression through that provider or plugin’s supported account flow. The visible main-chat model may use another route. Do not delete memory or treat the Codex missing-input fix as a repair for a revoked token. Retry one compression after authentication is restored and verify the saved goal, artifact path, constraint and next action.

FAQ

What is the default Hermes compression tail mode?

The current official configuration reference defaults tail_mode to lean. Older configurations may retain legacy explicitly; inspect the owning profile and installed version rather than assuming an upgrade changed it.

Does target_ratio 0.20 mean the whole prompt becomes 20% of the context window?

No. In legacy mode it describes the recent verbatim tail relative to the compression threshold. Lean uses its own bounded tail behavior. System instructions, pinned messages and the summary also occupy context.

How do threshold and threshold_tokens interact?

The lower trigger applies: the ratio-based threshold or the optional absolute token count. Leaving threshold_tokens null disables the absolute trigger. Neither control is a dollar spending cap.

Do I need to reset the gateway conversation after editing compression settings?

Current official docs say compression and model.context_length changes apply on the next gateway message without a reset or session rotation. Verify behavior on the installed release; this does not cover arbitrary other configuration changes.

Does in-place compression delete the old session?

No. It keeps the session ID and soft-archives pre-compression turns for search. The active summary is still lossy, so verify important details against original artifacts or retrieved history.

Will a bigger VPS fix a model context-limit error?

Not when the model runs through a remote provider with its own context limit. Host RAM and the model request window are different constraints. Check the actual error before changing the hosting plan.

Should I keep retrying compression when it says missing input?

No. Preserve the session and diagnose the request-format boundary. The repair in PR 139050 is not in the v0.22.2 source checked October 20, 2026. Confirm your actual build or select an authorized summary route, then run one bounded retry and recall check.

Related Guides

hermes agent token overheadhermes agent memory context troubleshootingset up hermes memoryai agent session handoff checklisthermes agent provider fallbacks