fix: add mempalace-mcp entry point for pipx/uv compatibility by messelink · Pull Request #340 · MemPalace/mempalace

messelink · 2026-04-09T06:40:08Z

Summary

Two related fixes for installation-method compatibility:

Adds a mempalace-mcp console_scripts entry point in pyproject.toml so the MCP server works with all installation methods (pip, pipx, uv, conda). Updates plugin configs (.claude-plugin/.mcp.json, .claude-plugin/plugin.json, .codex-plugin/plugin.json) to use mempalace-mcp instead of python3 -m mempalace.mcp_server. Updates docs (README, examples, instructions) to reflect the new command.
Updates hook scripts to use the mempalace CLI (hooks/mempal-precompact-hook.sh, hooks/mempal-stop-hook.sh, .codex-plugin/hooks/mempal-hook.sh) instead of python3 -m mempalace hook run .... Same root cause, same class of fix.

Problem

When mempalace is installed via pipx or uv, both python -m mempalace.mcp_server (MCP server config) and python3 -m mempalace hook run ... (hook scripts) fail because the system Python can't find the module inside the isolated venv. The MCP plugin fails to connect, and stop/precompact hooks fail silently (or loudly) with No module named mempalace.

Solution

Console scripts installed by setuptools/hatchling go on PATH for pip, pipx, and uv alike — just like the existing mempalace CLI entry point. A new mempalace-mcp entry point exposes the MCP server the same way. Hook scripts switch to calling the mempalace CLI directly (which pipx/uv put on PATH) instead of python3 -m mempalace.

Test plan

pip install -e . and verify mempalace-mcp starts the MCP server
pipx install . and verify mempalace-mcp is on PATH and works
pipx install . and verify stop/precompact hooks run without No module named mempalace errors
claude mcp add mempalace -- mempalace-mcp connects successfully

Notes on rebase

This branch has been rebased onto current develop (v3.3.0+). The [project.scripts] section conflicted because develop refactored mempalace = "mempalace:main" → mempalace = "mempalace.cli:main". Resolution combines both: the new cli entry point path is preserved, and mempalace-mcp is added alongside it.

⚠️ Known limitation: restart MCP servers after upgrading

This fix makes the MCP server runnable via pipx/uv, which surfaces a latent Python process-lifecycle issue. Long-running MCP server processes cache mempalace and chromadb in sys.modules at startup and never reload them. After any subsequent upgrade — pipx install --force -e ., pip install -U mempalace, uv pip install -U, etc. — already-running MCP server processes continue serving tool calls with the stale libraries, even though the CLI (fresh Python each invocation) picks up the new version immediately.

In practice this means: after upgrading mempalace or any of its dependencies (especially chromadb, which has had breaking format changes between 0.6.x and 1.5.x), you must restart any active Claude Code MCP servers to pick up the new code. Ways to do this:

Claude Code: disable and re-enable the mempalace plugin's MCP in settings (the /mcp command or the Settings → MCP UI). This closes the stdio pipe, the Python process exits, and Claude Code respawns a fresh one on the next tool call.
Alternative: restart Claude Code entirely (exit and relaunch). The bulletproof method, also handles plugin reload edge cases.

Without restarting, stale MCP servers can write rows with legacy storage formats (e.g., seq_id as BLOB under chromadb 0.6.x) that cause fresh processes to crash during compaction on read. Not caused by this PR — the same bug would affect pip install -U mempalace users without pipx/uv — but this PR makes more users able to actually run the MCP server, so the bug is more visible in practice.

Tracked as: #899 (MCP server silently serves with stale library versions after package upgrade). The long-term fix is a version check at tool-call time or an automatic self-restart mechanism; this PR only documents the manual workaround until a code fix lands.

🤖 Generated with Claude Code

nzkdevsaider · 2026-04-09T11:44:55Z

Hi! I’ve been working on expanding the README.md to include installation steps for MCP in this PR. Please take a look!

web3guru888

Clean and well-scoped fix. The python3 -m mempalace.mcp_server pattern is exactly the kind of thing that breaks in isolated venvs (pipx, uv) — we hit this ourselves when deploying across different environments.

The change is straightforward: one new console_scripts entry point + consistent updates across all plugin configs and docs. LGTM.

One thing to flag: #410 (armujahid) does mempalace mcp-serve as a subcommand instead of a separate mempalace-mcp entry point. Both solve the same problem but with different UX. The separate entry point approach here is simpler and follows the pattern other MCP servers use, while the subcommand approach avoids adding another binary to PATH. Maintainers will want to pick one and close the other.

From an integration standpoint, the separate entry point is slightly preferable — it means MCP configs don't need to know about argument parsing, just a single command name.

🔭 Reviewed as part of the MemPalace-AGI integration project — autonomous research with perfect memory. Community interaction updates are posted regularly on the dashboard.

The MCP server config used `python -m mempalace.mcp_server` which fails when mempalace is installed via pipx or uv, since the system python cannot find the module in the isolated venv. Adding a `mempalace-mcp` console_scripts entry point ensures the MCP server works regardless of installation method (pip, pipx, uv, conda). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Hook scripts used `python3 -m mempalace` which fails when mempalace is installed via pipx or uv. Using the `mempalace` CLI command directly works for all installation methods. Dev users running from source should use `pip install -e .` as documented in CONTRIBUTING.md. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

hooks/mempal_precompact_hook.sh and hooks/mempal_save_hook.sh used python3 -m mempalace mine which fails when mempalace is installed via pipx or uv. Switch to the mempalace CLI entry point which pipx/uv put on PATH. Also removes the now-unused PYTHON variable from mempal_save_hook.sh. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

cmd_mcp() in cli.py was still printing `python -m mempalace.mcp_server` as the setup command. Update to use the mempalace-mcp console entry point added in the previous commit. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Three assertions in test_mcp_command_* were still checking for the old `python -m mempalace.mcp_server` output string. Update to match the new `mempalace-mcp` command printed by cmd_mcp(). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

The legacy hook scripts `hooks/mempal_save_hook.sh` and `hooks/mempal_precompact_hook.sh` shell out to `python3` for JSON parsing and transcript-message counting. On macOS GUI launches of Claude Code — `open -a`, Spotlight, the dock — the harness inherits `PATH` from launchd (`/usr/bin:/bin:/usr/sbin:/sbin`), which may not contain a `python3` at all, or may contain only a system Python that lacks what the hook needs. The hook then fails silently in the background log where users never look. `mempalace` auto-ingest itself is unaffected — #340 switched that path to the `mempalace` CLI entry point, which pipx/uv install on a stable global PATH. This PR adds a `MEMPAL_PYTHON` environment variable that users can set to point the hook at any Python 3 interpreter. Resolution order applied at each `python3` invocation site inside the two hooks: 1. $MEMPAL_PYTHON (if set and executable) 2. $(command -v python3) on PATH 3. bare `python3` as a last resort The interpreter does not need `mempalace` installed in it — only the standard-library `json` and `sys` modules. The hook's `mempalace mine` call runs via the CLI, independent of this override. hooks/README.md documents the macOS GUI PATH issue and the MEMPAL_PYTHON override. tests/test_hooks_shell.py adds 3 regression tests (Linux/macOS only, POSIX bash): - MEMPAL_PYTHON override wins over PATH (proved via a marker-emitting shim that proxies to the real interpreter). - Non-executable MEMPAL_PYTHON falls back to PATH rather than crashing on permission denied. - Unset MEMPAL_PYTHON resolves via PATH. `hooks_cli.py` (the Python implementation invoked via `mempalace hook run ...`) already uses `sys.executable` and is therefore trivially correct — no changes needed there. Supersedes abandoned branch `fix/hook-bugs`. Co-Authored-By: MSL <232237854+milla-jovovich@users.noreply.github.com>

Resolutions: - `.claude-plugin/.mcp.json`, `plugin.json` — adopt upstream's `mempalace-mcp` console-script command (added via upstream MemPalace#340 for pipx/uv). Run `pip install -e .` in plugin venv after merge to install the entry point. - `.claude-plugin/hooks/*.sh`, `hooks/*.sh` — adopt upstream's console-command resolution order (`mempalace` script → `python3 -m mempalace` → `python`). `MEMPAL_PYTHON` override still works inside `hooks_cli.py`. - `mempalace/hooks_cli.py`, `tests/test_hooks_cli.py` — keep fork's `_mempalace_python()` helper (fork-ahead #4); upstream only had `sys.executable`, which loses MEMPAL_PYTHON override. - `mempalace/miner.py` — keep fork's concurrent mining path (fork-ahead #1), apply upstream's unicode-`✓` → ASCII-`+` fix (MemPalace#681) to both paths. - `mempalace/backends/chroma.py` — take upstream's refined `quarantine_stale_hnsw` docstring (it's the version merged via our own MemPalace#1000). Brought in: 33 upstream commits including Belarusian/Chinese/German/Spanish/French entity detection, console-script entry points, hook plugin-root space quoting, and v3.3.2 tag (which contains our MemPalace#681/MemPalace#1000/MemPalace#1023). Tests: 1096 passed, 106 deselected (benchmarks). Ruff clean.

@messelink

Restore-integrity release. Unbreaks fresh `pip install mempalace` from v3.3.2 by re-tagging current develop, which carries both the plugin.json consumer (shipped in 3.3.2) and the matching mempalace-mcp entry point in pyproject.toml (added on develop ~10h after the 3.3.2 tag via MemPalace#340 by @messelink). MemPalace#1093 diagnosed by @jphein. Bumps (all 5 sources agree per Version Guard / CLAUDE.md): - mempalace/version.py 3.3.2 → 3.3.3 - pyproject.toml 3.3.2 → 3.3.3 - .claude-plugin/plugin.json 3.3.2 → 3.3.3 - .claude-plugin/marketplace.json 3.3.2 → 3.3.3 - .codex-plugin/plugin.json 3.3.2 → 3.3.3 - CHANGELOG.md new [3.3.3] entry No code changes. The fix for MemPalace#1093 is already on develop via merged PRs MemPalace#340, MemPalace#1021, MemPalace#851, MemPalace#942, MemPalace#833, MemPalace#673, MemPalace#661, MemPalace#659, MemPalace#1097, MemPalace#1051, MemPalace#1001, MemPalace#945. Branch name intentionally outside the `release/*` ruleset so follow-up CI-fix commits aren't gated behind a nested PR. (Supersedes MemPalace#1143 — closed for exactly that reason after it missed 3 of 5 version files.) Smoke-tested locally from a fresh develop clone: grep mempalace-mcp pyproject.toml .claude-plugin/plugin.json # both ✓ python -m build --wheel # ✓ pip install …-py3-none-any.whl # ✓ which mempalace-mcp # ✓ mempalace-mcp --help # ✓

Fulfills the "Optional: release-checklist addition" proposal at the bottom of MemPalace#1093 (the v3.3.2 release defect where plugin.json referenced a mempalace-mcp binary that pyproject.toml never declared, so fresh `pip install` was broken for everyone until messelink's MemPalace#340 was re-cut as v3.3.3). New file at docs/RELEASING.md (no existing doc at that path) with a single pre-release grep: grep -rn mempalace-mcp pyproject.toml .claude-plugin .codex-plugin The original MemPalace#1093 proposal specified `pyproject.toml .claude-plugin/plugin.json` (2 files). This expands via -rn directory recursion to also cover `.claude-plugin/.mcp.json` and `.codex-plugin/plugin.json`, which reference `mempalace-mcp` by name too — same class of regression through a different surface. Happy to trim to the narrower 2-file form if preferred; one-line edit. Shows the concrete expected output so a maintainer running this under release pressure can eyeball "pass" without mental translation, and points at MemPalace#340 as the historical fix anchor so "investigate why the entry is missing" has a diagnostic starting point rather than a dead end. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

@igorls

… state Three stale sections updated: - Fork change queue: row 8 (.blob_seq_ids_migrated marker) struck through → FILED as MemPalace#1177. Two new rows added for segfault fixes discovered today (MemPalace#1171 concurrent-write lock, MemPalace#1173 quarantine in make_client) that weren't in the queue because the bugs surfaced today, not during the original 2026-04-21 triage. - Open upstream PRs: was showing 3 of 10 PRs. Now shows all 10 with current CI/review state. All rebased onto current upstream/develop and MERGEABLE as of today. - Merged since v3.3.1: added v3.3.3 release (2026-04-24) with its constituent merges — MemPalace#942, MemPalace#833, MemPalace#1097, MemPalace#1145, MemPalace#1147, MemPalace#1148/1150/1157 entity-detection overhaul (via @igorls's MemPalace#1175 stacked-PR rescue), MemPalace#1166 palace-path security, MemPalace#340/MemPalace#1093 install regression, plus MemPalace#851 from the 2026-04-22 batch.

v3.3.3 — restore install integrity See CHANGELOG.md for the full release notes. Headline fix: the mempalace-mcp console-script drift in v3.3.2. The plugin.json referenced a binary that pyproject.toml never declared, so every fresh 'pip install mempalace==3.3.2' produced a broken Claude Code plugin config. Fixed by MemPalace#340 (messelink) and follow-ups in MemPalace#1147 (igorls). # Conflicts: # CHANGELOG.md # mempalace/hooks_cli.py # tests/test_hooks_cli.py

messelink force-pushed the fix/mcp-pipx-compat branch from 9e40b1f to 15a6af2 Compare April 9, 2026 15:16

web3guru888 reviewed Apr 10, 2026

View reviewed changes

This was referenced Apr 10, 2026

fix: replace python3 -m mempalace with CLI entry point (PEP 668) #410

Open

fix(hooks): use mempalace shim instead of bare python3 -m mempalace #325

Open

messelink force-pushed the fix/mcp-pipx-compat branch 3 times, most recently from 2c4022c to 8ecd0a2 Compare April 10, 2026 16:06

messelink requested review from bensig and milla-jovovich as code owners April 10, 2026 16:06

messelink force-pushed the fix/mcp-pipx-compat branch from 8ecd0a2 to 95f514d Compare April 11, 2026 16:39

bensig changed the base branch from main to develop April 11, 2026 22:22

bensig requested a review from igorls as a code owner April 11, 2026 22:22

igorls added area/hooks Claude Code hook scripts (Stop, PreCompact, SessionStart) area/install pip/uv/pipx/plugin install and packaging area/mcp MCP server and tools bug Something isn't working labels Apr 14, 2026

messelink force-pushed the fix/mcp-pipx-compat branch from 95f514d to b394221 Compare April 14, 2026 15:13

messelink mentioned this pull request Apr 15, 2026

MCP server silently serves with stale library versions after package upgrade #899

Open

This was referenced Apr 16, 2026

fix(hooks): resolve Claude plugin hook runner cross-platform #942

Merged

Hooks and MCP server break in projects with Python venv (hardcoded python3) #1049

Open

messelink and others added 5 commits April 21, 2026 01:26

igorls force-pushed the fix/mcp-pipx-compat branch from 784b14a to 9e53228 Compare April 21, 2026 04:31

igorls merged commit 5522d34 into MemPalace:develop Apr 21, 2026
7 checks passed

igorls mentioned this pull request Apr 21, 2026

docs(readme): Improve MCP configuration guide and streamline setup with uvx #109

Closed

3 tasks

sha2fiddy mentioned this pull request Apr 21, 2026

Consolidate hooks/mempal_*_hook.sh into thin wrappers delegating to mempalace hook run #1069

Open

jphein mentioned this pull request Apr 22, 2026

v3.3.2 release defect: mempalace-mcp entry point missing from pyproject.toml despite plugin.json requiring it — MCP server fails to start on fresh install #1093

Closed

This was referenced Apr 23, 2026

release: v3.3.3 — restore install integrity #1143

Closed

release: v3.3.3 — restore install integrity #1144

Merged

bensig mentioned this pull request Apr 24, 2026

release: v3.3.3 — sync develop → main for tag cut #1159

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix: add mempalace-mcp entry point for pipx/uv compatibility#340

fix: add mempalace-mcp entry point for pipx/uv compatibility#340
igorls merged 5 commits intoMemPalace:developfrom
messelink:fix/mcp-pipx-compat

messelink commented Apr 9, 2026 •

edited

Loading

Uh oh!

nzkdevsaider commented Apr 9, 2026

Uh oh!

web3guru888 left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

messelink commented Apr 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Problem

Solution

Test plan

Notes on rebase

⚠️ Known limitation: restart MCP servers after upgrading

Uh oh!

nzkdevsaider commented Apr 9, 2026

Uh oh!

web3guru888 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

messelink commented Apr 9, 2026 •

edited

Loading