[BUG] integrations/hermes: stop overwriting modern provider registrations

[phernandez]

Bug Description

Hermes v2026.8.13 / v0.20.1 shipped memory-provider registration parity through NousResearch/hermes-agent#85527. Its _ProviderCollector now delegates register_command, register_skill, and the other register_* APIs through a real PluginContext.

The Basic Memory integration still unconditionally calls its private _register_via_plugin_manager() fallback after using the supported context APIs. On modern Hermes, that fallback overwrites the lifecycle-owned command and skill entries that Hermes just registered.

This is no longer only technical debt: it defeats Hermes's ownership ledger and can leave stale Basic Memory slash commands installed after the provider is unloaded.

Relevant Basic Memory paths:

• integrations/hermes/__init__.py
• integrations/hermes/tests/test_commands.py
• integrations/hermes/plugin.yaml
• integrations/hermes/MONKEYPATCH.md
• integrations/hermes/README.md

Why This Happens

The current registration flow is effectively:

1. ctx.register_command(...) and ctx.register_skill(...) run.
2. Hermes records lifecycle handles for those exact registry objects.
3. _register_via_plugin_manager() reaches into the private PluginManager registries and replaces the entries with new raw dictionaries.
4. Hermes later tries to restore/remove the objects it originally registered using identity checks.
5. The replacement entries do not match, so cleanup does not remove them.

The current unit test also locks in the legacy raw command shape:

{
    "handler",
    "description",
    "plugin",
    "args_hint",
}

Modern Hermes's supported registration adds ownership metadata such as plugin_key.

Reproduction / Evidence

Run the current Basic Memory provider against the released Hermes v2026.8.13 plugin runtime, register it through the modern provider collector, then dispose Hermes's lifecycle ledger.

Observed immediately after registration:

{
  'provider': 'basic-memory',
  'entry_keys': ['args_hint', 'description', 'handler', 'plugin'],
  'ledger_count': 1,
  'entry_has_plugin_key': False
}

Observed after disposing the ledger:

{'command_present_after_ledger_dispose': True}

The provider command remains present and holds the old provider closure.

Hermes Plugin Doctor currently reports the plugin as valid but does not catch this lifecycle/identity failure:

Plugin Doctor: integrations/hermes
  manifest: basic-memory 0.22.1 (exclusive)
  OK...
  registrations: 0 tool(s), 0 hook(s)

Upstream implementation references:

• Released provider collector delegation
• Released lifecycle-aware registration
• Released gateway command discovery

Expected Behavior

On Hermes v2026.8.13/v0.20.1 and newer:

• Basic Memory registers slash commands and the bundled skill only through PluginContext.
• Hermes owns their lifecycle.
• Disposing/unloading the provider removes its registrations.
• Basic Memory does not mutate private Hermes registries after supported registration succeeds.

Older Hermes versions can retain a narrowly gated compatibility fallback if we still intend to support them.

Proposed Solution

1. Treat ctx.register_command() and ctx.register_skill() as the primary and complete path.
2. Do not call _register_via_plugin_manager() for a capability that the supplied context supports.
3. Preserve legacy compatibility, if desired, only as a per-capability fallback when the context lacks register_command or register_skill.
   • This is the recommended transition because existing Basic Memory users may still be on Hermes v0.17/v0.18.
   • Alternatively, declare Hermes v0.20.1 as the minimum supported version and remove the private reach-in entirely.
4. Build each slash-command handler once so the supported and legacy paths cannot produce competing closure identities.
5. Update tests to cover both the modern lifecycle path and any intentionally supported legacy collector path.
6. Upgrade plugin.yaml to the current manifest contract:
   • manifest_version: 2
   • api_version: 1
   • kind: exclusive
   • python_dependencies: ["mcp>=2,<3"]
   • retain bounded legacy pip_dependencies only if old Hermes compatibility remains required
7. Update MONKEYPATCH.md and the Hermes README to distinguish the shipped collector fix from the remaining upstream startup gap.

Remaining Upstream Gap

The original Hermes tracker comment says the expansion wave is complete, and the collector half of our monkeypatch is now obsolete. However, released hermes_cli.plugins.get_plugin_commands() still only returns the current command registry; it does not first load the configured exclusive memory provider.

That means native /bm-* discovery at gateway boot may still require the active-provider-load half of the workaround or an upstream change. This should stay separate from Basic Memory's registration lifecycle fix.

Related upstream references:

• Tracker comment
• Provider collector follow-up PR
• Original provider registration issue

Acceptance Criteria

• On Hermes v2026.8.13/v0.20.1+, command entries retain Hermes ownership metadata such as plugin_key.
• Disposing the Hermes lifecycle ledger removes Basic Memory commands and skills.
• No private registry mutation occurs when the supplied context supports the relevant registration API.
• If legacy Hermes remains supported, fallback behavior is capability-gated and has focused coverage.
• Tests no longer require the obsolete raw command-entry shape on the modern path.
• plugin.yaml uses manifest v2 metadata and bounds the MCP dependency to mcp>=2,<3.
• MONKEYPATCH.md documents that collector delegation shipped in Hermes v0.20.1 and identifies only the remaining active-provider startup load gap.
• Existing tool aliases, session capture, bundled skill, and slash-command handlers remain covered.
• just package-check-hermes passes.
• Released Hermes Plugin Doctor passes in CI mode.
• A focused lifecycle probe proves commands do not survive provider disposal.

[claude]

Claude finished @phernandez's task in 52s —— View job

---

Triage

Type: Bug (confirmed against source). integrations/hermes/__init__.py:2014-2061 shows register() unconditionally calling _register_via_plugin_manager() (__init__.py:1864) after the supported ctx.register_command() / ctx.register_skill() calls succeed, regardless of whether the passed-in context already supports those APIs. That reach-in writes raw dicts (handler, description, plugin, args_hint, no plugin_key) directly into PluginManager._plugin_commands / _plugin_skills, overwriting the lifecycle-owned entries Hermes just created via the supported path — matching the repro in the issue. plugin.yaml is also still on the legacy manifest shape (no manifest_version/api_version/kind, unbounded pip_dependencies: [mcp]), consistent with the issue's proposed manifest-v2 update.

Priority: Medium. Not data loss or a security issue, but it defeats Hermes's ownership/cleanup ledger on the now-released Hermes v0.20.1+, leaving stale /bm-* commands and the bundled skill registered after the provider is unloaded.

Component: Hermes integration plugin (integrations/hermes/) — registration/lifecycle path. No repository cloud label applies.

Complexity: Medium. Localized to integrations/hermes/__init__.py (gate _register_via_plugin_manager per-capability on hasattr(ctx, "register_command"/"register_skill"), dedupe handler-closure construction), plugin.yaml (manifest v2 fields), MONKEYPATCH.md/README.md updates, and tests/test_commands.py (drop the legacy raw-shape assertion, add lifecycle-path coverage + a disposal probe). No duplicates found via gh search issues for this repo.

No reproduction steps needed — the issue includes a clear repro against Hermes v2026.8.13 plus upstream references. Per this task's scope, only classification/labeling was performed; implementation was intentionally not started.