# MemPalace — server-mode fork Local-first AI memory, deployed as a shared service across machines. This is a personal fork of [MemPalace](https://github.com/MemPalace/mempalace) configured for **server-mode deployment**: MemPalace runs as a Docker container (typically on Unraid) and multiple AI tools — Claude Code, Codex, Antigravity, or any MCP-compatible client — connect to a single shared palace from any machine on the network. Auto-save hooks on each client push session transcripts to the server over HTTPS with bearer auth. The upstream project remains local-first by design. This fork makes one deliberate trade: data crosses the LAN to a user-controlled server instead of staying on the originating machine. Privacy, verbatim storage, no-cloud, and no-telemetry properties are otherwise unchanged. See [CLAUDE.md](CLAUDE.md) for the architectural reasoning. --- ## What's in this fork ``` home LAN ┌───────────────────────────────────┐ │ Unraid (always on) │ │ ┌────────────────────────────┐ │ │ │ caddy :8443 (TLS + auth) │ │ │ │ ├─ /sse → mcp-proxy │ │ │ │ └─ /ingest → ingest API │ │ │ │ mempalace (single process) │ │ │ │ ├─ mcp-proxy :8765 │ │ │ │ └─ ingest :8766 │ │ │ └────────────────────────────┘ │ └───────────────────────────────────┘ │ │ │ ┌────┴───┐ ┌────┴───┐ ┌────┴─────┐ │ Claude │ │ Codex │ │ Antigrav │ └────────┘ └────────┘ └──────────┘ ``` * **One palace, many clients.** Search and write target the same ChromaDB index regardless of which machine you're on. * **Single bearer token gates everything.** Caddy sidecar terminates TLS and enforces `Authorization: Bearer ` at the edge. * **Auto-save hooks work across machines.** Each client's `Stop` and `PreCompact` events POST the active transcript to the server's `/ingest/transcript` endpoint; the server-side miner runs the existing entity-detection / room-assignment / dedup pipeline. * **Single ChromaDB writer.** The HTTP ingest endpoint runs as a daemon thread inside the same Python process as the MCP server — ChromaDB's HNSW index isn't safe across processes, so this is the safe shape. What this fork is **not**: a multi-tenant cloud service. One palace, one token, no per-user isolation. Designed for a single user with multiple machines. --- ## Concepts MemPalace stores conversation history as verbatim text and retrieves it with semantic search. It does not summarize, extract, or paraphrase. The index is structured: * **Wings** — broad categories (people, projects, topics) * **Rooms** — time-based or topical groupings (days, sessions, themes) * **Drawers** — verbatim content chunks (your exact words) * **AAAK compression** — symbolic dialect for the index layer; an LLM can scan thousands of entries in one prompt and know which drawer to open Same palace, two ingest paths: **project mining** (code, docs, notes) and **conversation mining** (Claude Code / Codex JSONL transcripts). --- ## Quickstart ### 1. Deploy the server (Unraid) ```bash # On Unraid: cd /mnt/user/system/build && git clone mempalace && cd mempalace/deploy/unraid TOKEN=$(openssl rand -hex 32) echo "MEMPAL_TOKEN=$TOKEN" > .env chmod 600 .env mkdir -p /mnt/user/appdata/mempalace /mnt/user/appdata/mempalace-caddy/{data,config} chown -R 99:100 /mnt/user/appdata/mempalace /mnt/user/appdata/mempalace-caddy docker compose up -d --build echo "Token: $TOKEN" # save to your password manager ``` Verify: `curl -k https://:8443/healthz` returns `{"status":"ok",...}`. Full deployment guide: [`deploy/unraid/README.md`](deploy/unraid/README.md). ### 2. Connect a client (per machine) Install `mcp-proxy` once: `uv tool install mcp-proxy` (or `pip install mcp-proxy`). Set environment variables: ```powershell # Windows PowerShell: [Environment]::SetEnvironmentVariable("MEMPAL_REMOTE_URL", "https://:8443", "User") [Environment]::SetEnvironmentVariable("MEMPAL_REMOTE_TOKEN", "", "User") [Environment]::SetEnvironmentVariable("MEMPAL_REMOTE_INSECURE", "1", "User") # self-signed cert ``` Add to your AI tool's MCP config (Claude Code `~/.claude.json`, Codex `~/.codex/config.toml`, Antigravity MCP settings): ```json { "mcpServers": { "mempalace": { "command": "mcp-proxy", "args": [ "https://:8443/sse", "--headers", "Authorization", "Bearer " ] } } } ``` ### 3. Wire up auto-save hooks Point Claude Code's `Stop` and `PreCompact` hooks at [`hooks/mempal_save_hook_remote.sh`](hooks/mempal_save_hook_remote.sh) and [`hooks/mempal_precompact_hook_remote.sh`](hooks/mempal_precompact_hook_remote.sh). Same shape for Codex via `.codex/hooks.json`. See [`hooks/README.md`](hooks/README.md) for the JSON config and env-var contract. --- ## Repository layout ``` mempalace/ # Python package (source unchanged from upstream) ├── mcp_server.py # MCP stdio server — all read/write tools ├── ingest_server.py # HTTP transcript-ingest endpoint (server mode) └── ... # see CLAUDE.md for full layout deploy/unraid/ # Server-mode deployment ├── docker-compose.yml # mempalace + caddy sidecar ├── Caddyfile # bearer-token auth, TLS, SSE-aware proxy ├── mempalace-server.xml # dockerMan template (no-auth fallback) └── README.md # Full install / troubleshooting guide hooks/ # Hook scripts for AI clients ├── mempal_save_hook_remote.sh ├── mempal_precompact_hook_remote.sh └── README.md Dockerfile # Builds the server image .dockerignore ``` --- ## Knowledge graph MemPalace includes a temporal entity-relationship graph with validity windows (add, query, invalidate, timeline) backed by local SQLite. Accessible via the MCP tools (`mempalace_kg_*`) over the same SSE endpoint. Tool reference: [mempalaceofficial.com/concepts/knowledge-graph](https://mempalaceofficial.com/concepts/knowledge-graph.html). --- ## Requirements * **Server (Unraid):** Docker + Compose Manager plugin. Image uses Python 3.13-slim. ~300 MB disk for the embedding model after first request. ~22 MB repo working tree. * **Clients:** [`mcp-proxy`](https://github.com/sparfenyuk/mcp-proxy) and `curl`. Python 3 on PATH only if you use the auto-save hooks (the hooks parse stdin JSON via Python stdlib). No API key is required at any stage. The default embedding model (all-MiniLM-L6-v2 ONNX) runs on CPU on the server. --- ## Docs * **Agent usage guide** → [`docs/AGENT_GUIDE.md`](docs/AGENT_GUIDE.md) — feed this to Claude Code / Codex / Antigravity so they know what tools exist, when to use which, and the workflow patterns. Drop into `~/.claude/CLAUDE.md` for global scope or a project's `CLAUDE.md` for project scope. * Server deployment → [`deploy/unraid/README.md`](deploy/unraid/README.md) * Hook setup → [`hooks/README.md`](hooks/README.md) * Project conventions and architecture (for editing this codebase) → [`CLAUDE.md`](CLAUDE.md) * Release notes (this fork) → [`CHANGELOG.md`](CHANGELOG.md) * Upstream CLI / Python API / concepts → [mempalaceofficial.com](https://mempalaceofficial.com) --- ## License MIT — see [LICENSE](LICENSE). Upstream copyright belongs to the MemPalace authors; modifications in this fork are also MIT.