Related to #9308 — both address cross-channel identity/memory unification. #9308 approaches via Honcho owner identity at gateway layer; this PR uses filesystem symlinks as a companion tool.

Thanks for pointing out #9308! You're right that both address cross-channel identity, but they solve it at different scopes:

#9308 (Honcho gateway layer):

• Auto-detects the bot owner via DM + home channel match
• Works at the Honcho memory plugin level
• Only covers the owner — other users still get fragmented memories

#19163 (filesystem layer):

• Manual mapping for any user (not just owner)
• Works with all memory providers (Honcho, Hindsight, local files)
• Complementary: feat(memory): unify owner identity across channels in Honcho #9308 for automatic owner detection, feat: add user_mapper.py for cross-channel memory unification #19163 for explicit multi-user mapping

The gap in #9308: if a non-owner user (e.g., a classmate sharing the bot) uses both Telegram and CLI, their memories are still split. #9308's _is_owner_source check intentionally skips non-owner users.

Proposed approach:

• If feat(memory): unify owner identity across channels in Honcho #9308 merges, owner gets auto-unification for free
• feat: add user_mapper.py for cross-channel memory unification #19163 adds manual mapping for non-owner users who need cross-channel continuity
• Both can coexist at different layers

I'll update #19163 to also support automatic owner detection (symlink the global MEMORY.md/USER.md to the owner's user directory on first setup), reducing the manual config burden.

The user_mapper.py approach is architecturally sound — unified identity mapping across channels prevents the fragmentation problem where the same user appears as different IDs on Telegram vs Discord.

Questions before merge:

1. Location: scripts/user_mapper.py is an odd home for a runtime component (and this is a net-new addition, not an edit). If this runs at agent startup or on each message, it belongs in agent/ or tools/. scripts/ typically implies standalone utilities. What's the invocation path?

2. Persistence: Does the mapper state survive session restarts? If channels are added incrementally, the mapper needs to be persisted (DB, file). If it's recomputed on each startup from some canonical source, that should be documented.

3. Conflict resolution: When two channels map to the same user_id but have conflicting display names or metadata, which wins? There should be an explicit merge strategy.

The core logic looks solid. The file is well-structured with clear docstrings. Resolving the location and persistence questions would unblock merge.

Thanks for the thorough review, @ether-btc! Good questions. Here's the breakdown:

1. Location: scripts/ vs agent/ vs tools/

user_mapper.py is a standalone CLI utility, not a runtime component. It's invoked manually during setup:

python3 user_mapper.py auto-setup      # one-time owner detection
python3 user_mapper.py map --chat-id X --user Y  # manual mapping

It does not run at agent startup or on each message. Once the symlinks are created, Hermes reads memories/{chat_id}/ and follows the symlink transparently — zero runtime code changes. This is why scripts/ is the correct home (same pattern as scripts/release.py, scripts/run_tests.sh).

That said, if the maintainers prefer tools/ for discoverability, I'm happy to move it.

2. Persistence

The mapper state persists across restarts via two mechanisms:

• Mapping file: ~/.hermes/user_mapping.json — JSON dict of {chat_id: username}. Loaded on each CLI invocation, saved on map/unmap commands.
• Symlinks: Created on the filesystem (~/.hermes/memories/{chat_id}/ → user_{username}/). These survive restarts, reboots, and hermes update. They're just regular filesystem symlinks.

The mapping is not recomputed on startup — it's explicitly managed via CLI commands. Once set, it persists until manually unmapped.

3. Conflict Resolution

With the symlink approach, there are no metadata conflicts to resolve — the design sidesteps the problem entirely:

• The canonical key is username (not display name, not metadata)
• All channels mapped to the same user point to the same directory (user_{username}/)
• Data naturally merges because it's literally the same filesystem directory
• Display names and per-channel metadata are not stored in the mapping file — only the {chat_id → username} mapping exists

If two channels map to the same user but have conflicting data (e.g., different USER.md content), the second map command doesn't overwrite — it symlinks to the existing directory. The first channel's data wins (it's already there). The migrate command handles moving existing data into the user directory with explicit confirmation.

Summary: The mapper is intentionally minimal — a CLI tool + JSON file + symlinks. No runtime code, no database, no conflict resolution logic needed because the filesystem handles it.