Skip to content

Commit 8ec284d

Browse files
igorlsigorls
authored
docs(guide): add Remote / Team Server deployment guide (#1877) (#1897)
Documents running MemPalace as a central memory service for a team: HTTP MCP transport (--transport http with bearer-token auth), a networked backend (Qdrant via REST, no extra dep; or pgvector), and optional GPU embedding. Covers the security model (non-loopback token requirement, Host/Origin DNS-rebinding guard, TLS-in-front), client connection, and operating notes. Adds the page to the guide sidebar. Addresses #1877.
1 parent 5dcc46b commit 8ec284d

2 files changed

Lines changed: 159 additions & 0 deletions

File tree

‎website/.vitepress/config.mts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -63,6 +63,7 @@ export default withMermaid(
6363
{ text: 'Auto-Save Hooks', link: '/guide/hooks' },
6464
{ text: 'Cursor IDE Hooks', link: '/guide/cursor-hooks' },
6565
{ text: 'Configuration', link: '/guide/configuration' },
66+
{ text: 'Remote / Team Server', link: '/guide/remote-server' },
6667
],
6768
},
6869
],

‎website/guide/remote-server.md‎

Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,158 @@
1+
# Remote / Team Server
2+
3+
Run MemPalace as a **central memory service** that a whole team connects to:
4+
one host stores the palace, does the embedding (optionally on a GPU), and
5+
serves MCP over HTTP. Every teammate's AI reads and writes the same shared
6+
memory instead of a palace on each laptop.
7+
8+
This is built from three pieces that already ship in MemPalace:
9+
10+
- the **HTTP transport** for the MCP server (`mempalace-mcp --transport http`),
11+
- a **networked storage backend** ([Qdrant](https://qdrant.tech/) or
12+
[Postgres + pgvector](/guide/configuration)),
13+
- optional **GPU embedding** on the server.
14+
15+
::: warning This is a deliberate step away from single-machine local-first
16+
By default MemPalace keeps everything on your own machine. A central server is
17+
still **your** infrastructure — no third-party API, no telemetry, nothing
18+
phones home — but your verbatim memory now lives on a server you operate and
19+
travels over your network. Run every component (Qdrant, the MCP host) on
20+
hardware you control, put it on a private network or VPN, and treat the
21+
bearer token and TLS setup below as mandatory, not optional. Embeddings are
22+
still produced locally on the server by MemPalace; only your own storage
23+
backend ever receives the vectors and text.
24+
:::
25+
26+
## Architecture
27+
28+
```
29+
Teammate A ─┐
30+
Teammate B ─┤ MCP over HTTP ┌─ mempalace-mcp --transport http
31+
Teammate C ─┴──(bearer token, TLS)─▶│ (one host: embedding + GPU)
32+
└─────────────┬───────────────
33+
│ vectors + verbatim text
34+
▼
35+
Qdrant / pgvector
36+
(central storage)
37+
```
38+
39+
## 1. Central storage
40+
41+
Pick a networked backend so all clients share one palace. **Qdrant** needs no
42+
extra Python package — MemPalace talks to its REST API directly.
43+
44+
Run Qdrant (Docker shown; use a managed/self-hosted instance you control):
45+
46+
```bash
47+
docker run -d --name qdrant -p 6333:6333 \
48+
-v "$HOME/qdrant_storage:/qdrant/storage" \
49+
qdrant/qdrant
50+
```
51+
52+
Point MemPalace at it on the server host:
53+
54+
```bash
55+
export MEMPALACE_BACKEND=qdrant
56+
export MEMPALACE_QDRANT_URL=http://localhost:6333
57+
export MEMPALACE_QDRANT_API_KEY=your-qdrant-api-key # if your Qdrant requires one
58+
```
59+
60+
| Variable | Default | Purpose |
61+
|---|---|---|
62+
| `MEMPALACE_BACKEND` | `chroma` | Set to `qdrant` (or `pgvector`) to select the backend |
63+
| `MEMPALACE_QDRANT_URL` | `http://localhost:6333` | Qdrant REST endpoint |
64+
| `MEMPALACE_QDRANT_API_KEY` | _(none)_ | Sent as the `api-key` header when set |
65+
| `MEMPALACE_QDRANT_NAMESPACE` | _(none)_ | Optional collection namespace prefix |
66+
| `MEMPALACE_QDRANT_TIMEOUT` | backend default | REST request timeout (seconds) |
67+
68+
The backend can also be set with `--backend qdrant` on any `mempalace` /
69+
`mempalace-mcp` command, or with `"backend": "qdrant"` in `config.json`.
70+
71+
Prefer Postgres? Install `pip install mempalace[pgvector]`, point
72+
`MEMPALACE_BACKEND=pgvector` at a database with the `vector` extension, and
73+
the rest of this guide applies unchanged.
74+
75+
## 2. GPU embedding (optional)
76+
77+
Embedding is the heaviest step; running it on the server's GPU keeps recall
78+
fast for everyone. Install one acceleration extra and select the device:
79+
80+
```bash
81+
pip install mempalace[gpu] # NVIDIA CUDA (onnxruntime-gpu)
82+
export MEMPALACE_EMBEDDING_DEVICE=cuda
83+
```
84+
85+
Other targets: `mempalace[dml]` + `MEMPALACE_EMBEDDING_DEVICE=dml` (DirectML,
86+
Windows AMD/Intel/NVIDIA), `mempalace[coreml]` + `=coreml` (Apple Neural
87+
Engine), or `=auto` to pick the best available provider. CPU is the default
88+
and needs no extra.
89+
90+
## 3. Serve MCP over HTTP
91+
92+
The MCP server speaks JSON-RPC over `POST /mcp` and exposes an unauthenticated
93+
`GET /healthz` liveness probe for orchestrators. Binding to a **non-loopback**
94+
host requires a bearer token — MemPalace refuses to start otherwise.
95+
96+
```bash
97+
export MEMPALACE_MCP_HTTP_TOKEN="$(openssl rand -hex 32)"
98+
99+
mempalace-mcp --transport http --host 0.0.0.0 --port 8765 --backend qdrant
100+
```
101+
102+
| Flag / variable | Default | Purpose |
103+
|---|---|---|
104+
| `--transport http` | `stdio` | Serve over HTTP instead of stdio |
105+
| `--host` | `127.0.0.1` | Bind address (`0.0.0.0` to accept remote clients) |
106+
| `--port` | `8765` | Listen port |
107+
| `MEMPALACE_MCP_HTTP_TOKEN` | _(none)_ | **Required** for non-loopback binds; clients send `Authorization: Bearer <token>` |
108+
109+
The server protects against DNS-rebinding with a `Host` allowlist and an
110+
`Origin` loopback check, and serializes concurrent writes — so multiple
111+
teammates can write to the shared palace at once over HTTP.
112+
113+
::: danger Put TLS in front of it
114+
The HTTP server is plaintext. For anything beyond a trusted private network,
115+
run it behind a reverse proxy (nginx/Caddy/Traefik) terminating TLS, and keep
116+
the bearer token secret. Only set
117+
`MEMPALACE_MCP_HTTP_ALLOW_INSECURE_NO_TOKEN=1` when a trusted fronting layer
118+
already enforces access control — never on a directly-exposed port.
119+
:::
120+
121+
## 4. Connect a client
122+
123+
Point each teammate's MCP client at the server's `/mcp` endpoint with the
124+
shared token. For Claude Code:
125+
126+
```bash
127+
claude mcp add --transport http mempalace https://memory.example.com/mcp \
128+
--header "Authorization: Bearer $MEMPALACE_MCP_HTTP_TOKEN"
129+
```
130+
131+
Other MCP clients use the same two ingredients — the `…/mcp` URL and an
132+
`Authorization: Bearer <token>` header. Verify connectivity from any host:
133+
134+
```bash
135+
curl https://memory.example.com/healthz # -> ok
136+
```
137+
138+
Once connected, all of MemPalace's [MCP tools](/guide/mcp-integration) operate
139+
against the shared palace — searches and saved memories are visible to the
140+
whole team.
141+
142+
## Operating notes
143+
144+
- **Mining** still happens via the CLI (`mempalace mine …`) on the server host
145+
against the same backend, so the central palace stays populated.
146+
- **One writer-lease per process**: a single `mempalace-mcp --transport http`
147+
process safely handles concurrent reads and writes. Don't point two server
148+
processes at the same backend collection.
149+
- **Health checks**: `GET /healthz` returns `200 ok` without a token, so it
150+
works as a load-balancer/Kubernetes liveness probe.
151+
- **Backups** are now your storage backend's responsibility (Qdrant snapshots
152+
/ Postgres backups) rather than a single laptop's palace directory.
153+
154+
## See also
155+
156+
- [MCP Integration](/guide/mcp-integration) — the tools clients get once connected
157+
- [Configuration](/guide/configuration) — config file, identity, environment variables
158+
- [Local Models](/guide/local-models) — keeping embedding and any LLM assist local

0 commit comments

Comments
 (0)