rawgentic-memorypalace
v0.4.2 · Claude Code plugin providing long-term memory powered by MemPalace. Bridges Claude Code's hook system to MemPalace's Python API via a slim HTTP gatekeeper + adapter layer, with native MemPalace hooks handling ingest.
Architecture (r3)
Three independent pieces cooperate:
- MemPalace (upstream) — the memory engine: palace-organized storage (wings/rooms/drawers), BM25 + semantic hybrid search, four layered wake-up (L0–L3), knowledge graph, fact-checking, AAAK dialect.
- MemPalace MCP server (upstream) — exposes ~29 tools (
mempalace_search, mempalace_diary_write, mempalace_add_drawer, mempalace_kg_query, etc.) to any LLM client over stdio.
- rawgentic-memorypalace (this plugin) — the bridge. Three bash hooks + slim HTTP server + versioned adapter that connect Claude Code's session events to the memory engine.
Why a bridge?
Claude Code hooks are short-lived bash processes. They can't import mempalace directly — they need a persistent server. ChromaDB also can't safely handle multi-process writes. So the bridge runs a single-process HTTP server (:8420) that serializes all palace access behind a stable adapter interface (CONTRACT_VERSION=3, MIN_VERSION=3.3.0, MAX_VERSION<4.0).
What mempalace handles natively (not us)
- L0 identity —
~/.mempalace/identity.txt injected at every session start
- L1 memory context — recent memories, diary entries, and per-wing context at session start
- 19+ MCP tools — search, diary, drawers, KG, tunnels, etc.
- Background mining — conversation transcript and project content ingest
- Stop/PreCompact hooks — auto-save session content via MCP tools
What this bridge adds (our unique value)
| Layer | Trigger | Mechanism | Cost |
|---|
| Tunnel context | SessionStart hook | GET /wakeup → cross-wing topic tunnels for multi-project awareness | One HTTP call per session |
| L2 — Auto-recall | UserPromptSubmit hook | Smart-gated POST /search on substantive prompts (> 20 chars, no slash commands, stop-words filtered, debounced) | ≤ 1 HTTP call per prompt |
| L3 — Proactive MCP | LLM reasoning | Claude directly calls mcp__mempalace__mempalace_search / mempalace_kg_query mid-thought | Zero infra cost — model budget only |
| L4 — Fact-checking | PostToolUse on Edit/Write/MultiEdit | Throttled POST /fact_check against file content | ≤ 1 HTTP call per file (per-session dedup) |
Ingest path
Unlike r1/r2, this plugin does no custom ingestion. The plugin's mempalace-hook-wrapper.sh script (at hooks/mempalace-hook-wrapper.sh, configured in ~/.claude/settings.json for Stop and PreCompact events) handles it. The Stop hook injects a systemMessage instructing the LLM to save session content via MCP tools (mempalace_diary_write, mempalace_add_drawer, mempalace_kg_add). The PreCompact hook forks the session to save before compaction (blocks compaction on failure). All writes route through the adapter's canary_write() in tests.
Prerequisites
- Python 3.12+ (mempalace's minimum)
jq (hook JSON parsing)curl (hook HTTP calls)- MemPalace 3.3.4+ installed. Preferred:
pipx install mempalace (isolates in its own venv). Alternative: pip install --user mempalace. Upgrade: /rawgentic-memorypalace:upgrade (auto-detects pipx vs pip).
Installation
claude plugin install rawgentic-memorypalace@rawgentic-memorypalace
This installs the bridge (HTTP server + bash hooks). MemPalace itself and the MemPalace MCP server are separate setup steps — the bridge alone can't know which Python environment holds your MemPalace install, so it doesn't guess.
MCP Setup
Pick the path that matches your deployment:
(a) Single-workstation, pip install --user mempalace:
claude mcp add -s user mempalace -- python3 -m mempalace.mcp_server
Works if python3 on PATH has mempalace importable.
(b) Single-workstation, pipx install mempalace:
claude mcp add -s user mempalace -- ~/.local/share/pipx/venvs/mempalace/bin/python -m mempalace.mcp_server
pipx isolates mempalace in its own venv — point at that venv's python directly.
(c) Central server (multiple client hosts share one palace via SSH):
On the server host (e.g. 10.0.17.205), install mempalace and run the slim server bound to a LAN-reachable address (see Central Server below). On each client host:
claude mcp add -s user mempalace -- ssh <server-host> exec ~/.local/share/pipx/venvs/mempalace/bin/python -m mempalace.mcp_server
MCP's stdio protocol tunnels over SSH — all palace operations execute in the server's mempalace process. Clients need SSH access but no local mempalace install.
After install, configure your identity:
