fix(memory): entry-point + project-dir discovery parity for out-of-tree providers (salvage of #18842, #40644, #76567)

[gigabyte22]

Closes #40101.

Problem

plugins/memory/ is closed to new providers, so every new memory backend now ships out of tree. But the out-of-tree path is measurably weaker than the in-tree one, and the docs already promise otherwise.

plugins/memory/__init__.py:_iter_provider_dirs() walks directories only — bundled and $HERMES_HOME/plugins/. The general PluginManager (hermes_cli/plugins.py:1371-1391) scans four sources including pip entry points. CONTRIBUTING.md:78 and AGENTS.md both state memory discovery "picks them up from user/project plugin directories and pip entry points". It does not.

The user-visible symptom is #40101: a correctly-registered pip-installed provider reports Plugin: NOT installed. The workaround in the wild is a bespoke second install step — note that Memori, documented in memory-providers.md, ships pip install hermes-memori plus hermes-memori install for exactly this reason.

This is a salvage, not a fourth attempt

Three PRs already address parts of this and none have merged. Rather than add another competing implementation, this rebases them onto current main with authorship preserved and adds what none of them cover — the same approach as #79239.

PR	Author	Taken
#18842	@smarzola	Entry-point discovery via hermes_agent.memory_providers, ctx.register_skill() forwarding, tests, developer-guide docs
#76567	@mlsmith	Classify entry-point provider plugins without importing them, including the dotted-name parent-import fix
#40644	@AxDSan	Not taken — its discovery half duplicates #18842, and its pipx switch was correctly rejected in review (pipx venvs are invisible to both importlib.metadata and the agent runtime) and reverted by the author. Its Mnemosyne docs belong in a docs PR.

#18842 and #76567 are complementary rather than competing: one adds memory entry-point discovery, the other stops the general PluginManager from eagerly importing such packages in every hermes process.

What this adds on top

Project-local providers (./.hermes/plugins/<name>/), gated on HERMES_ENABLE_PROJECT_PLUGINS exactly as PluginManager gates its own project scan. Completes the four sources.

find_provider_dir() resolves package entry points. This is load-bearing rather than cosmetic: config_schema.py (the dashboard config panel) and cli.py (the hermes <provider> subcommands) are read from disk, not imported — plugins/memory/config_schema.py:14-17 does this deliberately so the web server never pulls in the agent runtime. Without a directory, a pip-installed provider silently loses both.

list_memory_provider_names() includes entry-point providers, so they appear in the dashboard's memory.provider dropdown.

Resolution stays import-free. resolve_module_origin() is extracted from #76567's _resolve_module_source() and shared, so discovery walks a module's file layout instead of importing it. find_provider_dir() is called from the dashboard and from argparse setup — long before the operator has chosen a provider — so importing every installed candidate would execute third-party code on the strength of a package merely being present. A test asserts resolution leaves no side effect and no sys.modules entry.

PluginContext.register_memory_provider(). Memory was the only provider category without one — context engine, image gen, video gen, web search, browser, TTS, transcription, secret source, dashboard auth and platform all have one.

_ProviderCollector delegates unknown register_* calls to a real PluginContext instead of carrying three hand-written no-ops. It silently dropped register_tool / register_hook, and had no register_auxiliary_task at all — despite PluginContext.register_auxiliary_task's own docstring using a memory provider (hindsight's pre-retain dedup) as its worked example. It can no longer drift behind PluginContext.

A raise after register_memory_provider() no longer costs the provider. The loader caught it into a logger.debug, discarded the registered instance, and fell through to "instantiate any MemoryProvider subclass" — returning a different, unconfigured provider. A silent downgrade that looked like success, and the exact outcome of calling register_auxiliary_task.

Precedence

bundled > user > project > entrypoint — deliberately the reverse of the general PluginManager's later-wins order, and documented in the module docstring. A memory provider is activated by name, so letting a directory dropped into a working tree shadow a shipped provider would silently redirect the agent's memory. Existing behaviour is unchanged; the new sources sit below it.

Safety

Activation is still gated on memory.provider naming the plugin. Discovery enumerates; it does not load. Using a real PluginContext must not start also requiring the plugin in plugins.enabled — that would break every existing user-installed provider — and there is a test pinning it.

Testing

406 passed across tests/plugins/memory/, tests/agent/test_memory_provider.py, tests/hermes_cli/test_plugins.py, tests/test_plugin_skills.py, tests/hermes_cli/test_web_server.py. Six failures in test_hindsight_provider.py are a missing optional dependency (hindsight_client_api) and fail identically on main.

New coverage in tests/plugins/memory/test_discovery_sources.py: project-dir discovery on and off, entry-point discovery, precedence, import-free resolution, bare-module entry points, the secondary-registration fix, and the plugins.enabled invariant.

Verified end to end against a real third-party provider (kainappsinc/elephant) installed by pip alone with no directory copy — it appears in the dropdown, resolves its directory, loads with its 34 tools, and renders its dashboard config panel.

Follow-ups, deliberately not bundled

• hermes_cli/config_defaults.py:3792 hardcodes env-var metadata per bundled provider; external plugins cannot join. Largely served already by get_config_schema() / config_schema.py, and a much larger refactor.
• hermes_cli/main.py:9210 still hardcodes "honcho" in _SUBCOMMANDS. Cosmetic — it only affects unquoted multi-word session names — but it is the same class of thing PR fix(honcho): plugin drift overhaul + feat(plugins): CLI registration system #5295 removed.

[gigabyte22]

Rebased onto current main (post–manifest v2 #64165 / ownership ledger). The only conflict was an insert-insert collision with the new manifest helpers in hermes_cli/plugins.py; resolved keeping both. _detect_kind_from_source now also backs the manifest parser's directory coercion that landed on main, so the heuristic stays in one place. register_memory_provider deliberately records no ownership-ledger handle — it mutates no global registry, and its docstring says so.

Full suites re-run on the rebased branch: 574 passed, 1 skipped across tests/plugins/memory/, tests/agent/test_memory_provider.py, tests/hermes_cli/test_plugins.py, tests/test_plugin_skills.py, tests/hermes_cli/test_web_server.py. The six test_hindsight_provider.py failures are the pre-existing optional hindsight-client dependency (security.allow_lazy_installs=false), identical on main — this PR touches no hindsight file.

One triage note: this is labelled P3 ("cosmetic, nice to have"), but it's a type/bug closing #40101, where users are still paying the cost — most recently on Aug 11, when a user resorted to hand-symlinking the package into ~/.hermes/plugins/ to get past Plugin: NOT installed. The sweeper's verdict on #18842 (one of the PRs salvaged here) was salvageability=high, and its two suggested changes — the combined entry-point + register_skill() regression and the developer-guide docs — are both included in this PR. Happy to adjust anything review turns up.

[teknium1]

Merged via PR #85527 — all five commits cherry-picked onto current main with authorship preserved in git history (your parity commit, @m1k3s0's two classification commits + activation-contract tests, and @smarzola's packaged-skills commit). One follow-up on top from us: a sibling test (test_plugin_cli_registration.py) pinned the old zero-arg _ProviderCollector() constructor and needed updating for the new required name arg.

Thanks for doing this as a proper salvage rather than a fourth competing implementation — the authorship table in your PR body made the credit trail trivial to preserve.