Build a Hermes Context Engine Plugin

Replace the default context compressor with an explicit, testable engine while preserving valid message history and session lifecycle behavior. This guide focuses on the public implementation contract; the official Hermes documentation remains the source of truth as interfaces evolve.

How the interface works

Context engine plugins implement the ContextEngine interface and replace the built-in compressor for one active session strategy at a time. They are never auto-activated: the operator selects context.engine.

Required behavior covers usage accounting, the compression decision, and compress(), which must return a valid OpenAI-format message list. The engine also maintains token, threshold, context-window, and compression-count state used by Hermes.

Optional lifecycle methods can load persisted state, flush state, clear a reset session, react to model changes, expose custom status, or add engine-specific tools.

A context engine may preserve information differently from lossy summarization, but it must still respect model context limits and session boundaries.

Practical checklist

Define the information-preservation goal before choosing a data structure.
Make compress() deterministic enough to test and always return valid role/content messages.
Reset per-session state on /new or /reset.
Recalculate budgets after model switches.
Keep engine tools narrow and return structured errors for unknown calls.

Common pitfalls

Auto-activating an installed engine without operator choice.
Returning custom internal nodes instead of model-ready messages.
Forgetting token counters or model-switch updates.
Persisting one session’s context into another without an explicit design.

Verification steps

Run the ABC contract tests and message-shape tests.
Select the engine explicitly, start a fresh session, and inspect status.
Force the compression threshold with synthetic history and verify preserved facts.
Reset the session and confirm engine-specific state is cleared.

Official reference

https://hermes-agent.nousresearch.com/docs/developer-guide/context-engine-plugin