feat: pluggable context engine slot (enabling LCM and custom compaction) by stephenschoettler · Pull Request #5700 · NousResearch/hermes-agent

stephenschoettler · 2026-04-07T02:02:12Z

What

Adds a context engine plugin slot so the built-in ContextCompressor can be replaced by third-party engines via the plugin system — the same pattern OpenClaw uses with its contextEngine slot.

This is the foundation for Lossless Context Management (LCM) as a plugin, without patching core.

Why

The current ContextCompressor is hardwired — there is no way for a plugin to replace compaction logic
LCM (and future context engines) need to control what stays in the active window
PR feat(lcm): Lossless Context Management — never lose a message again #4033 patches LCM directly into core (12 modules under agent/lcm/). A plugin slot is cleaner: small core change, engine logic lives in its own repo
Mirrors how OpenClaw handles this with lossless-claw

Changes

Commit 1: ContextEngine ABC (`agent/context_engine.py`)

New abstract base class defining the pluggable interface:

Required: name, update_from_response(), should_compress(), compress()

Optional (with defaults): on_session_start(), on_session_end(), on_session_reset(), get_tool_schemas(), handle_tool_call(**kwargs), get_status(), update_model()

ContextCompressor now inherits from ContextEngine as the default implementation. Zero behavior change.

Commit 2: Plugin slot wiring

PluginContext.register_context_engine(engine) — plugins call this in register(ctx)
PluginManager._context_engine — stores the registered engine (single engine rule, like memory providers)
run_agent.py — checks for a plugin engine at init, falls back to ContextCompressor
reset_session_state() — uses engine.on_session_reset() instead of poking internal attributes

Commit 3: Full engine lifecycle wiring

Tool injection — engine tool schemas (e.g. lcm_grep, lcm_describe, lcm_expand) injected into the agent tool surface after compressor init
Session lifecycle — on_session_start() called with session_id, hermes_home, platform, model
Tool dispatch — engine tool calls routed through handle_tool_call(**kwargs) before the regular handler, with live messages passed via kwargs so engines can ingest current-turn data
handle_tool_call signature — ABC updated to accept **kwargs (backward compatible)

Tests

55 tests in the PR (34 existing compressor + 19 new engine/slot + 2 plugin tests) — all passing
35 tests in the hermes-lcm plugin — all passing
90 total across both repos, 0 regressions

Tested End-to-End

Verified on a live Hermes install with the hermes-lcm plugin:

✅ Plugin loads, LCMEngine replaces ContextCompressor
✅ Agent responds normally (no regression)
✅ LCM tools visible to agent and callable
✅ Current-turn messages searchable via lcm_grep
✅ Messages persisted in immutable SQLite store
✅ Compaction fires and creates DAG summary nodes (1922 → 428 tokens, 78% reduction)

Companion

The first plugin built against this slot: hermes-lcm — Lossless Context Management as a standalone installable plugin.

Usage (for plugin authors)

def register(ctx):
    from my_engine import MyContextEngine
    engine = MyContextEngine(...)
    ctx.register_context_engine(engine)

Drop in ~/.hermes/plugins/my-engine/, restart Hermes, done.

…om it Introduces agent/context_engine.py — an abstract base class that defines the pluggable context engine interface. ContextCompressor now inherits from ContextEngine as the default implementation. No behavior change. All 34 existing compressor tests pass. This is the foundation for a context engine plugin slot, enabling third-party engines like LCM (Lossless Context Management) to replace the built-in compressor via the plugin system.

- PluginContext.register_context_engine() lets plugins replace the built-in ContextCompressor with a custom ContextEngine implementation - PluginManager stores the registered engine; only one allowed - run_agent.py checks for a plugin engine at init before falling back to the default ContextCompressor - reset_session_state() now calls engine.on_session_reset() instead of poking internal attributes directly - ContextCompressor.on_session_reset() handles its own internals (_context_probed, _previous_summary, etc.) - 19 new tests covering ABC contract, defaults, plugin slot registration, rejection of duplicates/non-engines, and compressor reset behavior - All 34 existing compressor tests pass unchanged

- Inject engine tool schemas into agent tool surface after compressor init - Call on_session_start() with session_id, hermes_home, platform, model - Dispatch engine tool calls (lcm_grep, etc.) before regular tool handler - 55/55 tests pass

…very, ABC completeness Follow-up fixes for the context engine plugin slot (PR #5700): - Enhance ContextEngine ABC: add threshold_percent, protect_first_n, protect_last_n as class attributes; complete update_model() default with threshold recalculation; clarify on_session_end() lifecycle docs - Add ContextCompressor.update_model() override for model/provider/ base_url/api_key updates - Replace all direct compressor internal access in run_agent.py with ABC interface: switch_model(), fallback restore, context probing all use update_model() now; _context_probed guarded with getattr/ hasattr for plugin engine compatibility - Create plugins/context_engine/ directory with discovery module (mirrors plugins/memory/ pattern) — discover_context_engines(), load_context_engine() - Add context.engine config key to DEFAULT_CONFIG (default: compressor) - Config-driven engine selection in run_agent.__init__: checks config, then plugins/context_engine/<name>/, then general plugin system, falls back to built-in ContextCompressor - Wire on_session_end() in shutdown_memory_provider() at real session boundaries (CLI exit, /reset, gateway expiry)

teknium1 · 2026-04-11T02:16:06Z

Merged via PR #7464. Your original design and implementation were cherry-picked with authorship preserved — thank you @stephenschoettler! The final version adds config-driven selection, a unified hermes plugins UI, and an auto-activation safety fix on top of your work.

…very, ABC completeness Follow-up fixes for the context engine plugin slot (PR NousResearch#5700): - Enhance ContextEngine ABC: add threshold_percent, protect_first_n, protect_last_n as class attributes; complete update_model() default with threshold recalculation; clarify on_session_end() lifecycle docs - Add ContextCompressor.update_model() override for model/provider/ base_url/api_key updates - Replace all direct compressor internal access in run_agent.py with ABC interface: switch_model(), fallback restore, context probing all use update_model() now; _context_probed guarded with getattr/ hasattr for plugin engine compatibility - Create plugins/context_engine/ directory with discovery module (mirrors plugins/memory/ pattern) — discover_context_engines(), load_context_engine() - Add context.engine config key to DEFAULT_CONFIG (default: compressor) - Config-driven engine selection in run_agent.__init__: checks config, then plugins/context_engine/<name>/, then general plugin system, falls back to built-in ContextCompressor - Wire on_session_end() in shutdown_memory_provider() at real session boundaries (CLI exit, /reset, gateway expiry)

stephenschoettler mentioned this pull request Apr 7, 2026

Proposal: Pluggable context engines — enabling LCM as a plugin (like OpenClaw's lossless-claw) #5701

Closed

stephenschoettler added 2 commits April 6, 2026 19:05

stephenschoettler force-pushed the feat/context-engine-slot branch from ba23588 to 190eaa9 Compare April 7, 2026 02:07

stephenschoettler force-pushed the feat/context-engine-slot branch from 9e5953b to 6f0d635 Compare April 7, 2026 03:05

teknium1 mentioned this pull request Apr 8, 2026

feat: pluggable context engine slot with config-driven selection #6126

Closed

teknium1 mentioned this pull request Apr 11, 2026

feat: pluggable context engine slot + unified hermes plugins UI #7464

Merged

teknium1 closed this Apr 11, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: pluggable context engine slot (enabling LCM and custom compaction)#5700

feat: pluggable context engine slot (enabling LCM and custom compaction)#5700
stephenschoettler wants to merge 3 commits into
NousResearch:mainfrom
stephenschoettler:feat/context-engine-slot

stephenschoettler commented Apr 7, 2026 •

edited

Loading

Uh oh!

teknium1 commented Apr 11, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

stephenschoettler commented Apr 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What

Why

Changes

Commit 1: ContextEngine ABC (agent/context_engine.py)

Commit 2: Plugin slot wiring

Commit 3: Full engine lifecycle wiring

Tests

Tested End-to-End

Companion

Usage (for plugin authors)

Uh oh!

teknium1 commented Apr 11, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

stephenschoettler commented Apr 7, 2026 •

edited

Loading

Commit 1: ContextEngine ABC (`agent/context_engine.py`)