137 lines
5.4 KiB
Markdown
137 lines
5.4 KiB
Markdown
# 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`](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 <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`](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).
|