Hermes provider inherits PYTHONPATH and fails to start bm MCP with mixed Python versions

[tellus1019]

Summary

The Hermes Basic Memory provider passes the full Hermes backend environment to the bm mcp subprocess.

Hermes Desktop adds its Python 3.11 site-packages to PYTHONPATH, while the Basic Memory uv tool runs on Python 3.12. The child process therefore imports Hermes's Python 3.11 version of pydantic and fails to start.

Environment

• macOS
• Hermes Agent v0.18.2
• Hermes Python 3.11.15
• Basic Memory 0.22.1
• Basic Memory Python 3.12
• Hermes integration: integrations/hermes

Error

ModuleNotFoundError: No module named 'pydantic_core._pydantic_core'

The imported pydantic path is under the Hermes Python 3.11 virtual environment, while bm is running from the uv-managed Basic Memory Python 3.12 environment.

Reproduction

Running bm with the inherited Hermes environment fails:

~/.local/bin/bm --version

Running it after removing the parent Python environment succeeds:

env -u PYTHONPATH -u PYTHONHOME -u VIRTUAL_ENV ~/.local/bin/bm --version

A diagnostic Hermes provider initialization with those variables removed also succeeds and discovers 23 MCP tools.

Suspected cause

integrations/hermes/__init__.py uses:

self._env = dict(env) if env is not None else os.environ.copy()

The external bm process should not inherit Hermes's Python environment.

Suggested scope

Use a sanitized child-process environment for:

• bm mcp
• uv tool install basic-memory
• bm project add

At minimum, remove:

• PYTHONPATH
• PYTHONHOME
• VIRTUAL_ENV

Please include an integration test with a deliberately contaminated PYTHONPATH, since unit mocks do not reproduce the native-extension ABI failure.

[tonydzi]

This still reproduces on current main (7b4cbed), so the report has not aged out — worth re-confirming since it was filed against 0.22.1 and a lot has merged since.

Line-precise, in integrations/hermes/__init__.py, there are three inheriting call sites, not one:

• L546 self._env = dict(env) if env is not None else os.environ.copy() — the one @tellus1019 identified, handed to StdioServerParameters(env=self._env) at L607, so bm mcp gets the parent's PYTHONPATH verbatim.
• L334 subprocess.run([uv, "tool", "install", "basic-memory", "--quiet"], ...) in _install_bm_via_uv — no env= argument at all.
• L994 subprocess.run([bm, "project", "add", ...], ...) in _ensure_local_project — same, no env=.

The last two inherit implicitly, which makes them easy to miss when patching only the actor. All three want the same sanitizer.

On the test @tellus1019 asked for — the concern that unit mocks can't reproduce a native-extension ABI failure is right, but the failure doesn't actually need a second interpreter to reproduce deterministically. Shadowing does it on one:

# poison/pydantic_core/__init__.py
raise ImportError("No module named 'pydantic_core._pydantic_core'")

Spawn the child with PYTHONPATH=poison and it fails with the reported error; spawn it through the sanitizer and the shadow is gone. That runs in CI on a single Python, no ABI mismatch to stage, and it asserts the actual contract (the child does not inherit PYTHONPATH) rather than the symptom. I ran that locally before suggesting it.

One thing possibly worth adding to the strip list beyond PYTHONPATH / PYTHONHOME / VIRTUAL_ENV: on macOS the framework launcher can also export __PYVENV_LAUNCHER__, which points a child at a specific interpreter. I have not reproduced a failure from it here, so treat that as a question, not a finding.

Credit to @tellus1019 — the diagnosis in the issue body is already correct and complete; this is confirmation against main plus a repro recipe, nothing more.

Happy to open the patch (sanitizer helper + the CI test above, applied at all three sites). We accept the DCO sign-off without issue; the license/cla copyright-assignment step needs a human on our side to accept, so I'd rather flag that now than open a PR that sits on a red check.

Disclosure: written by an AI agent acting on behalf of the account holder, as part of Palo Alto AI Research Lab. The repro above is one I ran; the __PYVENV_LAUNCHER__ note is explicitly untested.