Skip to content

Commit 1387c7f

Browse files
RerankerGuoRerankerGuo
committed
docs(hermes): plan context engine support
Signed-off-by: Ziyang Guo <121015044+RerankerGuo@users.noreply.github.com>
1 parent 4339e63 commit 1387c7f

3 files changed

Lines changed: 172 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -504,6 +504,7 @@ Debugging no longer means probing an opaque database — it becomes a determinis
504504

505505
| Document | Contents |
506506
| :--- | :--- |
507+
| [`docs/hermes-context-engine-plan.md`](./docs/hermes-context-engine-plan.md) | Design plan for Hermes short-term context engine support |
507508
| [`scripts/README.memory-tencentdb-ctl.md`](./scripts/README.memory-tencentdb-ctl.md) | Operations & management tooling |
508509
| [`CHANGELOG.md`](./CHANGELOG.md) | Release notes and version history |
509510
| [`openclaw.plugin.json`](./openclaw.plugin.json) | OpenClaw plugin manifest and configuration schema |

‎README_CN.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,9 @@
4343

4444
> 超长 Session 评测不是单题清空上下文，而是把多个任务拼接到同一个 Session 中连续执行。例如 SWE-bench 每个 Session 连续执行 50 个任务，用来模拟真实长程 Agent 的上下文累积压力。
4545
46+
Hermes 短期记忆 / Context Engine 支持的阶段性设计见
47+
[Hermes Context Engine Integration Plan](./docs/hermes-context-engine-plan.md)。
48+
4649
---
4750

4851
## 项目简介

‎docs/hermes-context-engine-plan.md‎

Lines changed: 168 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,168 @@
1+
# Hermes Context Engine Integration Plan
2+
3+
This document outlines a staged plan for adding TencentDB Agent Memory short-term
4+
context offload to Hermes as a `ContextEngine` plugin.
5+
6+
It is a design document, not a completed adapter. The goal is to make the
7+
integration boundary explicit before wiring runtime behavior into Hermes's
8+
compression lifecycle.
9+
10+
## Background
11+
12+
TencentDB Agent Memory currently has two integration surfaces:
13+
14+
- **OpenClaw**: long-term memory plus short-term context offload through the
15+
`contextEngine` slot.
16+
- **Hermes**: long-term memory through `memory.provider: memory_tencentdb`.
17+
18+
Hermes also supports pluggable context engines selected by:
19+
20+
```yaml
21+
context:
22+
engine: "memory_tencentdb"
23+
```
24+
25+
The official Hermes `ContextEngine` interface requires an engine to:
26+
27+
- track token usage via `update_from_response(usage)`,
28+
- decide when compaction should run via `should_compress(prompt_tokens)`,
29+
- return a valid OpenAI-style message list from `compress(messages, ...)`,
30+
- optionally expose tools through `get_tool_schemas()` and `handle_tool_call()`,
31+
- handle session lifecycle hooks such as `on_session_start()` and
32+
`on_session_end()`.
33+
34+
## Target Behavior
35+
36+
The Hermes context engine should bring the OpenClaw short-term memory benefits
37+
to Hermes users:
38+
39+
1. Persist large tool outputs outside the active prompt.
40+
2. Convert tool-heavy task history into compact Mermaid task canvases.
41+
3. Preserve drill-down recovery through `node_id` and raw reference files.
42+
4. Keep returned messages valid for Hermes's model provider path.
43+
5. Avoid replacing the existing long-term memory provider; users may enable the
44+
memory provider, context engine, or both.
45+
46+
## Proposed Architecture
47+
48+
```text
49+
Hermes Agent
50+
├─ memory.provider: memory_tencentdb
51+
│ └─ existing Python MemoryProvider -> Node Gateway /recall + /capture
52+
└─ context.engine: memory_tencentdb
53+
└─ new Python ContextEngine adapter
54+
├─ session lifecycle and token threshold tracking
55+
├─ local/offload sidecar client
56+
├─ Mermaid injection into compressed messages
57+
└─ optional lookup tools for node_id/raw refs
58+
```
59+
60+
The first implementation should avoid duplicating the whole TypeScript offload
61+
pipeline in Python. Prefer one of these reuse paths:
62+
63+
- expose a narrow Gateway endpoint for offload operations, then have the Hermes
64+
engine call the Gateway;
65+
- or run a small Node helper next to the existing Gateway and keep Python as the
66+
lifecycle adapter.
67+
68+
## Lifecycle Mapping
69+
70+
| Hermes `ContextEngine` method | TencentDB responsibility |
71+
| :--- | :--- |
72+
| `on_session_start(session_id, **kwargs)` | Resolve session key, data directory, Gateway/helper availability, and load existing offload state. |
73+
| `update_from_response(usage)` | Update prompt/completion/total token counters and maintain `threshold_tokens`. |
74+
| `should_compress(prompt_tokens)` | Trigger when prompt usage crosses configured mild or aggressive offload ratios. |
75+
| `compress(messages, current_tokens, focus_topic)` | Persist eligible tool outputs, run or request L1/L1.5/L2 offload processing, inject active Mermaid context, and return valid messages. |
76+
| `get_tool_schemas()` | Expose optional lookup tools for `node_id`, Mermaid files, and raw refs. |
77+
| `handle_tool_call(name, args, **kwargs)` | Dispatch lookup calls to the offload store/helper. |
78+
| `on_session_end(session_id, messages)` | Flush pending offload work and persist final session state. |
79+
| `on_session_reset()` | Reset per-session state without deleting persisted offload artifacts. |
80+
81+
## Phased Implementation
82+
83+
### Phase 1: No-op Engine Skeleton
84+
85+
- Add `hermes-plugin/context_engine/memory_tencentdb/`.
86+
- Implement a minimal `ContextEngine` subclass that:
87+
- satisfies the Hermes ABC,
88+
- tracks token usage,
89+
- reports status,
90+
- returns messages unchanged from `compress()`.
91+
- Add Python tests that instantiate the engine and verify the ABC contract.
92+
93+
This phase proves discovery, configuration, and lifecycle compatibility without
94+
risking message corruption.
95+
96+
### Phase 2: Read-only Mermaid Injection
97+
98+
- Reuse existing offload artifacts if present under the configured data
99+
directory.
100+
- Inject the active Mermaid task canvas into the returned messages within a
101+
configurable token/character budget.
102+
- Add tests for message validity, budget enforcement, and no-op behavior when
103+
no MMD exists.
104+
105+
This gives Hermes users read-only task canvas context before enabling mutation.
106+
107+
### Phase 3: Offload Write Path
108+
109+
- Persist large tool outputs from Hermes messages into refs/JSONL.
110+
- Generate or request L1/L1.5/L2 summaries through the shared Gateway/helper.
111+
- Replace eligible historical tool results with compact summaries.
112+
- Preserve raw refs and `node_id` drill-down.
113+
114+
### Phase 4: Tools And Recovery
115+
116+
- Expose `tdai_offload_lookup` or equivalent through `get_tool_schemas()`.
117+
- Support exact raw ref lookup only through explicit tool calls, not automatic
118+
prompt injection.
119+
- Add tests for unknown tool names, missing refs, and successful node recovery.
120+
121+
## Configuration
122+
123+
Recommended initial config shape:
124+
125+
```yaml
126+
context:
127+
engine: memory_tencentdb
128+
129+
memory_tencentdb:
130+
context_engine:
131+
enabled: true
132+
data_dir: ~/.hermes/context-offload
133+
mild_offload_ratio: 0.5
134+
aggressive_offload_ratio: 0.85
135+
mmd_max_token_ratio: 0.2
136+
```
137+
138+
Keep this separate from `memory.provider` settings so users can enable
139+
long-term memory and short-term context management independently.
140+
141+
## Validation Plan
142+
143+
Minimum tests before enabling write behavior:
144+
145+
- Engine can be discovered and instantiated by Hermes.
146+
- `compress()` always returns a list of OpenAI-style message dicts.
147+
- System, first user messages, and recent tail messages are preserved.
148+
- Tool call/tool result groups are not split into invalid sequences.
149+
- Mermaid injection obeys its budget and is absent when no active MMD exists.
150+
- Session reset clears counters but not persisted artifacts.
151+
- Unknown tools return structured JSON errors.
152+
153+
Runtime validation:
154+
155+
- Run a long tool-heavy Hermes session and compare prompt tokens before/after.
156+
- Confirm raw tool output is recoverable by `node_id`.
157+
- Confirm the existing `memory_tencentdb` MemoryProvider still works when the
158+
context engine is disabled.
159+
- Confirm enabling both memory provider and context engine does not duplicate
160+
recall/context injection.
161+
162+
## Out Of Scope For The First Runtime PR
163+
164+
- Rewriting the TypeScript offload pipeline in Python.
165+
- Changing the existing Hermes MemoryProvider behavior.
166+
- Auto-enabling the context engine when the memory provider is selected.
167+
- Claiming WideSearch or SWE-bench improvements without a reproducible Hermes
168+
evaluation run.

0 commit comments

Comments
 (0)