This is a personal fork of 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 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 <token> 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)

# On Unraid:
cd /mnt/user/system/build && git clone <this-repo> 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://<unraid-ip>:8443/healthz returns {"status":"ok",...}.

Full deployment guide: 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:

# Windows PowerShell:
[Environment]::SetEnvironmentVariable("MEMPAL_REMOTE_URL",   "https://<unraid-ip>:8443", "User")
[Environment]::SetEnvironmentVariable("MEMPAL_REMOTE_TOKEN", "<the-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):

{
  "mcpServers": {
    "mempalace": {
      "command": "mcp-proxy",
      "args": [
        "https://<unraid-ip>:8443/sse",
        "--headers", "Authorization", "Bearer <the-token>"
      ]
    }
  }
}

3. Wire up auto-save hooks

Point Claude Code's Stop and PreCompact hooks at hooks/mempal_save_hook_remote.sh and hooks/mempal_precompact_hook_remote.sh. Same shape for Codex via .codex/hooks.json. See 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.

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 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 — 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
Hook setup → hooks/README.md
Project conventions and architecture (for editing this codebase) → CLAUDE.md
Release notes (this fork) → CHANGELOG.md
Upstream CLI / Python API / concepts → mempalaceofficial.com

License

MIT — see LICENSE. Upstream copyright belongs to the MemPalace authors; modifications in this fork are also MIT.