Codebase Memory & Graph Intelligence (`codebase-memory`)

Codebase Memory & Graph Intelligence (codebase-memory)

Diese Fähigkeit definiert die ingenieurtechnischen Standards, Betriebsabläufe und Tool-Nutzungsverträge für die Erkundung, Suche und das Verständnis von Code unter Verwendung des codebase-memory MCP-Wissensgraphen.

---

Kerninvariante: Das Index-zuerst-Protokoll

[!CRITICAL] INDEX-ZUERST-INVARIANTE: Die Hintergrund-Neuindizierung (auto_watch) ist dauerhaft deaktiviert (auto_watch = false) in diesem Workspace, um Festplatten-Thrashing, Zstd-Serialisierungs-Overhead und System-Ruckler während der aktiven Dateibearbeitung zu vermeiden.

Folglich MUSS der Agent IMMER die Aktualität des Index überprüfen oder eine bedarfsgesteuerte Neuindizierung (index_repository) auslösen, BEVOR er Suchanfragen gegen den Code-Wissensgraphen ausführt.

Wann immer Sie damit beauftragt werden, ein Symbol zu finden, ein Modul zu verstehen, einen Fehler zu untersuchen oder eine Refaktorierung vorzubereiten, führen Sie das Index-zuerst-Gate aus, bevor Sie Suchaufrufe tätigen.

---

Werkzeug-Hierarchie: Graph zuerst, Grep zweitens

Beim Entdecken, Navigieren oder Überprüfen von Code halten Sie sich strikt an diese Prioritätenhierarchie:

flowchart TD
    Task[Code-Entdeckungs- / Untersuchungsaufgabe] --> Freshness{Index aktuell?}
    Freshness -->|Nein / Unbekannt / Nach Änderungen| Sync[index_repository mode: 'fast' oder 'moderate']
    Freshness -->|Ja| Strategy{Abfragetyp}
    Sync --> Strategy

    Strategy -->|Symbol / Funktion / Schnittstelle| SearchGraph[search_graph BM25 oder semantic_query]
    Strategy -->|Aufrufer / Aufgerufene / Abhängigkeiten| TracePath[trace_path callers / callees]
    Strategy -->|Auswirkungsradius von Änderungen| DetectChanges[detect_changes diff to impact set]
    Strategy -->|Exakter Quellcode| GetSnippet[get_code_snippet präzise Zeilen]
    Strategy -->|Systemschichten & Hub-Module| GetArch[get_architecture hochzentrale Knoten]
    Strategy -->|Wörtliche Zeichenketten / Nicht-Code / Assets| GrepFallback[search_code oder run_command grep]

1. search_graph > Text-Grep: BM25-gerankte strukturelle Suche mit CamelCase-Aufteilung, Label-Boosting (Funktionen +10, Routen +8, Schnittstellen +5) und Vektor-Embeddings.
2. trace_path > manuelles Datei-Hopping: Sofortige Multi-Hop-Auflösung von Aufrufer- und Aufgerufenen-Graphen.
3. get_code_snippet > view_file bei großen Dateien: Ruft die genaue Deklaration und den Rumpf eines Symbols mit Start-/Endzeilen und Aufruferanzahlen ab, ohne den Agentenkontext aufzublähen.
4. detect_changes > manuelle Diff-Inspektion: Bildet Git-Diffs (since: "HEAD~1", base_branch: "main") direkt auf ihren transitiven Auswirkungsradius ab.
5. Grep-Fallback: Verwenden Sie search_code oder run_command (git grep, rg) NUR für:
   • Wörtlichen Text in Markdown (.md), Konfiguration (.json) oder Stylesheets (.css).
   • Zeilenbereiche, die explizit unter parse_partial in index_status markiert sind.
   • Dateien, die per Design über .cbmignore ausgeschlossen sind.

---

Standard-Arbeitsablauf

Schritt 1: Index-Synchronisierungs-Gate (zwingend erforderliche erste Aktion)

Bevor Sie Suchabfragen ausgeben, ermitteln Sie den Projektnamen und stellen Sie sicher, dass der Graph die aktuellen Dateisystemänderungen widerspiegelt.

1. Projektnamen identifizieren: Rufen Sie list_projects auf, wenn der Projektbezeichner unbekannt ist:

   {
     "ServerName": "codebase-memory",
     "ToolName": "list_projects",
     "Arguments": {}
   }
   

   (In diesem Workspace lautet der abgeleitete Projektname "D-Scripts-aminwebsite".)

2. Status überprüfen oder Index aktualisieren: Wenn während der Sitzung Dateien erstellt oder geändert wurden, rufen Sie index_repository auf:

   {
     "ServerName": "codebase-memory",
     "ToolName": "index_repository",
     "Arguments": {
       "repo_path": "d:/Scripts/aminwebsite",
       "mode": "fast"
     }
   }
   

   • Modusauswahl:
     • mode: "fast": Inkrementelles Parsen, gefilterte Dateien, keine semantischen Vektor-Embeddings. Schnell und leichtgewichtig für die aktive Entwicklung.
     • mode: "moderate": Inkrementelles Parsen + Vektor-Ähnlichkeits-Embeddings für die konzeptionelle Verknüpfung in natürlicher Sprache.
   • Abdeckungsinspektion: Überprüfen Sie die Antwort auf:
     • parse_partial: Dateien, bei denen bestimmte Zeilenbereiche Parse-Fehler aufwiesen.
     • skipped: Vollständig übersprungene Dateien (z. B. binär oder zu groß).

---

Schritt 2: Symbol- & Strukturentdeckung (search_graph)

Finden Sie Funktionen, Schnittstellen, Typen, Komponenten und Routendefinitionen.

{
  "ServerName": "codebase-memory",
  "ToolName": "search_graph",
  "Arguments": {
    "project": "D-Scripts-aminwebsite",
    "query": "LocaleSwitcher"
  }
}

• Entdeckung in natürlicher Sprache: Verwenden Sie query für die Stichwort-/BM25-Suche (z. B. "theme toggle transition", "locale routing").
• Exaktes Namensmuster: Verwenden Sie name_pattern für die Regex-Filterung (z. B. ".*Provider.*", ".*Skeleton.*").
• Semantische konzeptionelle Suche: Verwenden Sie semantic_query: ["i18n", "language", "switch"] (erfordert ein Array von Zeichenketten), um Vokabellücken zu überbrücken.
• Umgang mit Abschneidung (has_more): Wenn die Antwort "has_more": true zurückgibt, paginieren Sie durch Hinzufügen von "offset": <aktueller_offset + limit>.

---

Schritt 3: Beziehungsverfolgung & Auswirkungsradius

Ändern Sie niemals eine Funktion oder Schnittstelle, ohne deren Abhängigkeiten zu überprüfen.

1. Aufrufer & Aufgerufene verfolgen (trace_path):

   {
     "ServerName": "codebase-memory",
     "ToolName": "trace_path",
     "Arguments": {
       "project": "D-Scripts-aminwebsite",
       "function_name": "D-Scripts-aminwebsite.app.components.LocaleSwitcher.handleSelectLocale",
       "direction": "both",
       "depth": 3
     }
   }
   

   • direction: "inbound": Identifiziert alle Aufrufer, die von dieser Funktion abhängen (Auswirkungsradius).
   • direction: "outbound": Identifiziert nachgelagerte Funktionen, die von diesem Symbol aufgerufen werden.
   • direction: "both": Vollständige bidirektionale Aufrufkette.

2. Git-Diff-Auswirkungsbereich kartieren (detect_changes): Bewerten Sie vor dem Commit oder dem Abschluss von Änderungen den Auswirkungsradius:

   {
     "ServerName": "codebase-memory",
     "ToolName": "detect_changes",
     "Arguments": {
       "project": "D-Scripts-aminwebsite",
       "base_branch": "main",
       "scope": "impact"
     }
   }
   

---

Schritt 4: Chirurgischer Code-Abruf (get_code_snippet)

Anstatt Kontext durch das Anzeigen ganzer Dateien mit view_file zu verbrauchen, rufen Sie exakte Symbolimplementierungen ab:

{
  "ServerName": "codebase-memory",
  "ToolName": "get_code_snippet",
  "Arguments": {
    "project": "D-Scripts-aminwebsite",
    "qualified_name": "D-Scripts-aminwebsite.app.components.LocaleSwitcher.LocaleSwitcher"
  }
}

Die Antwort enthält:

• Exakte start_line und end_line
• Sauberen Quellcode des Symbols
• Direkte Aufrufer- und Aufgerufenen-Anzahl

---

Schritt 5: High-Level-Architektur-Erkundung (get_architecture)

Wenn Sie sich in einem neuen Subsystem orientieren oder die Systemtopologie verstehen möchten:

{
  "ServerName": "codebase-memory",
  "ToolName": "get_architecture",
  "Arguments": {
    "project": "D-Scripts-aminwebsite",
    "aspects": ["layers", "hub_nodes"]
  }
}

Identifiziert die wichtigsten architektonischen Hub-Komponenten, zentralen Abhängigkeiten und die Schichthierarchie.

---

MCP Lazy Tool Referenz-Matrix

Fähigkeit	Tool Name	Erforderliche Parameter	Wichtige optionale Parameter
Status prüfen	index_status	project	N/A
Indizierung auslösen	index_repository	repo_path	mode ("fast", "moderate", "full"), persistence
Projekte auflisten	list_projects	Keine	N/A
Symbole durchsuchen	search_graph	project	query, name_pattern, semantic_query, limit, offset
Aufrufkette verfolgen	trace_path	project, function_name	direction ("inbound", "outbound", "both"), depth, mode
Quelle abrufen	get_code_snippet	project, qualified_name	include_neighbors
Auswirkungsradius	detect_changes	project	base_branch, since, scope ("impact", "files"), depth
Architektur	get_architecture	project	aspects (["hub_nodes"], ["layers"], ["all"])
Wörtlicher Text	search_code	project, query	file_pattern, case_sensitive, limit

---

Leitplanken & Häufige Anti-Patterns

Anti-Pattern	Korrekter Betriebsstandard
Suche ohne Überprüfung der Index-Aktualität	Rufen Sie immer zuerst index_repository(mode: "fast") auf oder überprüfen Sie es mit index_status, da die Hintergrund-Auto-Watch deaktiviert ist.
Verwenden von grep zum Finden von Funktionsdefinitionen	Rufen Sie search_graph mit dem Symbolnamen auf; es gibt qualifizierte Namen, exakte Dateipfade, Zeilenbereiche und Aufruferanzahlen zurück.
1000 Zeilen einer Datei lesen, um 1 Funktion zu sehen	Rufen Sie get_code_snippet mit dem qualified_name des Symbols auf.
Jede Datei manuell lesen, um Aufrufer zu finden	Rufen Sie trace_path mit direction: "inbound" auf.
Annehmen, dass der Graph zu 100 % vollständig ist	Der Graph ist eine Bemühung nach bestem Wissen. Wenn index_status Dateien unter parse_partial auflistet, verwenden Sie Text-Grep für diese spezifischen markierten Zeilenbereiche.
Aktivieren von auto_watch	Aktivieren Sie auto_watch niemals; halten Sie es auf false, um eine optimale interaktive Entwicklungsumgebungsleistung zu gewährleisten.