Konfiguracja MemPalace

Ten dokument opisuje, jak skonfigurować MemPalace jako długoterminową pamięć (serwer MCP) dla asystentów AI — Gemini CLI i Claude Code — w modelu jednego wspólnego pałacu dla wszystkich projektów.

Korzystanie z tego samego pałacu z Windows przy dual boocie opisuje MemPalace na Windows.

Zmiana modelu (2026-09-17). Wcześniej ta instrukcja zalecała osobny pałac dla każdego projektu (<katalog_AI>/MemPalaces/<projekt>) i osobny plik .mcp.json. Ten układ został zastąpiony jednym wspólnym pałacem skonfigurowanym globalnie. Powody: wiedza z jednego projektu była niewidoczna z drugiego, a konfiguracja per projekt rozjeżdżała się cicho z globalną. Jeśli w jakimś dokumencie widzisz jeszcze PALACE_BASE, katalog MemPalaces/ albo instrukcję tworzenia .mcp.json dla MemPalace — dokument jest nieaktualny.

Znaczniki użyte w dokumencie

Znacznik	Co to jest	Przykład postaci
`<użytkownik>`	Konto na Linuksie	wynik `whoami`
`<katalog_AI>`	Katalog na wszystko, co dotyczy asystentów AI	`/home/<użytkownik>/AI`
`<pałac>`	Katalog jedynego pałacu	`<katalog_AI>/MemPalace`
`<projekt>`	Nazwa projektu, z którego indeksujesz wiedzę	`MojaGra`

1. Instalacja

MemPalace instaluje się systemowo dla użytkownika, nie w wirtualnym środowisku. Dzięki temu działa niezależnie od venvów poszczególnych projektów:

pip install --user mempalace

Sprawdzenie: mempalace --version oraz python3 -c "import mempalace; print(mempalace.__file__)".

2. Gdzie co leży

Ścieżka	Co to jest
`<pałac>`	Jedyny pałac. Wszystkie projekty dzielą go, rozdzielone wingami.
`<katalog_AI>/Archives`	Archiwa zamkniętych projektów. `Archives/Wings/` to zarchiwizowane wingi.
`<katalog_AI>/scripts`	Skrypty pomocnicze, m.in. skrypt weryfikacyjny (punkt 4).

Domyślny pałac dla CLI ustawia ~/.mempalace/config.json (klucz palace_path). Ten sam plik trzyma embedding_model. Ścieżka do tego pliku jest w MemPalace zaszyta na sztywno, a flaga --palace jej nie zmienia.

3. Konfiguracja serwera MCP — globalna, raz na maszynę

Claude Code — w ~/.claude.json, w sekcji mcpServers (nie w projects):

"mempalace": {
  "type": "stdio",
  "command": "python3",
  "args": ["-m", "mempalace.mcp_server", "--palace", "<pałac>"],
  "env": {}
}

Ten sam wpis da się dodać poleceniem claude mcp add --scope user mempalace -- python3 -m mempalace.mcp_server --palace <pałac>.

Gemini CLI — w ~/.gemini/settings.json, w sekcji mcpServers:

"mempalace": {
  "command": "python3",
  "args": ["-m", "mempalace.mcp_server", "--palace", "<pałac>"]
}

Wpis serwera MemPalace w katalogu projektu (.mcp.json) nie jest potrzebny i nie należy go tworzyć. Lokalna konfiguracja projektu po cichu nadpisuje globalną — to najczęstszy powód, dla którego asystent pisze do niewłaściwego pałacu.

4. Hook weryfikacyjny (SessionStart)

Krótki skrypt uruchamiany na starcie sesji (np. <katalog_AI>/scripts/verify-palace.sh, z dowiązaniem ~/bin/verify-mempalace) sprawdza trzy rzeczy:

czy pałac istnieje (<pałac>/chroma.sqlite3),
czy globalny serwer w ~/.claude.json wskazuje właśnie na niego,
czy żaden projekt nie nadpisuje tego lokalnie (projects.*.mcpServers.mempalace).

Wypisuje też liczbę wpisów i model embeddingów z <pałac>/mempalace_embedder.json. Bazę otwiera tylko do odczytu (sqlite3 z mode=ro), żeby nie zmieniać plików pałacu.

Rejestracja globalnie w ~/.claude/settings.json (albo tylko dla jednego projektu w jego .claude/settings.local.json):

"hooks": {
  "SessionStart": [
    { "matcher": "", "hooks": [ { "type": "command", "command": "/home/<użytkownik>/bin/verify-mempalace" } ] }
  ]
}

Rejestracja w settings.local.json działa tylko w sesjach otwartych w tym projekcie.

5. Indeksowanie projektu (mining)

mempalace mine --wing "<projekt>" "<katalog_do_zindeksowania>"

Wing nazywaj nazwą projektu, nigdy nazwą podkatalogu. Wing to jedyny wymiar, który oddziela projekty od siebie. Wing nazwany autoload, controllers, src czy tests zderzy się z następnym projektem o tej samej strukturze katalogów i obu zbiorów nie da się już rozdzielić — metadana mówiąca, z którego projektu pochodzi szuflada, po prostu nie istnieje. Podkatalog trafia do room albo zostaje w source_file.

Przykład:

mempalace mine --wing "MojaGra" --room "autoload" "scripts/autoload"

Nazwa wingu jest brana dosłownie, z wielkością liter: MojaGra i mojagra to dwa różne wingi. Jeśli projekt ma mempalace.yaml, wing pochodzi z tego pliku, a mempalace init potrafi go nadpisać wersją małymi literami.

6. Model embeddingów

Zalecany jest embeddinggemma (onnx-community/embeddinggemma-300m-ONNX, 384 wymiary przez obcięcie Matryoshka, ponad 100 języków). Domyślny wcześniej all-MiniLM-L6-v2 jest modelem wyłącznie angielskim i zwija polskie zapytania do jednego rejonu przestrzeni wektorowej. W pomiarze dwanaście niepowiązanych pytań po polsku miało między sobą średnie cosine 0,521, a pytanie po polsku wobec własnego tłumaczenia na angielski tylko 0,174.

Model musi się zgadzać z tym, którym zapisano wektory. Tożsamość trzyma plik mempalace_embedder.json w katalogu pałaca, osobno dla każdej kolekcji. Odczyt niewłaściwym modelem daje dla szuflad EmbedderIdentityMismatchError, a dla closetów — po cichu cosine_sim=0.0 i kod wyjścia 0. Literówka w nazwie modelu też nie jest błędem: nieznana wartość oznacza cichy powrót do MiniLM.

7. Backup

Kopiuj cały katalog pałaca (cp -a), przy zatrzymanym procesie mempalace. Skopiowanie samego chroma.sqlite3 działa tylko do pierwszego zrzutu HNSW, po którym kopia przestaje się otwierać (InternalError: Error finding id). Katalog bez chroma.sqlite3 nie zawiera w ogóle kolekcji. Uwaga: count() potrafi zwrócić poprawną liczbę wpisów dla kopii, z której nie da się odczytać ani jednego wektora — zgodna liczba nie jest dowodem, że backup jest dobry.

Kopii katalogowej nie weryfikuj przez md5. ChromaDB zmienia pliki przy każdym otwarciu bazy, nawet przy samym czytaniu.

8. Pułapka: `mempalace sync`

sync --apply kasuje szuflady, których pliki źródłowe zniknęły z dysku. Jeśli wing został zindeksowany z katalogu projektu, który potem przeniesiesz albo zarchiwizujesz, sync --apply skasuje cały ten wing — cicho i zgodnie ze swoim przeznaczeniem. Dotyczy to także szuflad zindeksowanych z innego systemu (np. z Windows przy dual boocie), których ścieżki nie istnieją na Linuksie. Zawsze najpierw --dry-run.

9. Instrukcje dla asystentów

Zasady pracy z pałacem trzymaj w plikach kontekstowych czytanych na starcie każdej sesji: ~/.claude/CLAUDE.md (Claude Code) i ~/.gemini/GEMINI.md (Gemini CLI). Nie powielaj ich w plikach projektowych — projekt dopisuje tylko to, co jest dla niego specyficzne.

Najważniejsza z nich, bo najłatwiej ją przeoczyć: szukaj najpierw bez filtra wing. Parametr wing przyjmuje pojedynczą nazwę, bez alternatywy, więc zapytanie zawężone do projektu jest ślepe na wiedzę ogólną i na pozostałe projekty. Filtr służy do zawężenia zalanego wyniku, a nie jako tryb domyślny.

Pozostałe zasady warte wpisania:

listę wingów pobieraj z mempalace_status, nie wpisuj jej na sztywno,
szuflady zapisuj dosłownie (verbatim), nigdy jako streszczenie,
zapisuj ustalenia, decyzje projektowe i techniczne, dane rejestrowe, strategię i kluczowe uwagi klienta; nie zapisuj treści plików, które i tak są w repozytorium.