MemPalace-Deployment und Praxis: Ein KI-Erinnerungssystem, das nie etwas vergisst

Mittlere Schwierigkeit · ca. 20 Minuten · Du erhältst die komplette Deployment-Pipeline für MemPalace, verstehst die Palace-Schichten und lernst, mit MCP ein beliebiges KI-System an das Speichersystem anzuschließen.

---

Zielgruppe

1–3 Jahre Berufserfahrung als Entwickler:in, bereits mit KI-Programmier-Tools wie Claude Code / Cursor / Copilot gearbeitet. Ziel: Damit KI in langfristigen Projekten den Kontext behält und nicht jedes Mal bei Null beginnt.

---

Kernerfordernisse und Umgebung

• Python: 3.9+
• Kernabhängigkeiten: chromadb>=0.5.0,<0.7、pyyaml>=6.0
• Installation: pip install mempalace oder uv pip install mempalace
• Betriebssystem: macOS / Linux / Windows (WSL ebenfalls)
• Speicher: ChromaDB (Vektor-DB) + SQLite (Wissensgraph), alles lokal, ohne Netzwerk

---

Vollständige Projektstruktur

mempalace/
├── mempalace/                 # Kern-Python-Paket
│   ├── cli.py                 # CLI-Entrypoint, routet zu mine/search/init usw.
│   ├── mcp_server.py          # MCP-Server, stellt 19 Tools bereit
│   ├── knowledge_graph.py     # Zeitlicher Wissensgraph (SQLite)
│   ├── palace_graph.py        # Palace-Navigationsgraph (BFS-Traversal, Tunnel-Findung)
│   ├── convo_miner.py         # Dialog-Mining, schneidet nach Q+A
│   ├── miner.py               # Projektdateien minen, schneidet nach Absätzen
│   ├── searcher.py            # Semantische Suche (ChromaDB)
│   ├── normalize.py           # 5 Dialogformate vereinheitlichen
│   ├── dialect.py             # AAAK-Kompressionsdialekt
│   ├── layers.py              # Vier-Schichten-Speicher-Stack (L0–L3)
│   ├── onboarding.py          # Initialisierung per Onboarding
│   ├── entity_detector.py     # Automatisches Erkennen von Personennamen/Projektbezeichnungen
│   └── split_mega_files.py    # Aufteilen und Zusammenführen großer Sitzungsdateien
├── hooks/                     # Claude-Code-Auto-Save-Hooks
│   ├── mempal_save_hook.sh     # Speichert alle 15 Nachrichten automatisch
│   └── mempal_precompact_hook.sh  # Notfall-Save vor Kontextkompression
├── benchmarks/               # Reproduzierbare Benchmarks (LongMemEval / LoCoMo)
│   ├── longmemeval_bench.py
│   ├── locomo_bench.py
│   └── BENCHMARKS.md
└── examples/
    ├── basic_mining.py
    └── mcp_setup.md

---

Schritt-für-Schritt

Step 1: Installation

pip install mempalace

Die niedrigste unterstützte Python-Version ist 3.9. Nach der Installation prüfen, ob es funktioniert:

mempalace --version

---

Step 2: Erinnerungspalast initialisieren

mempalace init ~/projects/myapp

Der init-Befehl startet den geführten Prozess und fragt nacheinander:

• die Personen, mit denen du häufig zusammenarbeitest (in die Wing-Konfiguration aufnehmen)
• das Projekt, an dem du arbeitest (pro Projekt ein wing)
• deine KI-Identität (wird in die L0-Schicht geschrieben)

Nach Abschluss des Onboardings werden zwei Konfigurationsdateien erzeugt:

• ~/.mempalace/config.json — globale Konfiguration (u. a. palace-Pfad)
• ~/.mempalace/wing_config.json — Mapping zwischen wing und Keywords

Die erzeugte wing_config.json sieht ungefähr so aus:

{
  "default_wing": "wing_general",
  "wings": {
    "wing_kai": { "type": "person", "keywords": ["kai", "kai's"] },
    "wing_driftwood": { "type": "project", "keywords": ["driftwood", "analytics", "saas"] }
  }
}

Wenn die KI startet, lädt sie nur L0 + L1 (ca. 170 Tokens) und weiß so, wie deine Welt aussieht.

---

Step 3: Daten auswerten (Mining)

MemPalace unterstützt zwei Mining-Modi – je nachdem, welche Datenquelle du verwendest.

Modus A: Projektdateien minen (Code, Dokumente, Notizen)

mempalace mine ~/projects/myapp

Der miner scannt das Verzeichnis rekursiv, schneidet nach Absätzen und speichert in ChromaDB; die Drawer speichern den ursprünglichen Inhalt.

Modus B: Dialog-Exports minen (Claude/ChatGPT/Slack)

# Grundverwendung
mempalace mine ~/chats/ --mode convos

# Konkretes wing angeben, damit später nach Projekt gefiltert werden kann
mempalace mine ~/chats/ --mode convos --wing myapp

# Automatische Klassifizierung aktivieren (extrahiert Entscheidungen, Präferenzen,
# Meilensteine, Problemfragen sowie emotionale Kontextinformationen)
mempalace mine ~/chats/ --mode convos --extract general

Der convo_miner schneidet die Dialoge nach Q+A, erkennt automatisch die room-Zugehörigkeit (über 70+ Modi-Matching in room_detector_local.py, ohne API).

---

Step 4: Semantische Suche zur Verifikation

Wenn das Mining abgeschlossen ist, probiere eine Suche:

mempalace search "why did we switch to GraphQL"

Mit wing-Filter, damit nur in einem bestimmten Projekt gesucht wird:

mempalace search "auth decision" --wing driftwood

Noch genauer: Zusätzlich room filtern:

mempalace search "auth decision" --wing driftwood --room auth-migration

Zurückgegeben wird der Originaltext aus dem Drawer (verbatim) – ohne Zusammenfassung und ohne Informationsverlust. ChromaDB macht die Vektor-Retrievals, Closet liefert die strukturierten Zusammenfassungen.

---

Step 5: MCP-Service anbinden

MCP (Model Context Protocol) macht MemPalace als Tool für jede beliebige KI verfügbar. Einmal konfigurieren, für immer aktiv.

Einbindung in Claude Code:

claude mcp add mempalace -- python -m mempalace.mcp_server

Nach der Konfiguration erhält Claude Code automatisch 19 Tools; die KI ruft mempalace_search bei Bedarf selbst auf – du musst nicht manuell suchen.

Einbindung in Gemini CLI:

# siehe examples/gemini_cli_setup.md
claude mcp add mempalace -- python -m mempalace.mcp_server

Die Gemini CLI bietet für MCP eine umfassendere Unterstützung; außerdem können save hooks automatisch konfiguriert werden.

Liste der MCP-Tools (19):

Die KI lernt automatisch AAAK-Syntax und den Memory-Mechanismus aus der Antwort von mempalace_status – ohne dass du manuell Prompts konfigurieren musst.

---

Step 6: Claude-Code-Auto-Save-Hooks konfigurieren

Mit den Hooks von Claude Code kann MemPalace bei jedem Dialog automatisch Erinnerungen speichern.

Passe ~/.claude/settings.json an (globale Konfiguration von Claude Code) und ergänze:

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/mempalace/hooks/mempal_save_hook.sh"
          }
        ]
      }
    ],
    "PreCompact": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/mempalace/hooks/mempal_precompact_hook.sh"
          }
        ]
      }
    ]
  }
}

Der Unterschied zwischen den beiden Hooks:

• Stop: Triggert alle 15 Nachrichten. Strukturierte Speicherung – Thema, Entscheidungen, Zitate sowie Code-Änderungen werden vollständig erfasst. Zusätzlich wird die L1-Schicht neu aufgebaut (wichtige Faktenschicht).
• PreCompact: Triggert vor der Kontextkompression. Speichert als Notfall noch nicht gesicherte Erinnerungen, um zu vermeiden, dass beim Komprimieren wichtiger Kontext verloren geht.

---

Step 7: Palace-Struktur verstehen

MemPalace basiert auf der Kernabstraktion „Erinnerungspalast“: inspiriert von den Gedächtnistechniken antiker griechischer Redner, bei denen man mit räumlicher Struktur statt flacher Suchindizes arbeitet.

  WING: kai (person)

    ┌──────────┐  ──hall──  ┌──────────┐
    │ auth-mig │            │ security  │
    └────┬─────┘            └──────────┘
         │
         ▼
    ┌──────────┐      ┌──────────┐
    │  Closet  │ ───▶ │  Drawer  │  ← Originaltext liegt hier
    └──────────┘      └──────────┘

  TUNNEL (Verbindung über wings hinweg):
  kai/auth-mig  ←→  driftwood/auth-mig  ←→  priya/auth-mig

Wings: Eine Person oder ein Projekt – die Hauptkategorie der Erinnerungen. Unter jedem wing können mehrere rooms existieren.

Rooms: Konkrete Themen innerhalb eines wings, z. B. auth-migration, ci-pipeline, pricing. Wenn ein room mit demselben Namen in verschiedenen wings vorkommt, wird automatisch ein Tunnel erzeugt.

Halls: Gänge für Erinnerungstypen. Jeder wing hat dieselbe Menge an halls:

• hall_facts — festgeschlossene Entscheidungen
• hall_events — Sitzungen, Meilensteine, Debugging-Prozesse
• hall_discoveries — Durchbrüche und neue Erkenntnisse
• hall_preferences — Gewohnheiten, Präferenzen, Meinungen
• hall_advice — Empfehlungen und Lösungen

Closets: Die Zusammenfassungsebene, die auf die Position des Originalinhalts (Drawer) zeigt. Der Originaltext geht nicht verloren – es kommt nur eine zusätzliche, navigierbare Strukturschicht hinzu.

Drawers: Ort der Aufbewahrung für den Originaltext. Der „raw verbatim“-Modus von MemPalace liest genau von hier den Originaltext aus und führt dann die Vektor-Suche aus – damit werden 96,6% R@5 erreicht.

---

Step 8: Zeitliche Beziehungen im Knowledge Graph nutzen

ChromaDB speichert Vektoren aus dem Originaltext; der Knowledge Graph (SQLite) speichert strukturierte Fakten-Dreiergruppen. Beide ergänzen sich.

from mempalace.knowledge_graph import KnowledgeGraph

kg = KnowledgeGraph()

# Fakten hinzufügen, inklusive Gültigkeitszeitraum
kg.add_triple("Kai", "works_on", "Orion", valid_from="2025-06-01")
kg.add_triple("Maya", "assigned_to", "auth-migration", valid_from="2026-01-15")
kg.add_triple("Maya", "completed", "auth-migration", valid_from="2026-02-01")

# Abfragen, woran Kai gerade arbeitet
print(kg.query_entity("Kai"))
# → [Kai → works_on → Orion (current)]

# Abfragen, wie es am 2026-01-20 war (damals war Maya auth-migration noch nicht fertig)
print(kg.query_entity("Maya", as_of="2026-01-20"))
# → [Maya → assigned_to → auth-migration]

# Zeitleiste des Projekts Orion ansehen
print(kg.timeline("Orion"))
# → Faktenkette in zeitlicher Reihenfolge

# Maya wechselt das Projekt: alte Fakten werden ungültig
kg.invalidate("Maya", "assigned_to", "auth-migration", ended="2026-02-01")
# Jetzt gibt query_entity("Maya") kein auth-migration mehr zurück

Das Gültigkeitsfenster (valid_from / ended) ist die Kernfähigkeit von MemPalace: Bei der Abfrage des historischen Zustands erfährst du „was damals passiert ist“, nicht „was jetzt passiert“.

---

Step 9: Vier-Schichten-Architektur des Memory-Stacks

MemPalace teilt die Retrieval-Strategie in vier Schichten auf. Je weiter oben, desto leichtergewichtig; je weiter unten, desto präziser:

Wenn die KI startet, lädt sie zuerst L0 + L1 (mempalace wake-up); bereits nach 170 Tokens steht ein vollständiger Hintergrundkontext. L2 wird nur geladen, wenn ein Thema einen bestimmten room triggert; L3 wird nur aktiviert, wenn explizit nach einer vollständigen ChromaDB-Suche gefragt wird.

Das erklärt auch, warum MemPalace so geringe Kosten hat – $10/Jahr Suchkosten gegenüber $507/Jahr für die reine Zusammenfassungs-Variante.

---

Häufige Probleme beheben

Q1: Suchergebnisse sind leer, aber der Inhalt ist sicher vorhanden

In drei Schritten prüfen:

# 1. Prüfen, ob wing- und room-Namen korrekt sind
mempalace list-wings
mempalace list-rooms --wing myapp

# 2. Bereich erweitern, nicht wing/room einschränken und Vollsuche durchführen
mempalace search "Schlüsselwort"   # ohne --wing

# 3. Prüfen, ob wirklich etwas in ChromaDB geschrieben wurde
mempalace status            # Drawer-Gesamtzahl ansehen: ist sie 0?

Wenn mempalace status 0 Drawer anzeigt, ist das Mining vermutlich nicht erfolgreich gewesen – möglicherweise ist das Dialogformat nicht unterstützt (derzeit unterstützt: Claude Code JSONL, Claude.ai JSON, ChatGPT JSON, Slack JSON, plain text).

Q2: ChromaDB-Collection-Namenskonflikt

Der Standard-Collection-Name ist mempalace_drawers. Wenn du mehrfach init machst oder in verschiedenen Verzeichnissen arbeitest, kann es zu Konflikten kommen. In ~/.mempalace/config.json den Pfad explizit setzen:

{
  "palace_path": "/custom/path/to/palace",
  "collection_name": "mempalace_drawers"
}

Dann mit --palace <path> überschreiben:

mempalace search "query" --palace /custom/path/to/palace

Q3: MCP-Verbindung schlägt fehl

Zuerst manuell verifizieren, dass der MCP-Service korrekt startet:

python -m mempalace.mcp_server
# Normalerweise wird nichts ausgegeben; im Vordergrund laufen lassen
# Ctrl+C zum Beenden

Wenn es einen ModuleNotFoundError gibt, prüfe die korrekte Installation:

pip show mempalace

Wenn du ein Virtual Environment nutzt, stelle sicher, dass in der MCP-Konfiguration von Claude Code der korrekte Python-Pfad eingetragen ist:

which python   # holt den richtigen Python-Pfad
claude mcp add mempalace -- /path/to/python -m mempalace.mcp_server

Q4: MCP-Toolaufrufe funktionieren, aber das Ergebnis entspricht nicht den Erwartungen

Wenn die KI mempalace_search aufruft, müssen die wing/room-Parameter exakt übereinstimmen, um die Palace-Struktur maximal auszunutzen. Führe die KI im Prompt an, den korrekten Filter zu verwenden:

When searching for project-specific memories, always pass --wing <project>.
When searching for a specific topic, always pass --room <room-name>.

Q5: Hook-Skripte werden nicht getriggert

# Prüfen, ob die hooks in Claude Code aktiviert sind
claude doctor

Stelle sicher, dass in settings.json die Hook-Pfade absolute Pfade sind. Relative Pfade können scheitern, weil Claude Code in unterschiedlichen Working Directories läuft.

Q6: Zeitliche Knowledge-Graph-Abfragen liefern unerwartete Ergebnisse

Zeitliche Abfragen hängen vom as_of-Parameterformat ab; das Datum muss YYYY-MM-DD sein:

# Falsches Format
kg.query_entity("Kai", as_of="2026/03/01")

# Korrektes Format
kg.query_entity("Kai", as_of="2026-03-01")

Außerdem prüfen, ob du beim Hinzufügen von Fakten mit add_triple valid_from ebenfalls im korrekten Format verwendet hast – sonst greift das zeitliche Fenster nicht.

---

Weiterführende Lektüre / Fortgeschrittene Richtungen

AAAK experimentelle Kompressionsschicht

AAAK ist eine verlustbehaftete Abkürzungs-Dialektvariante: Durch reguläre Ersetzungen werden wiederkehrende Entitäten zu Code komprimiert. In großem Maßstab (wenn dasselbe Projekt in hundertfacher Wiederholung erwähnt wird) kann es Token-Kosten sparen – aktuell ist der „raw verbatim“-Modus (96,6%) jedoch immer noch besser als der AAAK-Modus (84,2%). Geeignet sind Szenarien mit langen Laufzeiten, mehreren Sitzungen und vielen wiederholten Entitäten.

Specialist Agents: Memory-Isolation durch Multi-Agent

Jeder Agent hat ein eigenes wing und ein AAAK-Tagebuch:

~/.mempalace/agents/
  ├── reviewer.json    # Codequalität, Muster, Bugs
  ├── architect.json   # Architekturentscheidungen, Trade-offs
  └── ops.json         # Deployment, Ausfälle, Infrastruktur

Die KI entdeckt Agents zur Laufzeit dynamisch aus dem palace heraus – du musst keine Konfiguration in CLAUDE.md schreiben.

Benchmarks reproduzieren

Im benchmarks/-Verzeichnis liegen vollständige Reproduktionsskripte für LongMemEval und LoCoMo:

python benchmarks/longmemeval_bench.py

Über den gesamten Lauf sind keine API-Keys nötig. Auf einem M2 Ultra läuft das Ganze in unter 5 Minuten durch und testet 500 Aufgaben – damit wird die Reproduzierbarkeit von 96,6% validiert.

Quervergleich mit anderen Systemen

MemPalace ist die einzige Lösung, die ohne jegliche API-Aufrufe die höchste Punktzahl erreicht.