# Portabilitaet: SYSTEM
# Zuletzt validiert: 2026-02-16 (Claude Code Opus)
# Naechste Pruefung: 2026-06-01
# Quellen: Claude Code System-Prompt, ~/.claude/ Verzeichnisanalyse

CLAUDE CODE MEMORY-ARCHITEKTUR
==============================

Stand: 2026-02-16

WAS IST DAS MEMORY-SYSTEM?
---------------------------
Claude Code hat ein persistentes Auto-Memory-System, das Wissen ueber
Sessions hinweg speichert. Jede Claude Code Instanz laedt beim Start
automatisch die MEMORY.md ihres Projekts in den System-Prompt.

WICHTIG: Das Memory ist NICHT global -- es ist projekt-basiert.
Jedes Arbeitsverzeichnis hat seine eigene, isolierte Memory.

VERZEICHNISSTRUKTUR
-------------------
  ~/.claude/
  ├── .mcp.json                              # MCP-Server Config
  ├── projects/                              # Projekt-Memories
  │   ├── C--Users-User/                     # Projekt: Home-Verzeichnis
  │   │   └── memory/
  │   │       ├── MEMORY.md                  # Haupt-Memory (IMMER geladen)
  │   │       ├── mcmc-server.md             # Detail-Datei (bei Bedarf)
  │   │       └── debugging.md              # Themen-Datei (bei Bedarf)
  │   │
  │   ├── C--Users-User-OneDrive-KI-AI-BACH/
  │   │   └── memory/
  │   │       ├── MEMORY.md                  # BACH-spezifisch (190 Zeilen)
  │   │       └── sqlite_gotchas.md          # Ausgelagertes Detail
  │   │
  │   ├── C--Users-User-OneDrive-Forschung/
  │   │   └── memory/
  │   │       └── MEMORY.md                  # Forschungs-spezifisch
  │   │
  │   └── ... (42+ weitere Projektverzeichnisse)
  │
  └── teams/                                 # Team-Konfigurationen
      └── {team-name}/config.json

Der Verzeichnisname wird aus dem Arbeitsverzeichnis abgeleitet:
  %ONEDRIVE_AI_ROOT%  -->  C--Users-User-OneDrive-KI-AI

WIE MEMORY.md FUNKTIONIERT
---------------------------
1. AUTOMATISCH GELADEN: Die MEMORY.md des aktuellen Arbeitsverzeichnisses
   wird bei JEDEM Gespraech in den System-Prompt injiziert
   (als "user's private global instructions for all projects")

2. NICHT KOMPRIMIERT: MEMORY.md wird nie komprimiert, aber:
   -> Nach Zeile 200 wird ABGESCHNITTEN (Truncation, nicht Kompression)
   -> Deshalb MUSS sie kompakt bleiben
   -> Detail-Dateien auslagern und per Verweis referenzieren

3. MANUELLE PFLEGE: Claude schreibt/editiert die Datei selbst
   mit Write/Edit-Tools basierend auf System-Prompt-Regeln

4. DETAIL-DATEIEN (z.B. sqlite_gotchas.md, mcmc-server.md):
   -> Werden NICHT automatisch geladen
   -> Muessen explizit per Read-Tool gelesen werden
   -> Deshalb: Kurzverweis in MEMORY.md, Details in separater Datei

WAS MEMORY SPEICHERN SOLL
--------------------------
  JA (speichern):
    - Stabile Patterns und Konventionen (mehrfach bestaetigt)
    - Architektur-Entscheidungen, wichtige Pfade
    - User-Praeferenzen (Sprache, Workflow, Tools)
    - Loesungen fuer wiederkehrende Probleme
    - Explizite User-Wuensche ("merke dir immer...")

  NEIN (nicht speichern):
    - Session-spezifischer Kontext (aktuelle Task-Details)
    - Unvollstaendige/unverifiziete Informationen
    - Duplikate von CLAUDE.md-Inhalten
    - Spekulative Schlussfolgerungen

SESSION-SPEZIFISCHES WISSEN
----------------------------
Geht beim Session-Ende VERLOREN. Es gibt keinen persistenten
Session-Speicher. Jede neue Session startet nur mit:

  1. MEMORY.md (injiziert in System-Prompt)
  2. CLAUDE.md (Projekt-Instruktionen, falls vorhanden)
  3. Konversations-Kontext (wird bei Context-Limit KOMPRIMIERT)

Konversations-Kompression:
  - Das System komprimiert aeltere Nachrichten automatisch
  - Nur wenn der Context nahe am Limit ist
  - Komprimierung betrifft Gespraechsverlauf, NICHT Memory-Dateien
  - Nach Session-Ende: alles weg (ausser explizit in Memory geschrieben)

MEMORY vs. CLAUDE.md
---------------------
  MEMORY.md                          CLAUDE.md
  ─────────                          ─────────
  Pfad: ~/.claude/projects/*/memory/ Pfad: im Arbeitsverzeichnis
  Von Claude selbst geschrieben      Vom User/Team gepflegt
  Dynamisch (waechst mit Erfahrung)  Statisch (Projekt-Regeln)
  Lessons Learned, Erkenntnisse      Instruktionen, Verbote, Standards
  Projekt-spezifisch                 Vererbbar (Parent -> Child)
  Max 200 Zeilen (Truncation)        Kein hartes Limit

  CLAUDE.md Vererbung:
    C:\Users\User\CLAUDE.md           -> Gilt fuer ALLE Projekte
    C:\Users\User\Projekt\CLAUDE.md   -> Gilt fuer Projekt + Unterordner

DAS SILO-PROBLEM
-----------------
Jedes Projekt-Memory ist isoliert. Lessons Learned aus einem Projekt
sind in einem anderen UNSICHTBAR:

  Projekt A: "OneDrive lockt Dateien"     <- nur hier bekannt
  Projekt B: "PYTHONIOENCODING=utf-8"     <- nur hier bekannt
  Projekt C: "NUL-Dateien vermeiden"      <- nur hier bekannt

Loesungsansaetze:

  1. GLOBALE CLAUDE.md im Home-Verzeichnis
     -> C:\Users\User\CLAUDE.md
     -> Wird von ALLEN Instanzen geladen die in ~ oder darunter arbeiten
     -> Ideal fuer: System-Regeln, User-Praeferenzen, Windows-Hinweise

  2. HOME-MEMORY als Hub
     -> C--Users-User/memory/MEMORY.md als zentraler Index
     -> Verweist auf Detail-Dateien und andere Projekt-Memories
     -> Enthaelt "Master Lessons Learned" (cross-project)

  3. BRIEFING-DATEIEN fuer Instanz-Uebergabe
     -> Dedizierte .md Dateien im Memory-Verzeichnis
     -> Enthalten alles was eine neue Instanz wissen muss
     -> Beispiel: mcmc-server.md (Server-Zugangsdaten + Status)

MEMORY.md ALS KOMMUNIKATIONSKANAL (Entdeckung 2026-02-17)
---------------------------------------------------------
Wenn eine laufende Claude-Instanz MEMORY.md aendert, erhaelt eine andere
laufende Instanz (im selben Projekt-Verzeichnis) automatisch eine
System-Injection mit dem Diff:

  <system-reminder>
  MEMORY.md was modified, either by the user or by a linter.
  Here are the relevant changes...
  </system-reminder>

Das bedeutet:
  - MEMORY.md ist ein Shared Blackboard fuer parallele Instanzen
  - Aenderungen werden SOFORT sichtbar (Push, kein Polling)
  - Instanz A kann Instanz B informieren indem sie MEMORY.md editiert
  - Funktioniert NUR zwischen Instanzen im selben Projekt-Verzeichnis

Potenzielle Nutzung:
  - Multi-Instanz-Koordination (wer arbeitet woran)
  - Status-Updates zwischen parallelen Claude-Sessions
  - BACH Bridge-Daemon als Nachrichtenkanal

INJEKTIONS-MECHANISMEN (vollstaendig, Stand 2026-02-17)
-------------------------------------------------------
Folgende Events loesen System-Injections bei Claude Code aus:

  1. Session-Start      CLAUDE.md + MEMORY.md komplett injiziert
  2. Datei-Aenderung    CLAUDE.md/MEMORY.md → Diff wird injiziert
  3. Umgebungsinfos     Plattform, Shell, OS, Modell, Working Dir
  4. Datum              currentDate wird injiziert
  5. Skills             Verfuegbare Skills als <system-reminder>
  6. Hooks              user-prompt-submit-hook Output
  7. Kontext-Kompression  Bei Limit: aeltere Nachrichten komprimiert
  8. Tool-Ergebnisse    Koennen <system-reminder>-Tags enthalten

BEST PRACTICES
--------------
  1. MEMORY.md unter 200 Zeilen halten (Truncation-Limit!)
  2. Details in separate .md Dateien auslagern
  3. Index-Abschnitt am Ende von MEMORY.md pflegen
  4. Cross-Projekt Lessons in Home-Memory oder CLAUDE.md
  5. Sensible Daten (Keys, Tokens) NICHT in CLAUDE.md
     (wird ggf. in Git committed), besser in MEMORY.md
  6. Bei Multi-Instanz-Szenarien: Briefing-Dateien erstellen

BEISPIEL: OPTIMALE MEMORY-STRUKTUR
-----------------------------------
  ~/.claude/projects/C--Users-User/memory/
  ├── MEMORY.md                # Kompakter Index + Master Lessons (<200 Zeilen)
  ├── mcmc-server.md           # Detailwissen: Server-Zugang + Status
  ├── debugging.md             # Wiederkehrende Debugging-Patterns
  └── patterns.md              # Architektur- und Code-Patterns

  ~/CLAUDE.md                  # Globale Regeln fuer ALLE Instanzen
                               # (Windows-Verhalten, Sprache, Encoding)

WARTUNG
-------
  - Regelmaessig pruefen ob Eintraege noch aktuell sind
  - Veraltete Eintraege entfernen statt markieren
  - Nach groesseren Projekten: Lessons Learned extrahieren
  - Bei neuem Rechner: Memory-Verzeichnis mitkopieren

BEKANNTE EIGENHEITEN
---------------------
  - Projektname-Mapping: Sonderzeichen werden zu "-"
    %ONEDRIVE_AI_ROOT%  ->  C--Users-User-OneDrive-KI-AI
  - Gleiches Arbeitsverzeichnis = gleiche Memory (auch verschiedene Sessions)
  - Memory wird NUR geladen wenn `claude` im passenden Verzeichnis gestartet wird
  - Unterverzeichnisse erben NICHT die Memory des Parent-Verzeichnisses
    (anders als CLAUDE.md, die vererbt!)

BACH-KONTEXT
------------
Fuer BACH ist das Memory-System besonders relevant:
  - BACH hat ~42 verschiedene Projektverzeichnisse
  - Jedes mit eigener Memory (teils reichhaltig: 190 Zeilen)
  - Wissen-Silos zwischen BACH-Dev, Forschung, MCP etc.
  - Home-Memory als Hub-Loesung empfohlen

SIEHE AUCH
----------
  wiki/claude-code.txt    Claude Code CLI Referenz
  wiki/mcp.txt            Model Context Protocol
  wiki/mcp_patterns.txt   MCP Design Patterns
