--- doc_type: concept audience: architect, product_owner scope: graph, logic, provenance, agentic_validation, note_scope status: active version: 4.5.8 context: "Fachliche Beschreibung des Wissensgraphen: Knoten, Kanten, Provenance, Matrix-Logik, WP-15c Multigraph-Support, WP-22 Scoring-Prinzipien, WP-24c Phase 3 Agentic Edge Validation und automatische Spiegelkanten." --- # Konzept: Die Graph-Logik **Quellen:** `mindnet_functional_architecture.md`, `chunking_strategy.md`, `01_edge_vocabulary.md`, `retriever_scoring.py`, `03_tech_retrieval_scoring.md` Mindnet ist keine reine Dokumentablage, sondern ein **semantischer Graph**. Dieses Dokument beschreibt, wie aus statischen Textdateien ein vernetztes Wissensobjekt wird. ## 1. Die Knoten (Nodes) Der Graph besteht aus zwei Ebenen von Knoten. ### 1.1 Die Note (Das Fachobjekt) Eine Note repräsentiert ein atomares Konzept (z.B. "Projekt Alpha"). * **Eigenschaften:** Titel, Typ, Tags, Erstellungsdatum sowie der **Status** (Lifecycle). * **Rolle:** Sie ist der Container für Metadaten und steuert via `type`, wie der Inhalt verarbeitet wird (siehe `types.yaml`). * **Identität:** Definiert durch eine deterministische UUIDv5. ### 1.2 Der Chunk (Das Suchobjekt) Da LLMs (Large Language Models) nicht unendlich viel Text auf einmal lesen können, werden Notes in kleinere Segmente (**Chunks**) zerlegt. * **Eigenschaften:** Vektor (Embedding 768d), Textfenster, Link zum Vorgänger/Nachfolger. * **Rolle:** Dies sind die eigentlichen Treffer bei einer Suche. * **Hierarchie:** Jeder Chunk gehört streng zu einer Note (`belongs_to`). ### 1.3 Content Lifecycle & Status (WP-22) Seit v2.7 beeinflusst der `status` einer Note direkt deren Gewichtung im Retrieval (Lifecycle Scoring). * **Stable:** Notizen mit `status: stable` erhalten einen positiven Modifier (Standard: 1.0), da sie geprüftes Wissen repräsentieren. * **Draft:** Notizen mit `status: draft` werden durch einen Malus (Standard: 0.5 - 0.8) herabgestuft, um "Rauschen" durch unfertige Gedanken zu reduzieren. * **System/Template:** Diese Status-Typen führen zu einem vollständigen Ausschluss aus dem Index. --- ## 2. Die Kanten (Edges) Kanten machen aus isolierten Informationen Wissen. Mindnet nutzt gerichtete Kanten mit semantischer Bedeutung, die durch die **Edge Registry** validiert werden. ### 2.1 Kanonische Typen & Aliase Um eine konsistente mathematische Gewichtung zu garantieren, werden alle Kanten auf **kanonische Typen** normalisiert. | Kanonischer Typ | Aliase (Beispiele) | Bedeutung | | :--- | :--- | :--- | | `caused_by` | `ausgelöst_durch`, `wegen` | Kausalität: A löst B aus. | | `derived_from` | `abgeleitet_von`, `quelle` | Herkunft: A stammt von B. | | `based_on` | `basiert_auf`, `fundament` | Fundament: B baut auf A auf. | | `solves` | `löst`, `fix_für` | Lösung: A ist Lösung für Problem B. | | `part_of` | `teil_von`, `cluster` | Hierarchie: Kind -> Eltern. | | `depends_on` | `braucht`, `requires` | Abhängigkeit: A braucht B. | | `blocks` | `blockiert`, `risiko_für` | Blocker: A verhindert B. | | `related_to` | `siehe_auch`, `kontext` | Lose Assoziation. | ### 2.2 Provenance (Herkunft & Vertrauen) Nicht alle Kanten sind gleich viel wert. Mindnet unterscheidet mehrere Qualitätsstufen (**Provenance**), um bei der Berechnung des Edge-Bonus Prioritäten zu setzen. **1. Explicit (Der Mensch hat es gesagt)** * *Quelle:* Inline-Links (`[[rel:...]]`) oder Wikilinks im Text. * *Vertrauen:* **Hoch (1.0)**. * *Bedeutung:* Hartes Faktenwissen. Die explizite menschliche Intention wird im Scoring am stärksten gewichtet. **2. Smart (Die KI hat es bestätigt)** * *Quelle:* Smart Edge Allocation (WP15). * *Vertrauen:* **Mittel (0.9)**. * *Bedeutung:* Ein LLM hat die Relevanz des Links im Kontext geprüft. Dies filtert irrelevante Links (z.B. aus Navigationsleisten) heraus. **3. Rule (Die Regel hat es vermutet)** * *Quelle:* `types.yaml` Defaults oder Matrix-Logik. * *Vertrauen:* **Niedrig (0.7)**. * *Bedeutung:* Systemseitige Heuristik. Diese Verbindungen dienen der Entdeckung neuer Pfade, haben aber weniger Gewicht als explizite Links. **4. Structure (System-interne Verkettung)** * *Quelle:* Automatische Struktur-Kanten (`belongs_to`, `next`, `prev`). * *Vertrauen:* **Hoch (1.0)**. * *Bedeutung:* Diese Kanten werden ausschließlich durch interne Prozesse erzeugt und sind durch die **Provenance Firewall** geschützt. Sie können weder durch Nutzer noch durch KI manipuliert werden. ### 2.3 Provenance Firewall (WP-15c) Die **Edge Registry** (v0.8.0) implementiert eine strikte Trennung zwischen System-Kanten und Inhalts-Kanten: * **Geschützte System-Kanten:** `next`, `prev`, `belongs_to` dürfen nur mit `provenance="structure"` gesetzt werden. * **Blockierung:** Alle anderen Provenienzen (`explicit`, `semantic_ai`, `inherited`, `global_pool`, `rule`) werden bei System-Kanten blockiert und auf `related_to` zurückgesetzt. * **Zweck:** Sichert die Graph-Integrität und verhindert Manipulationen an der internen Struktur. --- ## 3. Matrix-Logik (Kontext-Sensitivität) Die Matrix-Logik bestimmt Kanten-Typen dynamisch anhand der Quell- und Ziel-Typen der verknüpften Notizen. **Logik-Beispiele:** * **Quelle `experience` → Ziel `value`**: Wird zu `based_on` (Erfahrungen fußen auf Werten). * **Quelle `principle` → Ziel `source`**: Wird zu `derived_from` (Prinzipien stammen aus Quellen). --- ## 4. Semantisch bezogene Booster & Scoring-Logik Das Scoring in Mindnet v2.7 folgt einer hybriden Logik, bei der semantische Ähnlichkeit durch kontextuelle Faktoren modifiziert wird. ### 4.1 Semantische Modifikatoren (Type & Status) Bevor der Graph-Bonus berechnet wird, durchläuft die semantische Ähnlichkeit (Cosine Similarity) zwei Filter: 1. **Type-Weight ($W_{type}$):** Bestimmt die "Wichtigkeit" einer Notizklasse. Ein Wert von 1.0 (z. B. für `decision`) lässt die volle semantische Stärke durch. Ein Wert von 0.4 (z. B. für `glossary`) dämpft den Treffer massiv ab, es sei denn, die Frage passt exakt auf den Text. 2. **Status-Modifier:** Agiert als Qualitätsfilter. `draft` markierte Inhalte werden herabgestuft, damit `stable` Inhalte bei gleicher semantischer Passung immer oben stehen. ### 4.2 Graph-Boosting (Additive Boni) Der Graph-Bonus wird auf den modifizierten semantischen Score addiert. Dies ermöglicht es Inhalten, im Ranking nach oben zu steigen, wenn sie stark mit anderen relevanten Treffern vernetzt sind. | Parameter-Gruppe | Wertebereich | Logik | | :--- | :--- | :--- | | **Notiz-Gewichte** | 0.1 - 1.0 | Multiplikativ. Dient als Relevanz-Filter für Informationstypen. | | **Kanten-Boosts** | 0.1 - 3.0+ | Additiv. Hebt vernetztes Wissen über isolierte Texttreffer. | | **Status-Malus** | 0.5 - 0.9 | Multiplikativ. Bestraft unfertiges Wissen (Drafts). | --- ## 5. Dynamic Intent Boosting (WP-22) In v2.7 ist die Graph-Gewichtung nicht mehr statisch, sondern hängt vom **Intent** der Nutzerfrage ab (Query-Time Boosting). Der Intent-Router injiziert spezifische Multiplikatoren für kanonische Typen: * **Intent `EMPATHY`**: Boostet `based_on` (Fokus auf Werte). * **Intent `WHY`**: Boostet `caused_by` (Fokus auf Ursachenforschung). --- ## 6. Section-basierte Links & Multigraph-Support Seit v2.9.1 unterstützt Mindnet **Deep-Links** zu spezifischen Abschnitten innerhalb einer Note. ### 6.1 Link-Parsing & Self-Links (WP-15c) Die Logik erkennt nun präzise **Obsidian-Anker** (`[[Note#Section]]`) und **Self-Links** (`[[#Section]]`): * **Obsidian-Anker:** `[[Note#Section]]` wird in `target_id="Note"` und `target_section="Section"` aufgeteilt. * **Self-Links:** `[[#Section]]` wird zu `target_id="current_note_id"` und `target_section="Section"` aufgelöst. * **`target_id`:** Enthält nur den Note-Namen (z.B. "Mein Leitbild") * **`target_section`:** Enthält den Abschnitts-Namen (z.B. "P3 – Disziplin") **Vorteil:** Verhindert "Phantom-Knoten", die durch das Einbeziehen des Anchors in die `target_id` entstanden wären. Ermöglicht präzise Verlinkung innerhalb derselben Note. ### 6.2 Multigraph-Support Die Edge-ID enthält nun einen `variant`-Parameter (die Section), sodass mehrere Kanten zwischen denselben Knoten existieren können, wenn sie auf verschiedene Sections zeigen: * `[[Note#Section1]]` → Edge-ID: `src->tgt:kind@Section1` * `[[Note#Section2]]` → Edge-ID: `src->tgt:kind@Section2` ### 6.3 Semantische Deduplizierung Die Deduplizierung basiert auf dem `src->tgt:kind@sec` Key, um sicherzustellen, dass identische Links (gleiche Quelle, Ziel, Typ und Section) nicht mehrfach erstellt werden. --- ## 7. Automatische Spiegelkanten (Invers-Logik) - WP-24c v4.5.8 Das System erzeugt automatisch **Spiegelkanten** (Invers-Kanten) für explizite Verbindungen, um die Auffindbarkeit von Informationen zu verdoppeln. ### 7.1 Funktionsweise **Beispiel:** - **Explizite Kante:** Note A `depends_on: Note B` - **Automatische Spiegelkante:** Note B `enforced_by: Note A` **Vorteil:** Beide Richtungen sind durchsuchbar. Wenn du nach "Note B" suchst, findest du auch alle Notizen, die von "Note B" abhängen (via `enforced_by`). ### 7.2 Invers-Mapping Die Edge Registry definiert für jeden Kanten-Typ das symmetrische Gegenstück: - `depends_on` ↔ `enforced_by` - `derived_from` ↔ `resulted_in` - `impacts` ↔ `impacted_by` - `blocks` ↔ `blocked_by` - `next` ↔ `prev` - `related_to` ↔ `related_to` (symmetrisch) ### 7.3 Priorität & Schutz * **Explizite Kanten haben Vorrang:** Wenn du bereits beide Richtungen explizit gesetzt hast, wird keine automatische Spiegelkante erzeugt (keine Duplikate) * **Höhere Wirksamkeit expliziter Kanten:** Explizit gesetzte Kanten haben höhere Confidence-Werte (`confidence: 1.0`) als automatisch generierte Spiegelkanten (`confidence: 0.9 * original`) * **Provenance Firewall:** System-Kanten (`belongs_to`, `next`, `prev`) können nicht manuell überschrieben werden ### 7.4 Phase 2 Symmetrie-Injektion Spiegelkanten werden am Ende des gesamten Imports (Phase 2) in einem Batch-Prozess injiziert: - **Authority-Check:** Nur wenn keine explizite Kante existiert, wird die Spiegelkante erzeugt - **ID-Konsistenz:** Verwendet exakt dieselbe ID-Generierung wie Phase 1 (inkl. `target_section`) - **Logging:** `🔄 [SYMMETRY]` zeigt die erzeugten Spiegelkanten --- ## 8. Phase 3 Agentic Edge Validation - WP-24c v4.5.8 Das System implementiert ein finales Validierungs-Gate für alle Kanten mit `candidate:` Präfix, um "Geister-Verknüpfungen" zu verhindern und die Graph-Qualität zu sichern. ### 8.1 Trigger-Kriterium Kanten erhalten `candidate:` Präfix, wenn sie: - In `### Unzugeordnete Kanten` Sektionen stehen - Von der Smart Edge Allocation als Kandidaten vorgeschlagen wurden - Explizit als `candidate:` markiert wurden ### 8.2 Validierungsprozess 1. **Kontext-Optimierung:** - **Note-Scope (`scope: note`):** LLM nutzt `note_summary` (Top 5 Chunks) oder `note_text` (aggregierter Gesamttext) - **Chunk-Scope (`scope: chunk`):** LLM nutzt spezifischen Chunk-Text, falls verfügbar, sonst Note-Text 2. **LLM-Validierung:** - Nutzt `ingest_validator` Profil (Temperature 0.0 für Determinismus) - Prüft semantisch: "Passt diese Verbindung zum Kontext?" - Binäre Entscheidung: YES (VERIFIED) oder NO (REJECTED) 3. **Ergebnis:** - **VERIFIED:** `candidate:` Präfix wird entfernt, Kante wird persistiert - **REJECTED:** Kante wird **nicht** in die Datenbank geschrieben (verhindert persistente "Geister-Verknüpfungen") ### 8.3 Fehlertoleranz Das System unterscheidet zwischen: - **Transienten Fehlern (Netzwerk, Timeout):** Kante wird erlaubt (Integrität vor Präzision) - **Permanenten Fehlern (Config, Validation):** Kante wird abgelehnt (Graph-Qualität schützen) ### 8.4 Provenance nach Validierung - **Vor Validierung:** `provenance: "candidate:global_pool"` oder `rule_id: "candidate:..."` - **Nach VERIFIED:** `provenance: "global_pool"` oder `rule_id: "explicit"` (Präfix entfernt) - **Nach REJECTED:** Kante existiert nicht im Graph (wird nicht persistiert) --- ## 9. Note-Scope vs. Chunk-Scope - WP-24c v4.2.0 Das System unterscheidet zwischen **Note-Scope** (globale Verbindungen) und **Chunk-Scope** (lokale Referenzen). ### 9.1 Chunk-Scope (Standard) - **Quelle:** `source_id = chunk_id` (z.B. `note-id#c00`) - **Kontext:** Spezifischer Textabschnitt (Chunk) - **Verwendung:** Lokale Referenzen innerhalb eines Abschnitts - **Phase 3 Validierung:** Nutzt spezifischen Chunk-Text **Beispiel:** ```markdown In diesem Abschnitt nutzen wir [[rel:uses|Technologie X]]. ``` ### 9.2 Note-Scope - **Quelle:** `source_id = note_id` (nicht `chunk_id`) - **Kontext:** Gesamte Note (Note-Summary oder Note-Text) - **Verwendung:** Globale Verbindungen, die für die ganze Note gelten - **Phase 3 Validierung:** Nutzt `note_summary` (Top 5 Chunks) oder `note_text` (aggregierter Gesamttext) **Beispiel:** ```markdown ## Smart Edges [[rel:depends_on|Projekt-Übersicht]] [[rel:part_of|Größeres System]] ``` ### 9.3 Priorität Bei Duplikaten (gleiche Kante in Chunk-Scope und Note-Scope): 1. **Note-Scope Links** haben **höchste Priorität** 2. Dann Confidence-Wert 3. Dann Provenance-Priority --- ## 10. Idempotenz & Konsistenz Das System garantiert fachliche Konsistenz auch bei mehrfachen Importen. * **Stabile IDs:** Deterministische IDs verhindern Duplikate bei Re-Imports. * **Deduplizierung:** Kanten werden anhand ihrer Identität (inkl. Section) erkannt. Die "stärkere" Provenance gewinnt. * **Format-agnostische Erkennung:** Kanten werden unabhängig vom Format (Inline, Callout, Wikilink) erkannt, um Dopplungen zu vermeiden. * **Phase 3 Validierung:** Verhindert persistente "Geister-Verknüpfungen" durch Ablehnung irrelevanter Kanten.