Hermes plugin can't be installed via 'hermes plugins install' on any released Hermes (manifest_version 2 vs installer cap of 1)

[nellins]

Summary

hermes plugins install cannot install integrations/hermes on any released version of Hermes Agent. The plugin declares manifest_version: 2; the installer caps at 1. Every user following the documented install path hits this.

Reproduce

$ hermes plugins install basicmachines-co/basic-memory/integrations/hermes
Cloning https://github.com/basicmachines-co/basic-memory.git (subdir: integrations/hermes)...
Error: Plugin 'basic-memory' requires manifest_version 2, but this installer
only supports up to 1. Run hermes update to update Hermes.

Verified 2026-08-26 on Hermes Agent v0.20.5 (v2026.8.19), the latest release, and again after hermes update pulled newer upstream commits (b0dbf72f → 3b672a68). Same error both times.

Why the error's own advice doesn't help

It says to run hermes update. There is nothing to update to:

• The installer fix is NousResearch/hermes-agent#85893, which is still open and unmerged.
• v0.20.5 is the newest release, and the git checkout is already current.

Our docs previously repeated this advice ("update Hermes to a release containing that fix"), which sent readers after a release that doesn't exist. That wording has been corrected.

Current workaround

The Hermes runtime loads manifest_version: 2 without trouble — only the installer is capped. So symlinking the plugin in works:

git clone https://github.com/basicmachines-co/basic-memory.git
ln -snf "$PWD/basic-memory/integrations/hermes" ~/.hermes/plugins/basic-memory

hermes memory status then reports Plugin: installed ✓ / Status: available ✓, and reads and writes against a cloud-routed project work normally. This is the dev-install path already documented in integrations/hermes/README.md.

Options

1. Wait for Nous to merge #85893. Out of our control; no timeline.
2. Document the symlink as the supported path until then. Done as an interim measure on both docs pages.
3. Ship the plugin as manifest_version: 1. The only option that doesn't depend on Nous. Needs someone who knows whether the v2 manifest features are load-bearing here.

Filing per Paul's request so this is tracked rather than living in a docs warning.

[claude]

Claude finished @nellins's task in 39s —— View job

---

Triage

Type: Bug — installer incompatibility, not a code defect in this repo's plugin logic, but it fully blocks the documented install path.

Priority: High — every user following the documented hermes plugins install flow hits this on all currently released Hermes Agent versions (verified on v0.20.5, the latest release, both before and after hermes update). No released fix exists upstream to point users to.

Component: integrations/hermes (Hermes plugin packaging/manifest). Not a cloud issue — this is about the external Hermes Agent installer's version cap, not Basic Memory Cloud behavior.

Complexity: Simple–Medium, depending on the option chosen:

• Waiting on upstream (NousResearch/hermes-agent#85893) is zero-effort but has no timeline and is out of this repo's control.
• Documenting the symlink workaround as the interim supported path (already done per the issue) is simple.
• Downgrading integrations/hermes/plugin.yaml from manifest_version: 2 to 1 is the only fix independent of upstream, but needs verification that no manifest_version: 2–only manifest features are load-bearing for this plugin (current manifest uses kind: exclusive, python_dependencies, and the prefetch/queue_prefetch/sync_turn/on_session_end/shutdown hooks — someone familiar with the Hermes manifest spec should confirm these are all available under v1 before downgrading).

No duplicate found — a related closed issue, #1280, covered a different install-docs defect (--path flag), not this manifest-version cap. Labeled bug.

[nellins]

Follow-up once this is unblocked: shoot the docs video for the Hermes integration.

Deferred deliberately rather than shot against the symlink workaround — the install clip and the payoff clip want to be one recording session against a working hermes plugins install, and shooting the payoff now would mean filming it twice.

Everything else is already verified working, so it's a short session when the time comes:

• Plugin runs fine via the symlink; hermes memory status reports installed / available
• Runs free on GitHub Copilot (gpt-4.1) — no Nous Portal or OpenRouter subscription needed
• Cloud mode confirmed against a cloud-routed project, reads and writes both work

One behaviour worth knowing independent of the video: asked conversationally ("remember this: X"), gpt-4.1 replies "Got it, I've recorded that" and writes nothing. /bm-remember writes reliably. Worth a look at whether the tool description nudges harder toward actually calling the write tool.