# MemPalace — local fork Local-first AI memory. Verbatim storage, pluggable backend, 96.6% R@5 raw on LongMemEval — zero API calls. 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. The upstream project lives at ; refer there for benchmark methodology, contribution guidelines, project history, and the public docs site at . --- ## What it is 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 ``` If you prefer pip, `pip install mempalace` still works. ## Quickstart ```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) # Search mempalace search "why did we switch to GraphQL" # Load context for a new session mempalace wake-up ``` For Claude Code, Gemini CLI, MCP-compatible tools, and local models, see [mempalaceofficial.com/guide/getting-started](https://mempalaceofficial.com/guide/getting-started.html). 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. --- ## Server mode (Unraid / shared across machines) 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. The `deploy/unraid/` directory ships a complete two-container stack: * `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`. 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. 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 ` runs inside the container (`docker exec mempalace mempalace sweep ...`) — stores one verbatim drawer per user/assistant message, idempotent and resume-safe. --- ## 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 No API key is required for any path. ## 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) ## License MIT — see [LICENSE](LICENSE).