Repository navigation
[BUG] Hermes install docs use unsupported --path and fail on latest stable #1280
Description
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/hermesThat 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.yamlversion0.22.1
1. Run the documented command
hermes plugins install basicmachines-co/basic-memory --path integrations/hermesActual result:
hermes: error: unrecognized arguments: --path integrations/hermes
2. Use Hermes's supported subdirectory-identifier syntax
hermes plugins install basicmachines-co/basic-memory/integrations/hermesActual 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.pyvalidates file layout and marker strings.integrations/hermes/justfileexplicitly 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
-
Immediately update all Basic Memory-owned documentation to stop presenting
--pathas a working Hermes option. -
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.
-
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/hermesURL. -
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
-
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.
Activity
prefrontalsys commentedon Aug 19, 2026
Follow-up: deprecated pointer-release evaluation on Hermes v0.20.4
I also evaluated the README's suggested fallback,
basicmachines-co/hermes-basic-memoryv0.3.2, in a disposableHERMES_HOME.Under Hermes v0.20.4's default policy, the managed install is blocked before installation:
The findings include the README's persistent
~/.hermes/config.yamlmodification 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_installinside the disposable profile. With that isolated bypass:hermes plugins install basicmachines-co/hermes-basic-memory --enablesucceeded.hermes plugins doctor basic-memory --cipassed and identified v0.3.2 as an exclusive provider.hermes memory statusreported installed/available.initialize("pointer-eval-session")successfully bootstrapped Basic Memory 0.22.1, started its MCP server, andbm_projectsreturned the expected temporary local projects.shutdown()completed and nobm mcpprocess remained after this single clean lifecycle.However, the pointer is frozen before several fixes now present in the monorepo integration:
bm mcpsubprocesses in affected lifecycle paths.PYTHONPATH/ interpreter environment could break the separate bm runtime._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 declaresmcp>=2,<3using 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.
phernandez commentedon Aug 21, 2026
Scope note from release triage: docs-side fix in the docs repo, Paul is taking this one directly. Tracked on the v0.23 milestone for the release sweep.
phernandez commentedon Aug 23, 2026
Release triage decision: Basic Memory will support managed installation only on a Hermes Agent release that contains the manifest-v2 installer fix in NousResearch/hermes-agent#85893. We will not downgrade the plugin manifest or maintain the deprecated pointer-repository fallback.
The supported install form is:
Hermes Agent v0.20.5 (
v2026.8.19) and earlier are explicitly unsupported for managed installation. As of August 23, 2026, upstream #85893 remains open, so no released Hermes version currently meets this support floor.Fixes are prepared in:
Keeping this issue open until the three documentation PRs land.
phernandez commentedon Aug 23, 2026
Resolved across all documented install surfaces and merged to
main:c01d451)3f78959)c08d588)The documented command is now
hermes plugins install basicmachines-co/basic-memory/integrations/hermes. Managed installation requires a Hermes Agent release containing NousResearch/hermes-agent#85893; v0.20.5 and earlier are explicitly unsupported. No manifest downgrade or deprecated pointer-repository fallback is maintained.