HHermes Explained

Runtime

Turn Context

The once-per-turn assembled view of instructions, history, tools, memory, and guardrails.

Importance 5/51 backlinks1 source refs

Turn Context

What it is

The once-per-turn assembled view of instructions, history, tools, memory, and guardrails.

In plain terms

A photographer packs one bag before a shoot — the right lens, spare batteries, and memory cards for that specific job — and doesn’t stop to rummage for more gear once the shutter starts clicking. Hermes assembles an equivalent bundle at the start of every turn: conversation history, active instructions, retrieved memory, and which tools are currently switched on, fixed before the model is ever called.

Why it matters

build_turn_context decides, once per turn, exactly what the model is allowed to see this time — conversation history, the active system prompt, retrieved memory, enabled tools, and any active guardrails. A toolset that looks ‘installed’ in the dashboard but never appears in a model’s options usually failed here, not at the tool layer itself. Every later step in the turn, tool execution included, works from the snapshot this function produces rather than re-deriving context on its own.

How it works

Defined in agent/turn_context.py, build_turn_context runs once at the very top of a turn, before any model call happens. It restores or rebuilds the cached system prompt only when one is missing, runs a cheap character-based estimate to decide whether the expensive full token count is even worth paying for, and compresses older conversation history when that estimate crosses the configured threshold. It also refreshes any newly-connected MCP tool server into this turn’s tool snapshot and runs the pre_llm_call plugin hook so installed plugins can inject extra context. Everything produced — the sanitized message, working message list, active system prompt, and a fresh turn_id — is packaged into one TurnContext object that the turn loop’s run_conversation function reads from for the rest of the turn.

A concrete example

A session has grown to roughly 300 messages and is edging toward the model’s context window.

  1. A new message arrives, and build_turn_context runs before any API call is made.
  2. Its cheap token estimate flags the request as oversized.
  3. It compresses the older history, rebuilds the system prompt, and reuses one memory-provider prefetch instead of repeating it.
  4. The model receives a trimmed, cache-friendly context on the very first call of the turn instead of hitting a context-length error partway through.

How it connects

This note belongs to the Runtime family. Its closest neighboring concepts are: Turn Loop, Conversation Loop, Personal OS.

Source evidence

  • vendor/hermes-agent/agent/turn_context.py:343-347#agent.turn_context.build_turn_context — Verified Source Map evidence for build_turn_context. Turn setup ensures the prompt cache exists and exposes it as active_system_prompt, notifies MemoryManager of the new turn before prefetch, then calls prefetch_all with the original user message and caches the result for that turn.

Workflows

  • No first-pass workflow mapping yet; this concept still appears in the vault graph through articles and source evidence.
  • No article currently mentions this concept by name/alias often enough to qualify (see mention-mining policy).