Lars/mindnet
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 21 Wiki Activity
9b0d8c18cb
mindnet/docs/02_concepts/02_concept_graph_logic.md

8.7 KiB
Raw Blame History

doc_type audience scope status version context
concept architect, product_owner graph, logic, provenance active 2.9.1 Fachliche Beschreibung des Wissensgraphen: Knoten, Kanten, Provenance, Matrix-Logik, WP-15c Multigraph-Support und WP-22 Scoring-Prinzipien.

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