hermes-identity-plugin/docs/how-it-works.md

Architecture: Why monkey-patch instead of patching files?

The identity plugin uses runtime monkey-patching — no files in the Hermes repo are modified. This is the key design decision that eliminates the need for a fork.

The problem

Kanban workers start with NO gateway user identity. The spawn function runs hermes -p <profile> chat -q "work kanban task <id>". When Honcho initializes, kwargs["user_id"] is None, so it creates user-default-* peers.

There is no Hermes plugin hook that fires at agent initialization before Honcho creates the session. The hooks available are:

• pre_gateway_dispatch — only fires for gateway sessions (Discord, etc.)
• on_session_start — fires AFTER Honcho has already initialized
• pre_tool_call / post_tool_call — fire during tool execution, too late

The solution: runtime monkey-patch

Python allows replacing any method on any class at runtime. The identity plugin does exactly this in its register() function:

1. At plugin load time, it imports HonchoMemoryProvider
2. Stores a reference to the original _do_session_init method
3. Replaces it with a wrapper that checks the identity config first
4. If the wrapper finds a peer name, it injects it via kwargs["user_id"]
5. Otherwise, it calls the original method unchanged

# In the plugin's register() function:
provider_cls = plugins.memory.honcho.HonchoMemoryProvider
_original_init = provider_cls._do_session_init

@wraps(_original_init)
def wrapper(self, cfg, session_id, **kwargs):
    if not kwargs.get("user_id"):
        resolved = get_peer_name()  # reads config + env vars
        if resolved:
            kwargs["user_id"] = resolved
    return _original_init(self, cfg, session_id, **kwargs)

provider_cls._do_session_init = wrapper

Advantages over file patching

Aspect	File patching	Monkey-patching
Repo modifications	Yes (edits plugin file)	Zero
Fork needed	Yes (git diff to maintain)	No
Upgrades	Merge conflict on every pull	Unchanged
Uninstall	Need to revert file changes	Plugin removed → clean
Reliability	Works across restarts	Applied at every load
Complexity	Simple file edit	Wrapping pattern

When does the patch apply?

• At plugin discovery time (Hermes startup)
• Before any Honcho session is created
• Before any agent is initialized
• Before any kanban worker is spawned

The Hermes plugin loader calls register() during gateway/agent startup, which means the patch is in place before any session can begin.

Safety guarantees

1. Non-destructive: The original method is preserved via closure — removing the plugin restores original behavior with zero cleanup.

2. Idempotent: _apply_honcho_patch() guards against double-patching via the _original_init sentinel.

3. Graceful degradation: If the config file is missing, parsing fails, or the kanban DB is unavailable, the wrapper returns None → Honcho falls back to its default behavior (creating user-default-* peers).

4. No data loss: The injected kwargs["user_id"] only affects what peer name Honcho assigns to the session's messages. It doesn't touch any existing data.