Uniwersalna konfiguracja MemPalace dla projektów

Ten dokument stanowi szablon i instrukcję, jak skonfigurować MemPalace jako długoterminową pamięć (serwer MCP) dla asystentów AI (Gemini CLI, Claude Code) w nowym projekcie/workspace.

1. Globalna Instalacja i Ścieżki

Instalacja: Upewnij się, że MemPalace jest zainstalowany globalnie w systemie:
```
pip install mempalace
```
Główny katalog pałaców (PALACE_BASE): Zaleca się trzymanie wszystkich "pałaców" w jednym, centralnym miejscu.
- Przykład Linux: /home/<user>/AI/MemPalaces/
Skrypt weryfikacyjny (Dla Claude): Główny skrypt weryfikujący połączenie na starcie sesji powinien znajdować się w centralnym miejscu, np. w podkatalogu scripts głównego katalogu pałaców. Dla wygody, zaleca się stworzenie dowiązania symbolicznego (symlinka) dostępnego globalnie:
```
mkdir -p ~/bin
ln -sf /home/<user>/AI/MemPalaces/scripts/verify-palace.sh ~/bin/verify-mempalace
chmod +x ~/bin/verify-mempalace
```

2. Inicjalizacja wiedzy dla nowego projektu (Mining)

Aby AI "poznało" projekt, należy zindeksować jego pliki. Najlepiej robić to z podziałem na logiczne sekcje (tzw. wingi).

Komenda ogólna:

mempalace --palace "<SCIEZKA_DO_PALACU_PROJEKTU>" mine --wing "<NAZWA_SEKCJI>" "<KATALOG_DO_ZINDEKSOWANIA>"

Przykład: Budowa wiedzy dla modułu malloc_quantum_connector w pałacu EJSAero:

mempalace --palace "/home/kuba/AI/MemPalaces/EJSAero" mine --wing "malloc_quantum_connector" "ejs_addons/malloc_quantum_connector"

3. Konfiguracja projektu (.mcp.json)

Kluczowym elementem powiązania danego projektu (workspace'a) z jego pałacem jest plik .mcp.json w głównym katalogu projektu. Ten plik mówi asystentom AI, z jakiego serwera i z jakim pałacem mają się łączyć.

Utwórz plik .mcp.json w głównym katalogu projektu:

{
  "mcpServers": {
    "mempalace": {
      "command": "python3",
      "args": [
        "-m", "mempalace.mcp_server",
        "--palace", "<PELNA_SCIEZKA_DO_PALACU_TEGO_PROJEKTU>"
      ]
    }
  }
}

(Zastąp <PELNA_SCIEZKA_DO_PALACU_TEGO_PROJEKTU> odpowiednią ścieżką, np. /home/kuba/AI/MemPalaces/MojNowyProjekt)

4. Konfiguracja Gemini CLI

Gemini CLI odczyta plik .mcp.json i połączy się z serwerem. Wymagana jest jednak jednorazowa konfiguracja globalna.

Rejestracja serwera (globalna): Wystarczy wykonać raz na danej maszynie.

gemini mcp add --scope user mempalace python3 -m mempalace.mcp_server

Auto-zapisywanie sesji (PreCompress Hook): Aby włączyć automatyczne zapisywanie, należy zedytować plik ~/.gemini/settings.json, dodając odpowiedni skrypt (jeśli posiadasz lokalną kopię repozytorium MemPalace ze skryptami hooków):

"hooks": {
  "PreCompress": [
    {
      "matcher": "*",
      "hooks": [
        {
          "type": "command",
          "command": "<PELNA_SCIEZKA_DO_REPOZYTORIUM_MEMPALACE>/hooks/mempal_precompact_hook.sh"
        }
      ]
    }
  ]
}

5. Konfiguracja Claude Code

Claude Code również wykorzystuje plik .mcp.json, ale wymaga dodatkowej konfiguracji w samym projekcie (katalog .claude), aby nadać uprawnienia i włączyć weryfikację.

Utwórz plik .claude/settings.local.json w głównym katalogu projektu z poniższą zawartością (zastąp ścieżkę do skryptu weryfikacyjnego, jeśli jest inna):

{
  "permissions": {
    "allow": [
      "mcp__mempalace__mempalace_status",
      "mcp__mempalace__mempalace_search",
      "mcp__mempalace__mempalace_list_wings",
      "mcp__mempalace__mempalace_list_rooms",
      "mcp__mempalace__mempalace_list_drawers",
      "mcp__mempalace__mempalace_get_drawer",
      "mcp__mempalace__mempalace_add_drawer",
      "mcp__mempalace__mempalace_update_drawer",
      "mcp__mempalace__mempalace_delete_drawer",
      "mcp__mempalace__mempalace_check_duplicate",
      "mcp__mempalace__mempalace_traverse",
      "mcp__mempalace__mempalace_kg_add",
      "mcp__mempalace__mempalace_kg_query",
      "mcp__mempalace__mempalace_kg_stats",
      "mcp__mempalace__mempalace_kg_timeline",
      "mcp__mempalace__mempalace_kg_invalidate",
      "mcp__mempalace__mempalace_diary_read",
      "mcp__mempalace__mempalace_diary_write",
      "mcp__mempalace__mempalace_find_tunnels",
      "mcp__mempalace__mempalace_follow_tunnels",
      "mcp__mempalace__mempalace_create_tunnel",
      "mcp__mempalace__mempalace_delete_tunnel",
      "mcp__mempalace__mempalace_list_tunnels",
      "mcp__mempalace__mempalace_reconnect",
      "mcp__mempalace__mempalace_graph_stats",
      "mcp__mempalace__mempalace_memories_filed_away",
      "mcp__mempalace__mempalace_get_aaak_spec",
      "mcp__mempalace__mempalace_get_taxonomy",
      "mcp__mempalace__mempalace_hook_settings"
    ]
  },
  "enableAllProjectMcpServers": true,
  "enabledMcpjsonServers": ["mempalace"],
  "hooks": {
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "/home/kuba/bin/verify-mempalace"
          }
        ]
      }
    ]
  }
}

6. Instrukcje dla Asystentów (Pliki kontekstowe)

Aby mieć pewność, że AI będzie aktywnie korzystać z MemPalace w danym projekcie, należy dodać specjalne instrukcje do głównych plików kontekstowych projektu (np. CLAUDE.md, GEMINI_CONTEXT.md lub ogólnego context.md).

Skopiuj poniższy blok i wklej go do pliku kontekstowego w głównym katalogu Twojego projektu:

# MemPalace

Ten workspace korzysta z dedykowanego MemPalace: `<NAZWA_PALACU>`.

## Na starcie sesji (szczególnie ważne dla Claude)

1.  Sprawdź komunikat z hooka SessionStart — jeśli zawiera `⚠`, napraw problem zanim zaczniesz pracę.
2.  Wywołaj `mempalace_status` — `palace_path` MUSI wskazywać na `.../AI/MemPalaces/<NAZWA_PALACU>`.
3.  Jeśli palace jest nieprawidłowy — uruchom diagnostykę z instrukcji: `INSTRUKCJA_nowy_mempalace.md`.

## Zasady korzystania i zapisu

-   **Czytanie:** Zawsze używaj `mempalace_search`, aby szukać wcześniejszych ustaleń, decyzji architektonicznych lub rozwiązań podobnych problemów, zanim zaczniesz proponować nowe.
-   **Zapisywanie:** Drawery w MemPalace powinny zawierać treść dokładną (verbatim), nigdy krótkie streszczenia.
-   **Co zapisywać:** Ustalenia, ważne decyzje projektowe/techniczne, dane rejestrowe, strategię, kluczowe uwagi klienta (verbatim).
-   **Czego NIE zapisywać:** Treści samych plików (są dostępne w workspace i były zminowane), rzeczy trywialnych, tymczasowego stanu prac.
-   Jeśli zauważysz ważną decyzję techniczną podczas sesji, **zaproponuj jej zapisanie do MemPalace** (np. pytając: "Czy zapisać tę decyzję do palace?").

(Pamiętaj o podmienieniu <NAZWA_PALACU> na faktyczną nazwę, np. EJSAero)