Skip to content

The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu

docs(hermes): explain how event ids stay unique across cloned profiles

Saurav Singh6ed31fcf755d
diff --git a/docs/runtimes/hermes-agent.mdx b/docs/runtimes/hermes-agent.mdx
index f1d342ac..a11824aa 100644
--- a/docs/runtimes/hermes-agent.mdx
+++ b/docs/runtimes/hermes-agent.mdx
@@ -80,6 +80,8 @@ Synced events record the Hermes home they were read from in `harness.config_path
The cursor is stored in Beacon endpoint state and advances by session message id. Each Hermes home has its own cursor file, so syncing one profile or store never advances another's cursor: the native root (`~/.hermes`) keeps `hermes.json`, and any other home, a profile or a custom `HERMES_HOME`, uses `hermes-<profile>-<id>.json`, where `<id>` is derived from the home's path. The home a default sync resolves to starts its keyed cursor from `hermes.json`, which every default sync advanced before cursors were keyed, so upgrading does not re-collect it. Any other home starts with a new cursor the first time it is synced this way, so its retained history is collected once more. Use `--print` to preview mapped events without writing the runtime log or advancing the cursor.
+Synced events take their `event.id` from the session id, the Hermes message id and the kind of event, so syncing a session again names its events the same way. A cloned profile starts from a copy of the original home's `state.db`, so both homes hold the same session ids, and once the copies diverge their message ids count up independently. To keep the two homes from writing different events under one id, `hermes-session-homes.json`, beside the cursor files, records which home first synced each session id. That home keeps the ids above. Any other home that syncs a session with the same id for the first time derives that session's ids from its own path as well, and `beacon endpoint hermes status` marks such sessions `ids keyed by home` (`ids_keyed_by_home` in `--json`). A session keeps the ids it was first synced with, so a session two homes had both synced before this file existed keeps its original ids in both. A `--print` dry run claims no session for its home.
+
For scheduled collection, run `beacon endpoint hermes sync --watch`, or run one-shot `sync` from your scheduler. Live hooks remain the real-time path.
## Deployment notes