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

[messelink]

Summary

Two related fixes for installation-method compatibility:

1. 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.
2. 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]

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.