[BUG] Hermes install docs use unsupported --path and fail on latest stable

[prefrontalsys]

Bug description

Basic Memory currently advertises this as the one-command installation path for the Hermes integration:

hermes plugins install basicmachines-co/basic-memory --path integrations/hermes

That command is not accepted by the latest stable Hermes Agent (v0.20.4 / v2026.8.18). Hermes has no plugins install --path option.

Using Hermes's actual monorepo-subdirectory syntax gets past argument parsing, but the current Basic Memory plugin is then rejected because its manifest is v2 while the Hermes installer still caps installation at v1. Consequently, none of the published managed-install instructions work against the latest stable Hermes release.

Steps to reproduce

Environment:

• Hermes Agent v0.20.4 (v2026.8.18), the current latest stable release
• Basic Memory monorepo main, integrations/hermes/plugin.yaml version 0.22.1

1. Run the documented command

hermes plugins install basicmachines-co/basic-memory --path integrations/hermes

Actual result:

hermes: error: unrecognized arguments: --path integrations/hermes

2. Use Hermes's supported subdirectory-identifier syntax

hermes plugins install basicmachines-co/basic-memory/integrations/hermes

Actual result:

Error: Plugin 'basic-memory' requires manifest_version 2, but this installer
only supports up to 1. Run hermes update to update Hermes.

Updating does not currently provide a released fix. The installer/runtime manifest mismatch is tracked upstream in NousResearch/hermes-agent#85879; the runtime loader accepts v2, but the installer rejects it.

Affected official documentation

The unsupported command is repeated across Basic Memory-owned surfaces, including:

• Repository root README
• integrations/hermes/README.md
• https://docs.basicmemory.com/integrations/hermes
• https://docs.basicmemory.com/whats-new/hermes-plugin
• https://basicmemory.com/for/hermes

This makes the documented “one command” setup appear supported even though it cannot complete on the latest stable Hermes.

Provenance and validation gap

--path integrations/hermes was introduced during the monorepo consolidation in PR #859 / commit 5365f971efe9296c880bc028a9883e864dd3f5cc. The same README addition says users should fall back when their Hermes build does not support --path, but I could not find a released Hermes version or Hermes plugin-installer history implementing that flag.

The Basic Memory Hermes package checks do not exercise installation through a real Hermes binary:

• scripts/validate_hermes_plugin.py validates file layout and marker strings.
• integrations/hermes/justfile explicitly runs hermetic unit tests that do not require Hermes.
• The CI workflow does not execute the documented hermes plugins install ... command.

That allows installer-facing documentation and manifest compatibility to drift while the package tests remain green.

Expected behavior

Basic Memory's official documentation should advertise an installation path that has been exercised successfully against the latest released Hermes Agent.

Suggested resolution

1. Immediately update all Basic Memory-owned documentation to stop presenting --path as a working Hermes option.

2. Until the Hermes v2-manifest installer fix is released, document the tested user-plugin clone/symlink method for the current integration, with the deprecated pointer release listed only as an explicitly versioned, caveated alternative.

3. Once Hermes ships the installer fix, use its supported subdirectory identifier, for example:

   hermes plugins install basicmachines-co/basic-memory/integrations/hermes

   or the complete GitHub /tree/main/integrations/hermes URL.

4. Add an end-to-end CI job that installs the latest released Hermes, runs the exact documented installation command, then verifies:

   hermes plugins doctor basic-memory --ci
   hermes memory status

5. Document the minimum verified Hermes version rather than referring generically to builds that may support a speculative flag.

Additional note

This report is about the managed installation path. The separate native /bm-* gateway command-discovery limitation is already documented and tracked upstream; it should not obscure the fact that the primary install command itself currently fails.

[prefrontalsys]

Follow-up: deprecated pointer-release evaluation on Hermes v0.20.4

I also evaluated the README's suggested fallback, basicmachines-co/hermes-basic-memory v0.3.2, in a disposable HERMES_HOME.

Under Hermes v0.20.4's default policy, the managed install is blocked before installation:

Blocked: Security scan blocked plugin install: Blocked (dangerous verdict, 14 findings).
--force does not override a dangerous verdict.

The findings include the README's persistent ~/.hermes/config.yaml modification and the provider's expected subprocess execution. Regardless of whether those are acceptable for this trusted provider, the practical result is that the documented deprecated fallback does not install under default current Hermes policy either.

For runtime evaluation only, I disabled plugins.scan_on_install inside the disposable profile. With that isolated bypass:

• hermes plugins install basicmachines-co/hermes-basic-memory --enable succeeded.
• hermes plugins doctor basic-memory --ci passed and identified v0.3.2 as an exclusive provider.
• hermes memory status reported installed/available.
• The provider exposed 10 schemas.
• initialize("pointer-eval-session") successfully bootstrapped Basic Memory 0.22.1, started its MCP server, and bm_projects returned the expected temporary local projects.
• shutdown() completed and no bm mcp process remained after this single clean lifecycle.

However, the pointer is frozen before several fixes now present in the monorepo integration:

• [BUG] integrations/hermes: bm mcp processes leak #1017 / July 15: leaked bm mcp subprocesses in affected lifecycle paths.
• Hermes provider inherits PYTHONPATH and fails to start bm MCP with mixed Python versions #1093 / August 4: inherited Hermes PYTHONPATH / interpreter environment could break the separate bm runtime.
• [BUG] integrations/hermes: stop overwriting modern provider registrations #1257 / August 19: the old private _register_via_plugin_manager() fallback overwrites lifecycle-owned registrations on Hermes v0.20.1+ and can leave stale command/skill entries.

The pointer also declares unbounded pip_dependencies: [mcp], whereas the current integration now declares mcp>=2,<3 using the modern manifest field.

Conclusion: v0.3.2 can still execute its core provider path in a clean test, but it should not be presented as an unqualified production fallback for current Hermes. The docs should prefer a pinned clone/symlink of the maintained monorepo integration until the managed installer path is repaired, and should spell out the scanner/compatibility trade-offs if the pointer remains mentioned.