5.4 KiB
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 https://github.com/MemPalace/mempalace; refer there for benchmark methodology, contribution guidelines, project history, and the public docs site at https://mempalaceofficial.com.
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
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.
Install
We recommend uv — uv tool install puts
the mempalace CLI in an isolated environment on your PATH:
uv tool install mempalace
mempalace init ~/projects/myapp
If you prefer pip, pip install mempalace still works.
Quickstart
# 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.
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:
mempalaceruns 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.caddysidecar terminates TLS, enforces a bearer-token check on every request, and reverse-proxies/sseand/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.
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.
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.
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.
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.
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.
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 - Hook setup (remote variants) →
hooks/README.md - Release notes →
CHANGELOG.md - Project conventions →
CLAUDE.md - Upstream CLI / Python API reference → mempalaceofficial.com
License
MIT — see LICENSE.