Skip to content

Hermes Agent context engine: the main model writes the compaction handoff on its cached prompt prefix

Check heading order and section text, reserve the reply in the copy budget, and state the fallback window

Elevatormusicc2388e5b6df2
diff --git a/README.md b/README.md
index e532dcb..4651d76 100644
--- a/README.md
+++ b/README.md
@@ -116,7 +116,7 @@ The warm request sends the whole earlier request again, plus the new rows and th
## Fallback model and keys
-The fallback summary uses the auxiliary task `warm_compaction`. Set `auxiliary.warm_compaction.provider` and `auxiliary.warm_compaction.model` to use a different model. The default `auto` uses the main model route.
+The fallback summary uses the auxiliary task `warm_compaction`. Set `auxiliary.warm_compaction.provider` and `auxiliary.warm_compaction.model` to use a different model. The default `auto` uses the main model route. The fallback request is at most about 11,000 tokens: a transcript of about 8,000 tokens, the instruction, and a 2,048-token reply. A fallback model needs a context window of at least 16,000 tokens. Hermes accepts main models with 64,000 tokens or more, so the default route has enough space.
For a custom endpoint that needs a key, put the key name in the model settings:
diff --git a/evidence/plugin-integration.json b/evidence/plugin-integration.json
index 2a637b0..e7f4257 100644
--- a/evidence/plugin-integration.json
+++ b/evidence/plugin-integration.json
@@ -1,6 +1,6 @@
{
"check": "standalone warm_compaction plugin on unpatched Hermes Agent",
- "started_utc": "2026-10-06T09:14:35Z",
+ "started_utc": "2026-10-06T09:31:05Z",
"hermes": {
"commit": "45871e100feceb89769536c88e5e6e265226a409",
"clean": true
@@ -10,9 +10,9 @@
"plugin_files_sha256": {
"warm_compaction/__init__.py": "11e038f05813627b2d1d8b82b3b775ecfe41015746c8e90ed6d452cfdaec65a6",
"warm_compaction/capture.py": "9d6414ec2dc552a01d7ba0ab84009ee30a363d57b9a061c2b5d9bc699c0efb75",
- "warm_compaction/engine.py": "83e2434a172a540e7e21053fd8da6d7204bc8eacadab1809213095821b362b96",
+ "warm_compaction/engine.py": "b1bfd993e7e33f4760a9a49c28987bf877d5c4a507a2b1520aeaf33e1f62f088",
"warm_compaction/fallback.py": "b5ccd56550381fc8033351156cbf2dcf0a7e667f8f9bbf0d15bb2101f3abb97e",
- "warm_compaction/handoff.py": "2fcdc2af2eba2d36eaabfef912ce0dd6d64bccc7849849e6411869a0025a06c2",
+ "warm_compaction/handoff.py": "a88b580a909ea832b53d6e2be58fa213ce621bd486df7a43d0b835ac9ccb8563",
"warm_compaction/layout.py": "84673bd98710416599b3718071dcc24e0c230e4845cdbffb47fd743b2a21f423",
"warm_compaction/plugin.yaml": "d67560fd4625ec80d9e26f3e6d712763e77474f68d469c7e48f09fd3506ccc71",
"warm_compaction/rows.py": "cc2a8a3d0561559f24fc40881453441d938ea9d7803e1df81a107a5e05e5f00a",
@@ -75,11 +75,11 @@
"threshold_tokens": 100000,
"context_length": 200000
},
- "compress_seconds": 0.099,
+ "compress_seconds": 0.167,
"warm_last": {
"path": "warm",
"reason": "accepted",
- "elapsed_s": 0.02,
+ "elapsed_s": 0.022,
"prompt_tokens": 33883,
"cached_tokens": 16941
},
@@ -87,8 +87,7 @@
"final_session_id": "wc-enable_manual_warm",
"continuation_keeps_custom_system_text": false,
"fence_denied": {
- "child_process_blocked": 4,
- "network_host_blocked": 1
+ "child_process_blocked": 4
},
"fence_blocked_programs": [
"git",
@@ -96,14 +95,11 @@
"python",
"python3"
],
- "fence_blocked_hosts": [
- "hermes-assets.nousresearch.com"
- ],
+ "fence_blocked_hosts": [],
"fence_blocked_callers": [
- "child_process_blocked from hermes_cli/source_check.py:_git_run < hermes_cli/source_check.py:_git_stdout < hermes_cli/source_check.py:_read_checkout",
+ "child_process_blocked from hermes_cli/source_check.py:_git_run < hermes_cli/source_check.py:_branch_tip < hermes_cli/source_check.py:_check_branch",
"child_process_blocked from tools/env_probe.py:_run < tools/env_probe.py:_py_out < tools/env_probe.py:_pip_python_version",
- "child_process_blocked from tools/env_probe.py:_run < tools/env_probe.py:_py_out < tools/env_probe.py:_python_version_of",
- "network_host_blocked from hermes_cli/release_channels.py:read < hermes_cli/release_channels.py:read_bytes < hermes_cli/release_channels.py:read_record"
+ "child_process_blocked from tools/env_probe.py:_run < tools/env_probe.py:_py_out < tools/env_probe.py:_python_version_of"
],
"fence_socketpairs": 1,
"install": {
@@ -188,7 +184,7 @@
"install",
"run"
],
- "process_seconds": 54.25
+ "process_seconds": 65.674
},
{
"scenario": "manual_fallback",
@@ -247,11 +243,11 @@
"threshold_tokens": 100000,
"context_length": 200000
},
- "compress_seconds": 0.245,
+ "compress_seconds": 0.332,
"warm_last": {
"path": "fallback",
"reason": "provider_error",
- "elapsed_s": 0.093,
+ "elapsed_s": 0.203,
"prompt_tokens": null,
"cached_tokens": null
},
@@ -259,10 +255,11 @@
"final_session_id": "wc-manual_fallback",
"continuation_keeps_custom_system_text": false,
"fence_denied": {
- "network_host_blocked": 1,
- "child_process_blocked": 3
+ "child_process_blocked": 4,
+ "network_host_blocked": 1
},
"fence_blocked_programs": [
+ "git",
"pip",
"python",
"python3"
@@ -271,6 +268,7 @@
"hermes-assets.nousresearch.com"
],
"fence_blocked_callers": [
+ "child_process_blocked from hermes_cli/source_check.py:_git_run < hermes_cli/source_check.py:_git_stdout < hermes_cli/source_check.py:_read_checkout",
"child_process_blocked from tools/env_probe.py:_run < tools/env_probe.py:_py_out < tools/env_probe.py:_pip_python_version",
"child_process_blocked from tools/env_probe.py:_run < tools/env_probe.py:_py_out < tools/env_probe.py:_python_version_of",
"network_host_blocked from hermes_cli/release_channels.py:read < hermes_cli/release_channels.py:read_bytes < hermes_cli/release_channels.py:read_record"
@@ -358,7 +356,7 @@
"install",
"run"
],
- "process_seconds": 32.746
+ "process_seconds": 33.65
},
{
"scenario": "manual_fixed",
@@ -416,11 +414,11 @@
"threshold_tokens": 100000,
"context_length": 200000
},
- "compress_seconds": 0.243,
+ "compress_seconds": 0.227,
"warm_last": {
"path": "fixed",
"reason": "provider_error",
- "elapsed_s": 0.125,
+ "elapsed_s": 0.109,
"prompt_tokens": null,
"cached_tokens": null
},
@@ -529,7 +527,7 @@
"install",
"run"
],
- "process_seconds": 29.783
+ "process_seconds": 29.985
},
{
"scenario": "auto_tool_loop",
@@ -732,7 +730,7 @@
"install",
"run"
],
- "process_seconds": 33.775
+ "process_seconds": 33.244
},
{
"scenario": "rollback",
@@ -782,11 +780,11 @@
"threshold_tokens": 100000,
"context_length": 200000
},
- "compress_seconds": 0.151,
+ "compress_seconds": 0.15,
"warm_last": {
"path": "warm",
"reason": "accepted",
- "elapsed_s": 0.016,
+ "elapsed_s": 0.015,
"prompt_tokens": 33873,
"cached_tokens": 16936
},
@@ -794,7 +792,7 @@
"final_session_id": "wc-rollback",
"continuation_keeps_custom_system_text": false,
"fence_denied": {
- "child_process_blocked": 4,
+ "child_process_blocked": 5,
"network_host_blocked": 1
},
"fence_blocked_programs": [
@@ -945,8 +943,7 @@
"stored": 30
},
"fence_denied": {
- "child_process_blocked": 5,
- "network_host_blocked": 1
+ "child_process_blocked": 5
},
"fence_blocked_programs": [
"git",
@@ -954,9 +951,7 @@
"python",
"python3"
],
- "fence_blocked_hosts": [
- "hermes-assets.nousresearch.com"
- ]
+ "fence_blocked_hosts": []
},
"exit": [
0,
@@ -968,10 +963,10 @@
"run",
"rollback"
],
- "process_seconds": 38.191
+ "process_seconds": 38.427
}
],
- "finished_utc": "2026-10-06T09:17:44Z",
+ "finished_utc": "2026-10-06T09:34:26Z",
"passed": true,
"run_folder": "outside repository"
}
diff --git a/tests/test_wc_engine.py b/tests/test_wc_engine.py
index af6b7d9..d9d21ed 100644
--- a/tests/test_wc_engine.py
+++ b/tests/test_wc_engine.py
@@ -314,6 +314,25 @@ class EngineTest(unittest.TestCase):
self.assertEqual(self.engine._copy_tokens(tail, "short", 4_000), 10_000 - 4_000 - CARRIER_TOKENS
- estimate_tokens(tail) - estimate_tokens("short"))
+ def test_copy_allowance_leaves_room_for_the_reply(self):
+ # threshold 0.95 of a 20K window: the prompt after compaction must leave the reply reserve free.
+ engine = self.make(threshold=0.95)
+ engine.update_model(model=ROUTE[0], context_length=20_000, base_url=ROUTE[1], api_key="k",
+ provider="custom", api_mode=ROUTE[2])
+ from warm_compaction.engine import CARRIER_TOKENS
+ from warm_compaction.rows import estimate_tokens
+ tail = [user("t " + "x" * 8_000)]
+ used = estimate_tokens(tail) + estimate_tokens("short") + CARRIER_TOKENS
+ self.assertEqual(engine._copy_tokens(tail, "short", 0, 4_096),
+ min(engine._tail_tokens(), 20_000 - 4_096 - used))
+
+ def test_request_reserve_comes_from_the_capture(self):
+ from warm_compaction.engine import request_reserve
+ from warm_compaction.warm import DEFAULT_RESERVE
+ self.assertEqual(request_reserve(None), DEFAULT_RESERVE)
+ self.assertEqual(request_reserve({"body": {"messages": [], "max_tokens": 1_000}}), 1_000)
+ self.assertEqual(request_reserve({"body": {"messages": [], "max_completion_tokens": 2_000}}), 2_000)
+
def test_request_overhead_comes_from_the_capture(self):
from warm_compaction.engine import request_overhead
from warm_compaction.rows import estimate_tokens
diff --git a/tests/test_wc_handoff.py b/tests/test_wc_handoff.py
index c37b42b..93cca6d 100644
--- a/tests/test_wc_handoff.py
+++ b/tests/test_wc_handoff.py
@@ -36,11 +36,25 @@ class HandoffTest(unittest.TestCase):
"byte_bound": reply(HEADINGS_TEXT + "x" * MAX_REPLY_BYTES),
"carrier_marker": reply("[CONTEXT SUMMARY]:\n" + HEADINGS_TEXT),
"heading_missing": reply(HEADINGS_TEXT.replace("## Key facts", "Key facts")),
+ "heading_order": reply("## Next step\nx\n## Goal\ng\n## User instructions\n## Current state\n- s\n"
+ "## Key facts\n"),
+ "section_empty": reply("## Goal\n## User instructions\n## Current state\n## Key facts\n## Next step"),
}
for expected, value in cases.items():
with self.subTest(expected=expected):
self.assertEqual(gate(value), (None, expected))
+ def test_gate_needs_text_in_goal_state_and_next_step(self):
+ sections = {"## Goal": "g", "## User instructions": "- u", "## Current state": "- [OPEN] s",
+ "## Key facts": "- k", "## Next step": "n"}
+ for heading in ("## Goal", "## Current state", "## Next step"):
+ text = "\n".join(f"{name}\n{'' if name == heading else body}" for name, body in sections.items())
+ with self.subTest(heading=heading):
+ self.assertEqual(gate(reply(text)), (None, "section_empty"))
+ # Empty User instructions and Key facts are allowed: there can be none.
+ text = "## Goal\ng\n## User instructions\n## Current state\n- [OPEN] s\n## Key facts\n## Next step\nn"
+ self.assertEqual(gate(reply(text)), (text, None))
+
def test_gate_refuses_a_hermes_summary_prefix(self):
self.assertEqual(gate(reply("[HERMES] x\n" + HEADINGS_TEXT), ("[HERMES]",)), (None, "carrier_marker"))
diff --git a/warm_compaction/engine.py b/warm_compaction/engine.py
index b190c21..2a6bc48 100644
--- a/warm_compaction/engine.py
+++ b/warm_compaction/engine.py
@@ -86,6 +86,13 @@ def request_overhead(capture: dict[str, Any] | None) -> int:
return estimate_tokens({"messages": body["messages"][:count], "tools": body.get("tools")})
+def request_reserve(capture: dict[str, Any] | None) -> int:
+ """The reply reserve of the captured request: max_tokens or max_completion_tokens, else the default."""
+ body = (capture or {}).get("body")
+ value = (body.get("max_tokens") or body.get("max_completion_tokens")) if isinstance(body, dict) else None
+ return value if isinstance(value, int) and not isinstance(value, bool) and value > 0 else warm.DEFAULT_RESERVE
+
+
def _int(value: Any) -> int:
return int(value) if isinstance(value, (int, float)) and not isinstance(value, bool) else 0
@@ -197,7 +204,8 @@ class WarmCompactionEngine(ContextEngine):
prefixes=prefixes,
end_marker=hermes_value("agent.context_compressor", "_SUMMARY_END_MARKER", HERMES_END_MARKER),
marker=hermes_value("agent.context_compressor", "_DB_PERSISTED_MARKER", HERMES_DB_MARKER),
- copy_tokens=self._copy_tokens(messages[start:], summary, request_overhead(capture)))
+ copy_tokens=self._copy_tokens(messages[start:], summary, request_overhead(capture),
+ request_reserve(capture)))
self.compression_count += 1
self._finish(record, started)
return new
@@ -295,16 +303,18 @@ class WarmCompactionEngine(ContextEngine):
return tail_budget(int(self._settings["tail_tokens"]), int(self.context_length or 0),
int(self.threshold_tokens or 0))
- def _copy_tokens(self, tail_rows: list, summary: str, overhead: int = 0) -> int:
+ def _copy_tokens(self, tail_rows: list, summary: str, overhead: int = 0, reserve: int = 0) -> int:
"""Token allowance for the copied user messages: at most the tail size, and small enough that the request
overhead (system rows and tool schemas), the tail rows, the summary, the summary row headings, and the
- copies fit below the compaction threshold."""
+ copies fit below the compaction threshold, and below the context window less the reply reserve."""
tail = self._tail_tokens()
threshold = int(self.threshold_tokens or 0)
if threshold <= 0:
return tail
+ window = int(self.context_length or 0)
+ limit = min(threshold, window - reserve) if window > 0 else threshold
used = overhead + estimate_tokens(tail_rows) + estimate_tokens(summary) + CARRIER_TOKENS
- return max(0, min(tail, threshold - used))
+ return max(0, min(tail, limit - used))
def _cancelled(self) -> bool:
check = getattr(self, "_compression_cancelled_check", None)
diff --git a/warm_compaction/handoff.py b/warm_compaction/handoff.py
index eb25ab1..fb15adb 100644
--- a/warm_compaction/handoff.py
+++ b/warm_compaction/handoff.py
@@ -7,6 +7,7 @@ from typing import Any, Iterable
from .rows import reply_text
HEADINGS = ("## Goal", "## User instructions", "## Current state", "## Key facts", "## Next step")
+REQUIRED_SECTIONS = ("## Goal", "## Current state", "## Next step")
MAX_REPLY_BYTES = 24_000
LEGACY_PREFIX = "[CONTEXT SUMMARY]:"
END_MARKER = "--- END OF CONTEXT SUMMARY"
@@ -83,7 +84,15 @@ def gate(reply: dict[str, Any], summary_prefixes: Iterable[str] = ()) -> tuple[s
return None, "byte_bound"
if any(marker and marker in text for marker in (LEGACY_PREFIX, END_MARKER, *summary_prefixes)):
return None, "carrier_marker"
- lines = {line.strip() for line in text.splitlines()}
+ lines = [line.strip() for line in text.splitlines()]
if any(heading not in lines for heading in HEADINGS):
return None, "heading_missing"
+ starts = [lines.index(heading) for heading in HEADINGS]
+ if starts != sorted(starts):
+ return None, "heading_order"
+ # The goal, the state, and the next step are necessary to continue the task. The user instructions and
+ # the key facts can be empty: there can be none.
+ for heading, start, end in zip(HEADINGS, starts, [*starts[1:], len(lines)]):
+ if heading in REQUIRED_SECTIONS and not any(lines[start + 1:end]):
+ return None, "section_empty"
return text, None