Issue Station
Sign In
Tools hereToolbox

hermes - ✅(Solved) Fix [Feature]: API Server lacks a session key interface for long-term memory scoping [1 pull requests, 1 comments, 2 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
NousResearch/hermes-agent#20060•Fetched 2026-05-06 06:38:58
View on GitHub
Comments
1
Participants
2
Timeline
7
Reactions
0
Author
manateelazycatmanateelazycat
Participants
manateelazycatmanateelazycatteknium1teknium1
Timeline (top)
labeled ×3closed ×1commented ×1cross-referenced ×1

Fix Action

Fix / Workaround

This would let API-based integrations match the CLI/gateway memory semantics without patching Hermes locally.

This would let API-based integrations match the CLI/gateway memory semantics without patching Hermes locally.

PR fix notes

PR #20199: feat(api-server): X-Hermes-Session-Key header for long-term memory scoping

Description (problem / solution / changelog)

API Server integrations (Open WebUI, third-party web UIs) can now pass a stable per-channel identifier via X-Hermes-Session-Key that scopes long-term memory (Honcho, etc.) independently of the transcript-scoped X-Hermes-Session-Id. One stable key per assistant channel, many transcripts that rotate on /new — matching the native gateway's session_key / session_id split.

Closes #20060.

Changes

  • _create_agent / _run_agent: new gateway_session_key kwarg threaded into AIAgent(gateway_session_key=...), which was already honored by the Honcho memory provider (plugins/memory/honcho/client.py::resolve_session_name). No other plumbing needed — the receiving end was complete.
  • _parse_session_key_header: shared helper with the same API-key gate, \r\n\x00 rejection, and a 256-char length cap as the existing session-id header.
  • _handle_chat_completions, _handle_responses, _handle_runs: all three agent endpoints honor the header.
  • JSON + SSE responses echo X-Hermes-Session-Key back.
  • /v1/capabilities advertises session_key_header so clients can feature-detect.

Validation

BeforeAfter
X-Hermes-Session-Key reaches AIAgent(gateway_session_key=...)droppedthreaded through
Honcho scope stable when session_id rotates (/new)noyes
/v1/capabilities advertises session-key header—"session_key_header": "X-Hermes-Session-Key"
  • 9 new tests in TestSessionKeyHeader (passed + echoed, independent of session-id, absent-yields-none, rejected without API key, control-char sanitization, length cap, threads through _create_agent, /v1/responses accepts it, capabilities advertises).
  • Full tests/gateway/test_api_server.py + test_proxy_mode.py suite: 157 passed.
  • E2E verified with real imports + isolated HERMES_HOME: HTTP X-Hermes-Session-Key: agent:main:webui:dm:user-42 → AIAgent(gateway_session_key=...) → HonchoClientConfig.resolve_session_name() returns the same stable agent-main-webui-dm-user-42 scope regardless of whether session_id is transcript-alpha or transcript-BETA. Without the key, Honcho's per-session strategy correctly produces two different scopes for the two ids — confirming the key is doing the stabilization, not something else.

Client usage

POST /v1/chat/completions
Authorization: Bearer $API_SERVER_KEY
X-Hermes-Session-Key: agent:main:webui:dm:user-42   # stable per-channel → Honcho scope
X-Hermes-Session-Id: transcript-alpha                # rotates on /new → transcript

Credit to @manateelazycat for the diagnosis and the clean feature request in #20060.

Changed files

  • gateway/platforms/api_server.py (modified, +127/-5)
  • scripts/release.py (modified, +1/-0)
  • tests/gateway/test_api_server.py (modified, +182/-0)
RAW_BUFFERClick to expand / collapse

Problem or Use Case

Hi Hermes team,

I am integrating Hermes Agent through the API Server with a third-party Web UI. I found a mismatch between the CLI/gateway session model and the API Server interface.

Hermes CLI/gateway already appears to support two distinct concepts:

  • session_key: a stable per-chat/per-channel identity used as the long-term gateway session/memory scope.
  • session_id: the short-term transcript/session id, regenerated by /new or /reset.

This design works well for the native gateway flow: the same session_key can survive across multiple session_ids, so users can start fresh short-term conversations while still keeping the same long-term memory scope.

However, the API Server currently only exposes X-Hermes-Session-Id. I could not find a way to provide a stable session_key to the API Server and have it passed into AIAgent(gateway_session_key=...).

This makes third-party Web UI integrations hard to implement correctly. The desired behavior is:

  • one stable assistant/channel-level session_key
  • multiple independent UI conversations with different session_ids
  • /new and /reset should rotate only the session_id
  • long-term memory providers such as Honcho should still be scoped by the stable session_key

Could the API Server support something like X-Hermes-Session-Key and pass it through to AIAgent(gateway_session_key=...), while keeping X-Hermes-Session-Id for transcript continuity?

This would let API-based integrations match the CLI/gateway memory semantics without patching Hermes locally.

Proposed Solution

Hi Hermes team,

I am integrating Hermes Agent through the API Server with a third-party Web UI. I found a mismatch between the CLI/gateway session model and the API Server interface.

Hermes CLI/gateway already appears to support two distinct concepts:

  • session_key: a stable per-chat/per-channel identity used as the long-term gateway session/memory scope.
  • session_id: the short-term transcript/session id, regenerated by /new or /reset.

This design works well for the native gateway flow: the same session_key can survive across multiple session_ids, so users can start fresh short-term conversations while still keeping the same long-term memory scope.

However, the API Server currently only exposes X-Hermes-Session-Id. I could not find a way to provide a stable session_key to the API Server and have it passed into AIAgent(gateway_session_key=...).

This makes third-party Web UI integrations hard to implement correctly. The desired behavior is:

  • one stable assistant/channel-level session_key
  • multiple independent UI conversations with different session_ids
  • /new and /reset should rotate only the session_id
  • long-term memory providers such as Honcho should still be scoped by the stable session_key

Could the API Server support something like X-Hermes-Session-Key and pass it through to AIAgent(gateway_session_key=...), while keeping X-Hermes-Session-Id for transcript continuity?

This would let API-based integrations match the CLI/gateway memory semantics without patching Hermes locally.

Alternatives Considered

No response

Feature Type

Gateway / messaging improvement

Scope

None

Contribution

  • I'd like to implement this myself and submit a PR

Debug Report (optional)

extent analysis

TL;DR

The API Server should support a new header, such as X-Hermes-Session-Key, to pass a stable session_key to AIAgent.

Guidance

  • Review the API Server code to determine where the X-Hermes-Session-Id is currently being processed and consider adding support for X-Hermes-Session-Key.
  • Investigate how the AIAgent gateway_session_key parameter is currently being populated and modify it to accept the new X-Hermes-Session-Key header.
  • Verify that the long-term memory providers, such as Honcho, are correctly scoped by the stable session_key.
  • Test the new implementation with multiple UI conversations and session_ids to ensure the desired behavior.

Notes

The proposed solution requires modifications to the API Server and AIAgent, which may involve significant changes to the existing codebase.

Recommendation

Apply workaround: Implement a custom solution to pass the stable session_key to AIAgent, such as using a custom header or modifying the API Server to accept the session_key as a query parameter. This would allow third-party Web UI integrations to match the CLI/gateway memory semantics without waiting for an official fix.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#api#installation#tensor shape#autograd error#model save/load

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING