feat(honcho): add stable multi-user memory identity mapping by mavrickdeveloper · Pull Request #27371 · NousResearch/hermes-agent

mavrickdeveloper · 2026-05-17T09:16:41Z

Update : This PR is now included and merged in a superset PR : #30077
Closing.

Summary

Adds a backwards-compatible runtime identity mapping layer for the Honcho memory provider so multi-user gateway deployments can map known platform user IDs to stable Honcho peers while keeping unknown users isolated under predictable platform-scoped peer IDs.

This locks down the design points from the issue discussion:

pinPeerName: true with peerName remains the strongest explicit choice and wins over aliases/prefixes.
sessionPeerPrefix stays orthogonal: it scopes Honcho session IDs, while runtimePeerPrefix scopes Honcho user peer IDs.
userPeerAliases and runtimePeerPrefix follow the existing host-block-wins-then-root fallback pattern.
Alias lookup matches raw runtime IDs before sanitizing the final selected Honcho peer ID.
Generated runtimePeerPrefix peers stay collision-resistant: safe IDs remain readable, but Hermes appends a stable short hash when sanitization is lossy or when the generated ID would collide with explicit peerName / alias targets. If the short hash itself is already reserved by explicit config, Hermes deterministically extends it.

Changes

plugins/memory/honcho/client.py — add userPeerAliases and runtimePeerPrefix parsing with host-block override semantics, empty host values that can intentionally disable root values, and forgiving handling for malformed alias maps.
plugins/memory/honcho/session.py — move user peer selection into _resolve_user_peer_id() with explicit precedence: pinned peerName, alias match, runtime prefix, raw runtime ID, configured peerName, then existing session-key fallback. Unknown prefixed runtime peers now avoid accidental sanitizer/config collisions with stable hash suffixes only when needed.
run_agent.py, agent/agent_init.py, gateway/run.py, and plugins/memory/honcho/__init__.py — thread user_id_alt from gateway sources into memory-provider initialization so platforms with alternate stable IDs can use aliases without changing default raw-ID fallback behavior.
Tests cover config parsing, pin precedence, raw-ID alias matching, runtime prefix fallback, generated-ID collision resistance, sessionPeerPrefix orthogonality, alternate-ID alias matching, and provider initialization plumbing.

Validation

scripts/run_tests.sh tests/honcho_plugin
# 286 passed

scripts/run_tests.sh tests/honcho_plugin/test_pin_peer_name.py tests/honcho_plugin/test_session.py tests/run_agent/test_memory_provider_init.py
# 149 passed

scripts/run_tests.sh tests/run_agent/test_memory_provider_init.py tests/tui_gateway/test_make_agent_provider.py tests/gateway/test_api_server_toolset.py tests/gateway/test_compress_command.py tests/gateway/test_compress_focus.py tests/gateway/test_compress_plugin_engine.py
# 29 passed

Also ran:

git diff --check
python -m py_compile plugins/memory/honcho/session.py tests/honcho_plugin/test_pin_peer_name.py

Remove "PR NousResearch#14984 / NousResearch#27371 / NousResearch#1969" references and "the original key / legacy / backwards-compatible / Port #N" narration from the honcho plugin README, tests, and one stale code comment. These artefacts age poorly: they describe how a change happened rather than what the code does today, and they tax readers who weren't around for the original work. Also drop a dangling reference to scratch/memory-plugin-ux-specs.md in __init__.py — the file isn't in the repo or git history. No behaviour change.

PR #27371 added host-scoped userPeerAliases, runtimePeerPrefix, and pinPeerName, but the cloned-profile allowlist in plugins/memory/honcho/cli.py::clone_honcho_for_profile() omitted them. A new profile created via 'hermes honcho setup' or similar would silently drop the operator's identity-mapping config, causing gateway users to resolve to raw runtime IDs and fragmenting Honcho memory across an unintended set of peers. Add the three keys to the allowlist and a regression test class covering all three plus the unset case.

…ed-thread peer contamination PR #27371 introduced a per-user-peer resolver in HonchoSessionManager, but the resolved runtime identity is frozen into the manager at first- message init. When the gateway session_key intentionally omits the participant ID (the default for threads via thread_sessions_per_user= False), a cached AIAgent created by user A is reused for user B's messages, attributing B's writes to A's resolved Honcho peer and breaking #27371's per-user-peer contract. Fix by including user_id and user_id_alt in _agent_config_signature so the cache key distinguishes participants in shared threads. Each user in a shared thread now triggers a fresh AIAgent build (trading prompt- cache warmth for memory-attribution correctness — the right tradeoff for an external-memory backend where misattribution is unrecoverable). The default-None case keeps the signature byte-identical to pre-fix behavior so this change doesn't invalidate in-flight caches on deploy.

The PR #27371 resolver introduced three identity-mapping config keys (pinPeerName, userPeerAliases, runtimePeerPrefix), but operators had no guided way to set them — they had to read the README, understand the resolver ladder, and hand-edit honcho.json. This commit adds an interactive step to 'hermes honcho setup' that asks one question ('what's your deployment shape?') and writes the right combination of keys. Three shapes cover the realistic deployments: * single -- pinPeerName=true. All gateway users collapse to your peerName. Recommended for personal/single-operator use. * multi -- pinPeerName=false, no aliases. Each runtime user gets their own peer. Optional runtimePeerPrefix for cross- platform namespace isolation. * hybrid -- pinPeerName=false, with userPeerAliases mapping YOUR runtime IDs (Telegram UID, Discord snowflake, Slack user, Matrix MXID) to peerName. Multi-user gateway where you are a privileged operator. A 'skip' option leaves existing identity-mapping config untouched — critical because re-running setup must not silently wipe operator- curated aliases. The wizard detects the current shape from existing config so the prompt's default matches what the operator already has.

…r pinPeerName The original key 'pinPeerName' from #14984 is ambiguous: a fresh reader can't tell whether it pins the user peer or the AI peer from the name alone. The resolver only ever pins the user-side (_resolve_user_peer_id short-circuits when pin_peer_name is true; the AI peer is already pinned by construction via aiPeer). Add 'pinUserPeer' as the canonical alias. Both keys land on the same internal pin_peer_name field; precedence is host pinUserPeer → host pinPeerName → root pinUserPeer → root pinPeerName → default. Host-level always beats root-level regardless of alias, so a host block can still explicitly disable a root-level pin even via the new key. Make _resolve_bool variadic so it can express the four-value precedence chain. All existing callers pass two positional args + default keyword, which the new signature accepts unchanged. Internal var name (pin_peer_name) stays the same to keep the cherry-picked #27371 commits clean and avoid a noisy rename diff.

…ployment shapes PR #27371 introduced three new identity-mapping config keys (pinPeerName, userPeerAliases, runtimePeerPrefix), but the README's 'Full Configuration Reference' didn't mention them. Operators had to read the source to understand the resolver, leading to predictable support questions ("why is my user split across two peers?", "what does pinPeerName actually pin?"). Add a new 'Identity Mapping' subsection that covers: * The four config keys (pinUserPeer + alias, userPeerAliases, runtimePeerPrefix) with concrete examples. * The 7-step resolver ladder so operators can predict which peer a given runtime ID will land on. * Why there's no symmetric pinAiPeer (the AI peer is already pinned by construction; the asymmetry is intentional). * Host vs root semantics (host-level replaces root for maps, wipes with empty value). * The three deployment shapes ('hermes honcho setup' uses these same shape names) with one-line guidance per shape.

Remove "PR #14984 / #27371 / #1969" references and "the original key / legacy / backwards-compatible / Port #N" narration from the honcho plugin README, tests, and one stale code comment. These artefacts age poorly: they describe how a change happened rather than what the code does today, and they tax readers who weren't around for the original work. Also drop a dangling reference to scratch/memory-plugin-ux-specs.md in __init__.py — the file isn't in the repo or git history. No behaviour change.

PR NousResearch#27371 added host-scoped userPeerAliases, runtimePeerPrefix, and pinPeerName, but the cloned-profile allowlist in plugins/memory/honcho/cli.py::clone_honcho_for_profile() omitted them. A new profile created via 'hermes honcho setup' or similar would silently drop the operator's identity-mapping config, causing gateway users to resolve to raw runtime IDs and fragmenting Honcho memory across an unintended set of peers. Add the three keys to the allowlist and a regression test class covering all three plus the unset case.

…ed-thread peer contamination PR NousResearch#27371 introduced a per-user-peer resolver in HonchoSessionManager, but the resolved runtime identity is frozen into the manager at first- message init. When the gateway session_key intentionally omits the participant ID (the default for threads via thread_sessions_per_user= False), a cached AIAgent created by user A is reused for user B's messages, attributing B's writes to A's resolved Honcho peer and breaking NousResearch#27371's per-user-peer contract. Fix by including user_id and user_id_alt in _agent_config_signature so the cache key distinguishes participants in shared threads. Each user in a shared thread now triggers a fresh AIAgent build (trading prompt- cache warmth for memory-attribution correctness — the right tradeoff for an external-memory backend where misattribution is unrecoverable). The default-None case keeps the signature byte-identical to pre-fix behavior so this change doesn't invalidate in-flight caches on deploy.

The PR NousResearch#27371 resolver introduced three identity-mapping config keys (pinPeerName, userPeerAliases, runtimePeerPrefix), but operators had no guided way to set them — they had to read the README, understand the resolver ladder, and hand-edit honcho.json. This commit adds an interactive step to 'hermes honcho setup' that asks one question ('what's your deployment shape?') and writes the right combination of keys. Three shapes cover the realistic deployments: * single -- pinPeerName=true. All gateway users collapse to your peerName. Recommended for personal/single-operator use. * multi -- pinPeerName=false, no aliases. Each runtime user gets their own peer. Optional runtimePeerPrefix for cross- platform namespace isolation. * hybrid -- pinPeerName=false, with userPeerAliases mapping YOUR runtime IDs (Telegram UID, Discord snowflake, Slack user, Matrix MXID) to peerName. Multi-user gateway where you are a privileged operator. A 'skip' option leaves existing identity-mapping config untouched — critical because re-running setup must not silently wipe operator- curated aliases. The wizard detects the current shape from existing config so the prompt's default matches what the operator already has.

…r pinPeerName The original key 'pinPeerName' from NousResearch#14984 is ambiguous: a fresh reader can't tell whether it pins the user peer or the AI peer from the name alone. The resolver only ever pins the user-side (_resolve_user_peer_id short-circuits when pin_peer_name is true; the AI peer is already pinned by construction via aiPeer). Add 'pinUserPeer' as the canonical alias. Both keys land on the same internal pin_peer_name field; precedence is host pinUserPeer → host pinPeerName → root pinUserPeer → root pinPeerName → default. Host-level always beats root-level regardless of alias, so a host block can still explicitly disable a root-level pin even via the new key. Make _resolve_bool variadic so it can express the four-value precedence chain. All existing callers pass two positional args + default keyword, which the new signature accepts unchanged. Internal var name (pin_peer_name) stays the same to keep the cherry-picked NousResearch#27371 commits clean and avoid a noisy rename diff.

…ployment shapes PR NousResearch#27371 introduced three new identity-mapping config keys (pinPeerName, userPeerAliases, runtimePeerPrefix), but the README's 'Full Configuration Reference' didn't mention them. Operators had to read the source to understand the resolver, leading to predictable support questions ("why is my user split across two peers?", "what does pinPeerName actually pin?"). Add a new 'Identity Mapping' subsection that covers: * The four config keys (pinUserPeer + alias, userPeerAliases, runtimePeerPrefix) with concrete examples. * The 7-step resolver ladder so operators can predict which peer a given runtime ID will land on. * Why there's no symmetric pinAiPeer (the AI peer is already pinned by construction; the asymmetry is intentional). * Host vs root semantics (host-level replaces root for maps, wipes with empty value). * The three deployment shapes ('hermes honcho setup' uses these same shape names) with one-line guidance per shape.

Remove "PR NousResearch#14984 / NousResearch#27371 / NousResearch#1969" references and "the original key / legacy / backwards-compatible / Port #N" narration from the honcho plugin README, tests, and one stale code comment. These artefacts age poorly: they describe how a change happened rather than what the code does today, and they tax readers who weren't around for the original work. Also drop a dangling reference to scratch/memory-plugin-ux-specs.md in __init__.py — the file isn't in the repo or git history. No behaviour change.

PR NousResearch#27371 added host-scoped userPeerAliases, runtimePeerPrefix, and pinPeerName, but the cloned-profile allowlist in plugins/memory/honcho/cli.py::clone_honcho_for_profile() omitted them. A new profile created via 'hermes honcho setup' or similar would silently drop the operator's identity-mapping config, causing gateway users to resolve to raw runtime IDs and fragmenting Honcho memory across an unintended set of peers. Add the three keys to the allowlist and a regression test class covering all three plus the unset case. #AI commit#

…ed-thread peer contamination PR NousResearch#27371 introduced a per-user-peer resolver in HonchoSessionManager, but the resolved runtime identity is frozen into the manager at first- message init. When the gateway session_key intentionally omits the participant ID (the default for threads via thread_sessions_per_user= False), a cached AIAgent created by user A is reused for user B's messages, attributing B's writes to A's resolved Honcho peer and breaking NousResearch#27371's per-user-peer contract. Fix by including user_id and user_id_alt in _agent_config_signature so the cache key distinguishes participants in shared threads. Each user in a shared thread now triggers a fresh AIAgent build (trading prompt- cache warmth for memory-attribution correctness — the right tradeoff for an external-memory backend where misattribution is unrecoverable). The default-None case keeps the signature byte-identical to pre-fix behavior so this change doesn't invalidate in-flight caches on deploy. #AI commit#

The PR NousResearch#27371 resolver introduced three identity-mapping config keys (pinPeerName, userPeerAliases, runtimePeerPrefix), but operators had no guided way to set them — they had to read the README, understand the resolver ladder, and hand-edit honcho.json. This commit adds an interactive step to 'hermes honcho setup' that asks one question ('what's your deployment shape?') and writes the right combination of keys. Three shapes cover the realistic deployments: * single -- pinPeerName=true. All gateway users collapse to your peerName. Recommended for personal/single-operator use. * multi -- pinPeerName=false, no aliases. Each runtime user gets their own peer. Optional runtimePeerPrefix for cross- platform namespace isolation. * hybrid -- pinPeerName=false, with userPeerAliases mapping YOUR runtime IDs (Telegram UID, Discord snowflake, Slack user, Matrix MXID) to peerName. Multi-user gateway where you are a privileged operator. A 'skip' option leaves existing identity-mapping config untouched — critical because re-running setup must not silently wipe operator- curated aliases. The wizard detects the current shape from existing config so the prompt's default matches what the operator already has. #AI commit#

…r pinPeerName The original key 'pinPeerName' from NousResearch#14984 is ambiguous: a fresh reader can't tell whether it pins the user peer or the AI peer from the name alone. The resolver only ever pins the user-side (_resolve_user_peer_id short-circuits when pin_peer_name is true; the AI peer is already pinned by construction via aiPeer). Add 'pinUserPeer' as the canonical alias. Both keys land on the same internal pin_peer_name field; precedence is host pinUserPeer → host pinPeerName → root pinUserPeer → root pinPeerName → default. Host-level always beats root-level regardless of alias, so a host block can still explicitly disable a root-level pin even via the new key. Make _resolve_bool variadic so it can express the four-value precedence chain. All existing callers pass two positional args + default keyword, which the new signature accepts unchanged. Internal var name (pin_peer_name) stays the same to keep the cherry-picked NousResearch#27371 commits clean and avoid a noisy rename diff. #AI commit#

…ployment shapes PR NousResearch#27371 introduced three new identity-mapping config keys (pinPeerName, userPeerAliases, runtimePeerPrefix), but the README's 'Full Configuration Reference' didn't mention them. Operators had to read the source to understand the resolver, leading to predictable support questions ("why is my user split across two peers?", "what does pinPeerName actually pin?"). Add a new 'Identity Mapping' subsection that covers: * The four config keys (pinUserPeer + alias, userPeerAliases, runtimePeerPrefix) with concrete examples. * The 7-step resolver ladder so operators can predict which peer a given runtime ID will land on. * Why there's no symmetric pinAiPeer (the AI peer is already pinned by construction; the asymmetry is intentional). * Host vs root semantics (host-level replaces root for maps, wipes with empty value). * The three deployment shapes ('hermes honcho setup' uses these same shape names) with one-line guidance per shape. #AI commit#

Remove "PR NousResearch#14984 / NousResearch#27371 / NousResearch#1969" references and "the original key / legacy / backwards-compatible / Port #N" narration from the honcho plugin README, tests, and one stale code comment. These artefacts age poorly: they describe how a change happened rather than what the code does today, and they tax readers who weren't around for the original work. Also drop a dangling reference to scratch/memory-plugin-ux-specs.md in __init__.py — the file isn't in the repo or git history. No behaviour change. #AI commit#