jason/mempalace
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs and usage

Browse Source
This commit is contained in:
jason
2026-05-09 10:59:58 -05:00
parent 40e5e5e3cc
commit 9f18e556d5
2 changed files with 331 additions and 95 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+124 -95
View File
@@ -1,136 +1,165 @@
# MemPalace — local fork
# MemPalace — server-mode fork
Local-first AI memory. Verbatim storage, pluggable backend, 96.6% R@5 raw on LongMemEval — zero API calls.
Local-first AI memory, deployed as a shared service across machines.
This is a personal fork configured for **server-mode deployment** — MemPalace runs as a Docker container (typically on Unraid) and multiple AI tools (Claude Code, Codex, Antigravity) connect to a single shared palace from any machine on the network.
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 lives at <https://github.com/MemPalace/mempalace>; refer there for benchmark methodology, contribution guidelines, project history, and the public docs site at <https://mempalaceofficial.com>.
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 it is
## What's in this fork
MemPalace stores your conversation history as verbatim text and retrieves
it with semantic search. It does not summarize, extract, or paraphrase.
The index is structured — people and projects become *wings*, topics
become *rooms*, and original content lives in *drawers* — so searches
can be scoped rather than run against a flat corpus.
The retrieval layer is pluggable. The current default is ChromaDB; the
interface is defined in [`mempalace/backends/base.py`](mempalace/backends/base.py)
and alternative backends can be dropped in without touching the rest of
the system.
Nothing leaves your machine unless you opt in.
Architecture, concepts, and mining flows:
[mempalaceofficial.com/concepts/the-palace](https://mempalaceofficial.com/concepts/the-palace.html).
---
## Install
We recommend [`uv`](https://docs.astral.sh/uv/) — `uv tool install` puts
the `mempalace` CLI in an isolated environment on your PATH:
```bash
uv tool install mempalace
mempalace init ~/projects/myapp
```
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 │
└────────┘ └────────┘ └──────────┘
```
If you prefer pip, `pip install mempalace` still works.
* **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
# Mine content into the palace
mempalace mine ~/projects/myapp # project files
mempalace mine ~/.claude/projects/ --mode convos # Claude Code sessions (scope with --wing per project)
# On Unraid:
cd /mnt/user/system/build && git clone <this-repo> mempalace && cd mempalace/deploy/unraid
# Search
mempalace search "why did we switch to GraphQL"
TOKEN=$(openssl rand -hex 32)
echo "MEMPAL_TOKEN=$TOKEN" > .env
chmod 600 .env
# Load context for a new session
mempalace wake-up
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
```
For Claude Code, Gemini CLI, MCP-compatible tools, and local models, see
[mempalaceofficial.com/guide/getting-started](https://mempalaceofficial.com/guide/getting-started.html).
Verify: `curl -k https://<unraid-ip>:8443/healthz` returns `{"status":"ok",...}`.
Benchmark methodology and per-question result files live in the upstream repository — this fork has had the `benchmarks/` directory removed since it isn't needed for deployment.
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.
---
## Server mode (Unraid / shared across machines)
## Repository layout
Most users run MemPalace locally on a single machine. If you work
across multiple machines and want one shared memory, you can deploy it
as a Docker container — typically on a home NAS like Unraid — and
point Claude Code, Codex, Antigravity, or any MCP client on each
machine at the same palace.
```
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
The `deploy/unraid/` directory ships a complete two-container stack:
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
* `mempalace` runs the existing MCP-over-SSE endpoint plus a small
HTTP transcript-ingest endpoint, both in a single process so there's
exactly one ChromaDB writer.
* `caddy` sidecar terminates TLS, enforces a bearer-token check on
every request, and reverse-proxies `/sse` and `/ingest`.
hooks/ # Hook scripts for AI clients
├── mempal_save_hook_remote.sh
├── mempal_precompact_hook_remote.sh
└── README.md
Auto-save hooks have remote-aware variants
(`hooks/mempal_save_hook_remote.sh`,
`hooks/mempal_precompact_hook_remote.sh`) that POST transcripts to the
server instead of running `mempalace mine` locally.
Dockerfile # Builds the server image
.dockerignore
```
Full install, client config, hook setup, and troubleshooting:
[`deploy/unraid/README.md`](deploy/unraid/README.md).
---
## Knowledge graph
MemPalace includes a temporal entity-relationship graph with validity
windows — add, query, invalidate, timeline — backed by local SQLite.
Usage and tool reference:
[mempalaceofficial.com/concepts/knowledge-graph](https://mempalaceofficial.com/concepts/knowledge-graph.html).
## MCP server
29 MCP tools cover palace reads/writes, knowledge-graph operations,
cross-wing navigation, drawer management, and agent diaries. Installation
and the full tool list:
[mempalaceofficial.com/reference/mcp-tools](https://mempalaceofficial.com/reference/mcp-tools.html).
## Agents
Each specialist agent gets its own wing and diary in the palace.
Discoverable at runtime via `mempalace_list_agents` — no bloat in your
system prompt:
[mempalaceofficial.com/concepts/agents](https://mempalaceofficial.com/concepts/agents.html).
## Auto-save hooks
Two hooks save periodically and before context compression. In this fork the **remote** variants ship — they POST the active transcript to the server's `/ingest/transcript` endpoint with bearer auth instead of running `mempalace mine` locally. Setup, env-var contract, and troubleshooting: [`hooks/README.md`](hooks/README.md).
For per-message recall on top of the file-level chunks the hooks produce, `mempalace sweep <transcript-dir>` runs inside the container (`docker exec mempalace mempalace sweep ...`) — stores one verbatim drawer per user/assistant message, idempotent and resume-safe.
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
- Python 3.9+ (server image uses 3.13)
- A vector-store backend (ChromaDB by default)
- ~300 MB disk for the default embedding model
- Docker + Compose Manager plugin on Unraid for the server-mode path
* **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 for any path.
No API key is required at any stage. The default embedding model (all-MiniLM-L6-v2 ONNX) runs on CPU on the server.
---
## Docs
- Server-mode deployment → [`deploy/unraid/README.md`](deploy/unraid/README.md)
- Hook setup (remote variants) → [`hooks/README.md`](hooks/README.md)
- Release notes → [`CHANGELOG.md`](CHANGELOG.md)
- Project conventions → [`CLAUDE.md`](CLAUDE.md)
- Upstream CLI / Python API reference → [mempalaceofficial.com](https://mempalaceofficial.com)
* **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).
MIT — see [LICENSE](LICENSE). Upstream copyright belongs to the MemPalace authors; modifications in this fork are also MIT.