mempalace/README.md

# 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 <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)

```bash
# 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`](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://<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):

```json
{
  "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`](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.