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

[naiyanat]

Summary

Replaces python3 -m mempalace with the mempalace shim in all 5 hook scripts. This fixes silent auto-save failures on any machine where $PATH resolves python3 to a venv that doesn't have mempalace installed.

The Bug

Hook scripts invoke the CLI via:

echo "$INPUT" | python3 -m mempalace hook run --hook stop --harness claude-code

On any machine where a Python tool has been installed via uv tool install (e.g. kimi-cli, llm, aider), ~/.local/share/uv/tools/<tool>/bin sits earlier in $PATH than /opt/homebrew/bin or /usr/bin. Bare python3 then resolves to that tool's isolated venv, which has no mempalace, and every hook fires:

/Users/nynat/.local/share/uv/tools/kimi-cli/bin/python3: No module named mempalace

On Claude Code this shows up as a Stop hook error on every conversation exit, which silently breaks auto-save. I hit this on a Mac Mini with kimi-cli installed via uv tool install kimi-cli. I'd expect it to be common — uv is mainstream now and uv tool is the recommended install path for Python CLIs.

The Fix

Call the mempalace shim directly. pipx, pip, and uv all install a wrapper at ~/.local/bin/mempalace (or equivalent) that internally dispatches to the correct venv's Python — so it's immune to $PATH ordering for python3 itself and survives Python version upgrades.

This also matches what the hook comments already document as the intended CLI:

# === MEMPALACE CLI ===
# This repo uses: mempalace mine <dir>

So the shell was diverging from its own documentation. The PR just brings them back into alignment.

Files Changed

5 files, 5 lines — pure text substitution:

File	What it runs
.claude-plugin/hooks/mempal-stop-hook.sh	mempalace hook run --hook stop --harness claude-code
.claude-plugin/hooks/mempal-precompact-hook.sh	mempalace hook run --hook precompact --harness claude-code
.codex-plugin/hooks/mempal-hook.sh	mempalace hook run --hook "$HOOK_NAME" --harness codex
hooks/mempal_save_hook.sh	mempalace mine "$MEMPAL_DIR" (optional auto-ingest block)
hooks/mempal_precompact_hook.sh	mempalace mine "$MEMPAL_DIR" (optional auto-ingest block)

Intentionally left alone:

• examples/gemini_cli_setup.md — uses .venv/bin/python3 -m mempalace, an absolute path which is immune to the hijack
• mempalace/onboarding.py — the python3 -m mempalace.onboarding string is a user-facing hint in a docstring, not a runtime call
• Inline python3 -c calls in hooks/mempal_*.sh — these only need stdlib (sys, json), which any python3 has, so they're not affected by the hijack

Compatibility

• No behaviour change on machines where bare python3 already resolves to a python with mempalace installed.
• Fixes the error on machines where it doesn't.
• Requires: mempalace shim on $PATH — which is the case for anyone who installed via pip install mempalace, pipx install mempalace, uv tool install mempalace, or the Claude Code plugin's bundled install.

Relates To

• mempal-stop-hook.sh calls nonexistent hook subcommand #323 — mempal-stop-hook.sh calls nonexistent hook subcommand. That issue is a different failure mode (running against mempalace 3.0.0 from PyPI, which doesn't have the hook subcommand yet — 3.0.14+ does). This PR is orthogonal: it fixes the $PATH hijack that triggers before the subcommand even runs. Both need to be resolved for the plugin to work out of the box.
• Bundle hook scripts in pip package #265 — Bundle hook scripts in pip package. That's the long-term architectural fix. This PR is a minimal stopgap that unblocks users today without touching package layout.

Test Plan

• grep -r "python3 -m mempalace" .claude-plugin .codex-plugin hooks returns no matches
• Verified the fix live on the affected Mac Mini (re-ran the stop hook, now returns {} with exit 0 instead of the No module named mempalace error)
• No Python code touched → pytest tests/ irrelevant for this change, but happy to run it if CI requests

Thanks for mempalace — it's been great!

[web3guru888]

Excellent PR. The bug report is thorough — the uv tool install PATH hijack is real and increasingly common as uv adoption grows. The fix is minimal and correct.

Why this is right:

• mempalace shim resolves to the correct venv regardless of $PATH ordering for python3
• The shim is installed by all standard methods (pip, pipx, uv, Claude Code plugin)
• The 5-line diff is pure text substitution in shell scripts — zero risk of Python regressions
• The intentional exclusions are well-reasoned (absolute-path .venv/bin/python3, stdlib-only python3 -c calls)

Overlap note: This PR is orthogonal to #340 (MCP entry point for pipx/uv) and #410 (PEP 668 entry point fix) — #325 fixes hook scripts, while #340/#410 fix the MCP server and CLI entry points. All three could land independently.

One edge case: If someone installed mempalace via git clone + pip install -e . but didn't install it as a system shim (just uses python3 -m mempalace), the hooks would break. But that's an uncommon dev-only setup, and the fix is just pip install -e . which creates the shim anyway. Worth a note in the hook comments, but not a blocker.

Clean, focused, well-documented. +1

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

[igorls]

Hi, thanks for the contribution.

This PR has merge conflicts with develop, and the branch has not been updated in over 7 days, which puts it before our most recent release. The conflicts are likely against work that landed in that release.

Could you rebase onto develop so we can take another look?

If this change is no longer relevant, feel free to close the PR.

(This message is part of a periodic backlog pass, sent to all open PRs that match this state.)