Skip to content

feat: discover pipx-installed memory providers via entry points, switch to pipx - #40644

Closed
AxDSan wants to merge 3 commits into
NousResearch:mainfrom
AxDSan:unified-mnemosyne-docs
Closed

feat: discover pipx-installed memory providers via entry points, switch to pipx#40644
AxDSan wants to merge 3 commits into
NousResearch:mainfrom
AxDSan:unified-mnemosyne-docs

Conversation

@AxDSan

@AxDSan AxDSan commented Jun 6, 2026

Copy link
Copy Markdown
Contributor

Problem

discover_memory_providers() in plugins/memory/__init__.py is purely directory-based. It scans plugins/memory/<name>/ and $HERMES_HOME/plugins/<name>/ for directories - never checks importlib.metadata entry points. This means pipx-installed memory provider packages (like mnemosyne-hermes) register a correct hermes_agent.plugins entry point but never appear as Plugin: installed ✓ because the memory discovery system doesn't look for entry points.

Separately, hermes_cli/memory_setup.py uses uv pip install for plugin dependencies, which doesn't provide stable path guarantees across Hermes updates.

Changes

1. Entry-point provider discovery (plugins/memory/__init__.py)

  • Added importlib.metadata based scanning of a new hermes_agent.memory_providers entry-point group
  • _get_entry_point_providers(): discovers pip/pipx-installed memory provider packages
  • _load_entry_point_provider(): loads a memory provider from its entry point (handles register_memory_provider, register, and MemoryProvider subclass patterns)
  • discover_memory_providers(): appends entry-point providers after directory-based ones
  • load_memory_provider(): falls through to entry-point loading when directory lookup fails
  • Precedence: bundled > user-installed > entry-point providers

2. pipx over uv (hermes_cli/memory_setup.py)

  • Replaced uv pip install with pipx install for plugin dependencies
  • pipx installs packages to stable isolated locations so hermes update doesn't break plugin paths

Testing

  • Lint clean on both modified files
  • Entry-point loading handles all three plugin patterns
  • Directory-based providers continue loading with unchanged precedence

@liuhao1024

Copy link
Copy Markdown
Contributor

There's a regression in hermes_cli/memory_setup.py:_install_dependencies — switching from uv pip install to pipx install will break the dependency installation flow for memory providers.

The problem: pipx install creates an isolated virtual environment for each package. It does NOT install packages into the current Python environment's site-packages. This means:

  1. Packages installed via pipx install --python <executable> won't be importable from the agent's Python runtime — the memory provider will fail to load its dependencies.
  2. The new entry-point discovery mechanism (_get_entry_point_providers()) also won't find them — importlib.metadata.entry_points() only discovers entry points from packages installed in the current Python environment, not from isolated pipx venvs.

Reproduction: After pipx install --python /usr/bin/python3 mnemosyne-memory, running python3 -c "import mnemosyne" in the agent's environment will fail with ModuleNotFoundError.

Suggested fix: Either:

  • Keep using uv pip install --python <executable> (or pip install) in _install_dependencies, since the packages need to be importable in the agent's main environment for the entry-point discovery to work
  • Or use pipx inject <app> <package> if you want to inject into an existing pipx-managed environment

The entry-point discovery code in plugins/memory/__init__.py itself looks correct and would work for packages installed via pip install into the current environment.

Minor note: The .codegraph/.gitignore file is unrelated to this PR's scope (entry-point discovery + pipx migration). Consider splitting it into a separate commit or PR.

@alt-glitch alt-glitch added type/feature New feature or request P3 Low — cosmetic, nice to have comp/plugins Plugin system and bundled plugins tool/memory Memory tool and memory providers comp/cli CLI entry point, hermes_cli/, setup wizard python:uv Pull requests that update python:uv code labels Jun 6, 2026
@AxDSan

AxDSan commented Jun 13, 2026

Copy link
Copy Markdown
Contributor Author

Great catch @liuhao1024 — you're right on every point.

creates an isolated venv, so plugin.yaml deps (honcho, mem0ai, etc.) aren't importable from the agent's runtime. Entry-point discovery via importlib.metadata also won't find packages in a pipx-isolated venv — it only sees the current Python environment.

Fix applied: reverted _install_dependencies back to uv pip install --python sys.executable in the latest commit. The plugin.yaml dependency flow needs uv because those packages must be importable at runtime.

The pipx narrative still holds, just for a different target:

  • pipx install mnemosyne-hermes or pipx install honcho-ai → installs the provider package itself in an isolated venv (safe from hermes update nuking it), and entry-point discovery finds it there
  • uv pip install --python sys.executable → installs the plugin.yaml pip_dependencies into the agent's runtime (must be importable)

Two separate tools, each for their job. The entry-point discovery change in plugins/memory/__init__.py is what makes the pipx workflow work end-to-end.

Also split the .codegraph/.gitignore out — agree that was scope creep.

@teknium1 teknium1 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for tackling a real gap: current main only loads memory providers from directories (plugins/memory/__init__.py:146-205).

Problems

  • The new group at plugins/memory/__init__.py:40 is hermes_agent.memory_providers, while Hermes' existing pip-plugin contract is hermes_agent.plugins (hermes_cli/plugins.py:215; website/docs/user-guide/features/plugins.md:109,125). The PR body says the target package already uses the latter, so this scan will not find it.
  • ep.load() at plugins/memory/__init__.py:155 is never invoked when it returns a registration callable; only module attributes and subclasses are inspected.
  • The implementation does not make pipx environments visible to the Hermes interpreter. The prior review correctly identified that limitation, and the author acknowledged it in the follow-up discussion.
  • No tests cover the newly added discovery and loading paths.

Suggested changes

  • Align on one entry-point contract and add end-to-end discovery/activation tests for it, including precedence and callable entry points.
  • Keep the documented symlink/pip install path unless pipx visibility is implemented and tested explicitly.

Automated hermes-sweeper review.

Comment thread plugins/memory/__init__.py Outdated
Comment thread plugins/memory/__init__.py Outdated
@teknium1 teknium1 added sweeper:risk-compatibility Sweeper risk: may break existing users, config, migrations, defaults, or upgrades sweeper:risk-security-boundary Sweeper risk: may affect sandboxing, auth, credentials, or sensitive data sweeper:blast-moderate Sweeper blast radius: moderate — a subsystem or single platform labels Jul 14, 2026
Bartok9 and others added 3 commits July 14, 2026 23:16
…Research#34271)

Mnemosyne is a community-maintained Hermes memory provider plugin
that fills a documented gap in the bundled provider set:

- Largest tool surface of any provider (19 tools vs Honcho's 5).
- Only provider with hybrid semantic + FTS5 + temporal ranking in one
  query.
- Only fully-local provider (beyond Holographic/ByteRover) with vector
  search, full-text search, and a knowledge graph in one engine.
- Free + MIT + no API key + no quotas + no network egress.

Per the issue's 'Minimal' acceptance criteria (no Hermes core code
changes required), this PR:

1. Adds Mnemosyne to the front-matter description, the providers
   inventory line ('9 external memory provider plugins + 1 community
   provider'), and the example config-yaml comment.
2. Adds a full provider section under ### Memori with:
   - Best-for / Requires / Storage / Cost block
   - All 19 tools listed
   - Setup snippet showing pip install + plugin symlink + provider
     selection
   - Key capabilities summary
   - Lifecycle integration audit (which optional hooks are
     implemented vs not)
   - Explicit community-maintained status note pointing bug reports
     to the Mnemosyne project.
3. Adds a Mnemosyne row to the Provider Comparison table with a
   footnote distinguishing it from bundled providers.

The 'community-maintained' framing is intentional: the issue's
request was visibility, not promotion to first-party. The plugin-
discovery system already supports user-installed providers via
$HERMES_HOME/plugins/, so documentation is the only blocker.

Refs: NousResearch#34271
Closes: NousResearch#34271

Co-authored-by: Cursor <cursoragent@cursor.com>
…s (+ zh-Hans)

Adds Mnemosyne (and Memori) to the cross-reference lists in:
- website/docs/integrations/index.md
- website/docs/user-guide/features/overview.md
- website/docs/user-guide/features/memory.md
- website/i18n/zh-Hans/ integrations/index.md (zh-Hans)
- website/i18n/zh-Hans/ overview.md (zh-Hans)

Replaces stale '8 providers' wording with 'supported providers' for
lower maintenance overhead.

Co-authored-by: Bartok <bartok9@users.noreply.github.com>
Co-authored-by: Abdias J <abdi.moya@gmail.com>
…ace uv with pipx

Three changes:

1. **Entry-point provider discovery** —  now
   scans  entry points in addition to
   directory-based providers. pipx/pip-installed memory provider packages
   are auto-discovered without symlinks or directory copies.

2. **pipx over uv** —  uses
   instead of  for plugin dependencies. pipx installs
   packages to stable isolated locations so updates don't break paths.

3. **Precedence** — bundled > user-installed > entry-point, so existing
   directory-based setups keep working unchanged.

Fixes mnemosyne-oss/mnemosyne#240 — mnemosyne-hermes plugin now surfaces
as 'installed' via entry-point discovery, no workaround needed.
@AxDSan
AxDSan force-pushed the unified-mnemosyne-docs branch from 2862437 to e881c03 Compare July 14, 2026 21:20
@teknium1 teknium1 added area/memory Memory subsystem: store, providers, sync, background reviews area/install-update Installer, updater, packaging, wheels, doctor labels Jul 19, 2026
m1k3s0 pushed a commit to m1k3s0/hermes-agent that referenced this pull request Aug 2, 2026
…ation

Documents and tests the routing contract the sweeper review asked about:
classification records the manifest but does not activate anything.

- model-provider test now exercises providers.get_provider_profile() against
  the pip-only name (None today — providers discovery is directory-based)
  and asserts the module never leaks into sys.modules via that path.
- new test for the mnemosyne shape: a pip entry point duplicating a
  same-name directory provider. The pip copy is classified exclusive and
  never imported; the directory copy still activates through
  plugins.memory discovery, exactly once.
- _classify_entrypoint_kind docstring now states the activation contract
  explicitly: pip-only providers were equally unactivatable pre-change
  (both destination systems are directory-only; the
  hermes_agent.memory_providers entry-point group has no consumers), so
  classification only removes the wasted import. Entry-point activation
  is tracked upstream (NousResearch#40644 for memory); this change is its
  prerequisite, preventing double import once it lands.
gigabyte22 pushed a commit to gigabyte22/hermes-agent that referenced this pull request Aug 13, 2026
…ation

Documents and tests the routing contract the sweeper review asked about:
classification records the manifest but does not activate anything.

- model-provider test now exercises providers.get_provider_profile() against
  the pip-only name (None today — providers discovery is directory-based)
  and asserts the module never leaks into sys.modules via that path.
- new test for the mnemosyne shape: a pip entry point duplicating a
  same-name directory provider. The pip copy is classified exclusive and
  never imported; the directory copy still activates through
  plugins.memory discovery, exactly once.
- _classify_entrypoint_kind docstring now states the activation contract
  explicitly: pip-only providers were equally unactivatable pre-change
  (both destination systems are directory-only; the
  hermes_agent.memory_providers entry-point group has no consumers), so
  classification only removes the wasted import. Entry-point activation
  is tracked upstream (NousResearch#40644 for memory); this change is its
  prerequisite, preventing double import once it lands.
teknium1 pushed a commit that referenced this pull request Aug 13, 2026
…ation

Documents and tests the routing contract the sweeper review asked about:
classification records the manifest but does not activate anything.

- model-provider test now exercises providers.get_provider_profile() against
  the pip-only name (None today — providers discovery is directory-based)
  and asserts the module never leaks into sys.modules via that path.
- new test for the mnemosyne shape: a pip entry point duplicating a
  same-name directory provider. The pip copy is classified exclusive and
  never imported; the directory copy still activates through
  plugins.memory discovery, exactly once.
- _classify_entrypoint_kind docstring now states the activation contract
  explicitly: pip-only providers were equally unactivatable pre-change
  (both destination systems are directory-only; the
  hermes_agent.memory_providers entry-point group has no consumers), so
  classification only removes the wasted import. Entry-point activation
  is tracked upstream (#40644 for memory); this change is its
  prerequisite, preventing double import once it lands.
@teknium1

Copy link
Copy Markdown
Contributor

Closing — the entry-point discovery half of this landed on main via PR #85527 (salvage of #80493), which took #18842's implementation for that piece; the pipx switch was previously found unworkable in review (pipx venvs are invisible to importlib.metadata and the agent runtime). Pip-installed memory providers now discover and activate end to end. The Mnemosyne docs addition would still be welcome as a standalone docs PR against website/docs/. Thanks for pushing on this gap early.

@teknium1 teknium1 closed this Aug 13, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area/install-update Installer, updater, packaging, wheels, doctor area/memory Memory subsystem: store, providers, sync, background reviews comp/cli CLI entry point, hermes_cli/, setup wizard comp/plugins Plugin system and bundled plugins P3 Low — cosmetic, nice to have python:uv Pull requests that update python:uv code sweeper:blast-moderate Sweeper blast radius: moderate — a subsystem or single platform sweeper:risk-compatibility Sweeper risk: may break existing users, config, migrations, defaults, or upgrades sweeper:risk-security-boundary Sweeper risk: may affect sandboxing, auth, credentials, or sensitive data tool/memory Memory tool and memory providers type/feature New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants