7 · The Context Engine ★

agent/context_engine.py, 490 lines. This file does no actual work — it only defines a contract. But it is the most concentrated expression of Hermes's architectural stance.

7.1 What It Defines

“Only one engine is active” is the important sentence — it classifies the context engine as a “mutually exclusive strategy” rather than a “stackable capability.” Chapter 9 explains why this distinction has to be made at the plugin-system level.

7.2 Lifecycle

"""
Lifecycle:
  1. Engine is instantiated and registered (plugin register() or default)
  2. on_session_start() called when a conversation begins
  3. update_from_response() called after each API response with usage data
  4. should_compress() checked after each turn
  5. compress() called when should_compress() returns True
  6. on_session_end() called at real session boundaries (CLI exit, /reset,
     gateway session expiry) — NOT per-turn
"""

Note the phrase “NOT per-turn” in step 6. This is an easy thing to get wrong:

7.3 The Three Methods You Must Implement

class ContextEngine(ABC):

    @property
    @abstractmethod
    def name(self) -> str:
        """Short identifier (e.g. 'compressor', 'lcm')."""

    @abstractmethod
    def update_from_response(self, usage: Dict[str, Any]) -> None:
        """Update tracked token usage from an API response."""

    @abstractmethod
    def should_compress(self, prompt_tokens: int = None) -> bool:
        """Return True if compaction should fire this turn."""

    @abstractmethod
    def compress(self, messages, current_tokens=None, focus_topic=None,
                 force=False, memory_context="") -> List[Dict[str, Any]]:
        """Compact the message list and return the new message list."""

Backward-compatible design of the usage dict

This is a textbook example of “interface evolution”: old fields are never removed (so old engines keep running), new fields are optional (so new engines can use the finer-grained data), and the compatibility contract is spelled out explicitly in the docs.

Each of compress's four optional parameters has a job

The docs also spell out how parameter evolution is handled: “Older engines may omit this parameter; the host filters unsupported optional parameters by signature.” — the host uses reflection to inspect the engine method's signature and passes only the parameters it accepts. So adding a parameter never breaks an old engine.

7.4 The Sharpest Design Decision: select and compress Are Two Orthogonal Verbs

def select_context(
    self,
    request_messages: List[Dict[str, Any]],
    *,
    conversation_messages: List[Dict[str, Any]] = None,
    incoming_message: Dict[str, Any] = None,
    budget_tokens: int = 0,
) -> List[Dict[str, Any]]:
    """Optionally choose/replace the context for THIS request, pre-generation."""
    return None      # default: no-op

This interface was forced into existence by real misuse

Reconstructing the story:

The key constraint: request-only

The cache contract is spelled out more clearly than anything else

7.5 The Post-Turn Observation Hook

def on_turn_complete(self, messages, usage: Dict[str, Any] = None, **kwargs) -> None:
    """Observe a finished user turn (post-turn ingestion / observation)."""
    return None

This is the mirror image of select_context(): selection happens before the request; observation happens after the turn.

An honest note on coverage

7.6 Other Optional Hooks

# Deterministic pruning, no model call
def prune_tool_results_only(self, messages, current_tokens=None) -> tuple[List, int]:
    return messages, 0                     # default: safe no-op

# Cheap preflight
def should_compress_preflight(self, messages) -> bool:
    return False
def should_defer_preflight_to_real_usage(self, rough_tokens: int) -> bool:
    return False

# Preflight guard for manual /compress
def has_content_to_compress(self, messages) -> bool:
    return True

# Session lifecycle
def on_session_start(self, session_id: str, **kwargs) -> None
def on_session_end(self, session_id: str, messages) -> None
def on_session_reset(self) -> None

# ★ Engines can bring their own tools
def get_tool_schemas(self) -> List[Dict[str, Any]]:
    return []
def handle_tool_call(self, name: str, args: Dict[str, Any], **kwargs) -> str

# Status display
def get_status(self) -> Dict[str, Any]

# Model switching
def update_model(self, model, context_length, base_url="", api_key="",
                 provider="", api_mode="") -> None

Pruning without a model call: why it gets its own hook

The key is “an independent, low trigger.” With a model that has a one-million-token window, should_compress might not fire for dozens of turns — but that stale tool output is re-sent every turn and costs money every turn. So you need a cost-driven pruning trigger that has nothing to do with “will we overflow the window.”

Engines can bring their own tools

get_tool_schemas() / handle_tool_call() let an engine expose its own tools to the model. The example in the docs: the LCM engine can offer tools like lcm_grep, lcm_describe, and lcm_expand — that is, it lets the model actively search, describe, and expand context that has been folded away.

7.7 Default Parameter Values

threshold_percent: float = 0.75      # start compacting at 75% of the window
protect_first_n:   int   = 3         # protect the first 3 (beyond the system prompt)
protect_last_n:    int   = 6         # protect the last 6

emit_automatic_compaction_status: bool = True    # notify the user on automatic compaction?

The semantics of protect_first_n come with an evolution note:

7.8 Control Over User-Visible Status

def automatic_compaction_status_message(engine, *, phase: str,
                                        default_message: str, **context) -> str | None:
    """Resolve host-visible status for an automatic compaction event.

    Engines can suppress routine automatic status with
    ``emit_automatic_compaction_status = False`` or customize it by defining
    ``get_automatic_compaction_status_message(...)``. Empty strings and
    ``None`` mean "do not emit a lifecycle status".
    """

The thinking here: different engines see “compaction” very differently.

• The built-in compressor: compaction is a big deal (lossy, irreversible), and the user should be told
• Some retrieval-style engine: reorganizing context is routine background maintenance, done every turn, and notifying the user would just be noise

And it is finely grained: “warnings, errors, and manual commands the user explicitly runs still notify” — only “routine automatic success” can be silenced.

7.9 Size Comparison of the Built-in Implementation