mindnet/docs/02_concepts/02_concept_graph_logic.md

doc_type	audience	scope	status	version	context
concept	architect, product_owner	graph, logic, provenance, agentic_validation, note_scope	active	4.5.8	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:

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:

## 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.