Repository navigation
Description
Bug Report: Hermes Link fails to sync web-originated messages in attached conversations
Summary
When a conversation starts in Hermes Link and the user continues it from the web SPA (via API Server), the web-side messages are NOT synced back to Hermes Link — even after force-refreshing the conversation list. Messages flow correctly from Link → Web, but NOT from Web → Link for the same conversation. The underlying state.db is correct (all messages from both sides are persisted), but Link's merge logic discards the web-side messages during re-sync.
Environment
- Hermes Agent: v0.16.0
- Hermes Link: v0.7.6
- Profile: default
- API Server: running on 127.0.0.1:8642
- Web SPA: served via nginx, connects to API Server
- Link store:
~/.hermeslink/conversations/+~/.hermeslink/link.db
Steps to Reproduce
- Open Hermes Link, create a new conversation, send a message ("hello from Link")
- Open the web SPA, find the same conversation in the sidebar, click it
- Send a follow-up message from the web SPA ("hello from web")
- Go back to Hermes Link, force-refresh the conversation list
- Open the same conversation
Expected: Both "hello from Link" and "hello from web" are visible in Link.
Actual: Only "hello from Link" is visible. The web-side message is missing.
What Works
- Web-created conversations → Link syncs correctly (first import is a "pure import", all messages replaced)
- Link → Web syncs correctly (web reads
state.dbdirectly via API Server, always sees latest) - Continuing in Link after web messages → Web sees the new Link messages (Web always reads
state.db)
Root Cause Analysis
Traced in Hermes Link binary (@hermespilot/link v0.7.6, chunk-P54DBGLE.js):
Data Flow (verified)
- Link sends message →
POST /v1/runswithsession_id→ AIAgent writes messages to~/.hermes/state.db✅ - Web sends message →
POST /api/sessions/{id}/chat→ AIAgent writes messages to~/.hermes/state.db✅ - All messages from both sides coexist correctly in
state.db✅
Link Sync Logic (the bug)
When Link re-syncs existing conversations, mergeExistingHermesConversation() (line 14451) is called. It correctly re-reads all messages from state.db via readHermesLineageMessages() (line 14462).
However, at line 14498, mergeHermesCandidateIntoConversation() handles two cases:
pureImport = true(conversation was purely imported, no Link-native user interactions): ALL messages are replaced withstate.dbdata → works correctlypureImport = false(conversation has Link-native user messages): Only the "imported prefix" is replaced (collectImportedHermesPrefixat line 14506). The Link-native suffix is preserved.
The bug is in collectImportedHermesPrefix boundary detection. After a conversation has Link-native messages, the prefix detection likely treats web-originated messages that arrived between Link messages as "not part of the imported prefix" and drops them during merge.
Why web-created conversations work
A web-created conversation imported into Link for the first time is a pureImport. All messages are replaced from state.db → works. But once the user sends a message in Link, the conversation loses pureImport status, and the next re-sync hits the broken prefix logic.
Verification Evidence
Tested by creating a session via /v1/runs (simulating Link), then adding messages via /api/sessions/{id}/chat (simulating Web). Confirmed:
state.dbhad all 8 messages (6 from Link, 2 from Web) ✅GET /api/sessionsreturns the session with correctmessage_count✅- Web SPA can see and load all messages ✅
Suggested Fix
In mergeHermesCandidateIntoConversation() (line ~14498), for non-pureImport conversations, the merge should re-read the full message set from state.db and use it as the authoritative source for the "imported" portion, rather than relying on collectImportedHermesPrefix boundary detection. Or, alternatively, the prefix detection should include ALL messages from state.db that have matching Link-native counterparts, not just a contiguous prefix block.
Related
- Hermes Agent version: 0.16.0
- Config: default profile, API Server on 8642
- Nginx reverse proxy:
/api/→http://127.0.0.1:8642
Activity
DavidMetcalfe commentedon Sep 8, 2026
@donglei1982 — thanks for the detailed trace; the analysis is solid and the evidence is on point.
A heads-up on scope, though: this bug is not in hermes-agent. The failing logic (
mergeHermesCandidateIntoConversation/collectImportedHermesPrefixin the merge path) lives in@hermespilot/link, the separately-published companion module (npm install -g @hermespilot/link, maintaineryanghangbin), not in this repository. hermes-agent's ownstate.dband API server are confirmed correct on both the Link→Web and Web→Link paths — the drop happens entirely in Link's re-sync merge, so there's no backend-side change that addresses it.Two things I'd suggest:
@hermespilot/linkowner (npm package,yanghangbin) — they're the ones who can patch the merge logic.collectImportedHermesPrefixno longer exists (replaced by a fingerprint-basedsyncHermesConversationMessages). So the specific bug as described may already be addressed on current Link; worth confirming on v1.1.1 before or alongside re-filing.