docs(hermes): plan context engine support

[RerankerGuo]

Description | 描述

Add a design plan for bringing TencentDB Agent Memory short-term context offload to Hermes through a ContextEngine plugin.

The document summarizes:

• the Hermes ContextEngine lifecycle contract
• how it maps to memory-tencentdb short-term offload and Mermaid task canvases
• a phased implementation plan from no-op skeleton to read-only MMD injection, offload write path, and lookup tools
• proposed config separation from the existing Hermes memory.provider
• validation requirements before enabling runtime behavior

This is intentionally design-only. It does not claim to complete Hermes Context Engine support.

Related Issue | 关联 Issue

Related to #102
Related to #202

Change Type | 修改类型

• Bug fix | Bug 修复
• New feature | 新功能
• Documentation update | 文档更新
• Code optimization | 代码优化

Self-test Checklist | 自测清单

• Verified locally | 本地验证通过
• No existing features affected | 无影响现有功能

Additional Notes | 其他说明

Verified with npm test and npm run build using Node v24.15.0.

[Maxwell-Code07]

Thanks for your attention. We will review it and get back to you soon.

[ysun0804]

Reference Implementation Available

We have built and deployed a working ContextEngine plugin that implements the design described in this PR. It has been running in production on Hermes Agent v0.16.0 for several days, replacing hermes-lcm as the sole context engine.

What we built

A standalone Python plugin (tencentdb-offload) that:

• Implements all 4 abstract ContextEngine methods (name, update_from_response, should_compress, compress)
• Talks exclusively to the offload V2 API (POST /v2/offload/compact, POST /v2/offload/ingest)
• Has zero dependencies on TencentDB internals — HTTP-only contract
• Includes graceful fallback (tail-truncation with tool-pair preservation) when the Gateway is unreachable
• Thread-safe compress() with lock-free HTTP calls
• Background after_tool_call hook for L1 ingest
• 8 unit tests, stdlib-only

Architecture validation

The implementation closely follows the "Proposed Architecture" section in docs/hermes-context-engine-plan.md:

Plan section	Our implementation
should_compress(prompt_tokens)	✅ Threshold-based (0.4 × context_length)
compress(messages, ...) → offload server	✅ POST /v2/offload/compact
Preserve valid OpenAI message format	✅ Server returns compacted message list
on_session_start() hook	✅ Override + plugin-level fallback
Background tool-pair ingestion	✅ POST /v2/offload/ingest (fire-and-forget)

Key design decisions worth noting

1. HTTP-only API contract: The plugin does not import any TencentDB Python/TS code. This means any server upgrade that preserves the V2 API is automatically compatible. We recommend this as a hard constraint for the official implementation.

2. Fallback is essential: The Gateway can be down, slow, or return errors. A local tail-truncation fallback ensures sessions never deadlock. This should be part of the official spec, not an afterthought.

3. register_context_engine availability check: Older Hermes versions may not have this method. Graceful degradation is important for adoption.

Configuration

# config.yaml
context:
  engine: tencentdb-offload
plugins:
  enabled:
    - tencentdb-offload

# .env
TENCENTDB_OFFLOAD_THRESHOLD=0.4
TENCENTDB_OFFLOAD_GATEWAY_URL=http://127.0.0.1:8420

Compatibility

• TencentDB Agent Memory v1.0.0+ (offload V2 API)
• Hermes Agent v0.16.0+
• Python 3.10+, no external dependencies

---

We are happy to contribute this as a starting point for the official hermes-plugin/context-engine/ directory, or keep it as a community plugin. Either way, this validates that the design plan is sound and implementable with minimal complexity (~440 lines of Python).

If there is interest, we can open a PR to add this under hermes-plugin/ alongside the existing memory_tencentdb provider.