This commit is contained in:
Lars committed 2025-12-19 09:02:49 +01:00
1 parent 0d71f41a13
commit 2cd3605017
8 files changed
+334 -263

No files matched your search

+65 -39
View File
@@ -3,13 +3,13 @@ doc_type: concept
audience: architect, product_owner
scope: graph, logic, provenance
status: active
version: 2.6
context: "Fachliche Beschreibung des Wissensgraphen: Knoten, Kanten, Provenance und Matrix-Logik."
version: 2.7.0
context: "Fachliche Beschreibung des Wissensgraphen: Knoten, Kanten, Provenance, Matrix-Logik und WP-22 Scoring-Prinzipien."
---
# Konzept: Die Graph-Logik
**Quellen:** `mindnet_functional_architecture.md`, `chunking_strategy.md`
**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.
@@ -19,7 +19,7 @@ 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.
* **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.
@@ -29,71 +29,97 @@ Da LLMs (Large Language Models) nicht unendlich viel Text auf einmal lesen könn
* **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.
Kanten machen aus isolierten Informationen Wissen. Mindnet nutzt gerichtete Kanten mit semantischer Bedeutung, die durch die **Edge Registry** validiert werden.
### 2.1 Semantische Typen
### 2.1 Kanonische Typen & Aliase
Um eine konsistente mathematische Gewichtung zu garantieren, werden alle Kanten auf **kanonische Typen** normalisiert.
| Kanten-Typ | Frage, die er beantwortet | Beispiel |
| Kanonischer Typ | Aliase (Beispiele) | Bedeutung |
| :--- | :--- | :--- |
| `references` | Worüber wird gesprochen? | Text erwähnt "Python". |
| `depends_on` | Was ist Voraussetzung? | Projekt braucht "Budget". |
| `caused_by` | Warum ist das passiert? | Bug durch "Commit X". |
| `blocks` | Was steht im Weg? | Risiko blockiert "Release". |
| `based_on` | Worauf fußt das? | Erfahrung basiert auf "Wert Y". |
| `derived_from` | Woher kommt das? | Prinzip stammt aus "Buch Z". |
| `related_to` | Was ist ähnlich? | "Hund" ist verwandt mit "Wolf". |
| `solves` | Was ist die Lösung? | "Qdrant" löst "Vektorsuche". |
| `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 in v2.6 drei Qualitätsstufen (**Provenance**), um Konflikte aufzulösen.
Nicht alle Kanten sind gleich viel wert. Mindnet unterscheidet drei 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:* Dies ist hartes Faktenwissen. "Ich habe diesen Link bewusst gesetzt."
* *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 geprüft, ob der Link im Kontext dieses Textabschnitts wirklich relevant ist. Dies filtert "Rauschen" heraus (z.B. Links im Footer, die nichts mit dem Absatz zu tun haben).
* *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.
* *Quelle:* `types.yaml` Defaults oder Matrix-Logik.
* *Vertrauen:* **Niedrig (0.7)**.
* *Bedeutung:* Eine Heuristik. "Weil es ein Projekt ist, nehmen wir an, dass es von allen erwähnten Technologien abhängt."
* *Bedeutung:* Systemseitige Heuristik. Diese Verbindungen dienen der Entdeckung neuer Pfade, haben aber weniger Gewicht als explizite Links.
---
## 3. Matrix-Logik (Kontext-Sensitivität)
Mit WP11 wurde eine Intelligenz eingeführt, die Kanten-Typen nicht nur anhand des Quell-Typs, sondern auch anhand des Ziel-Typs bestimmt ("Matrix").
Die Matrix-Logik bestimmt Kanten-Typen dynamisch anhand der Quell- und Ziel-Typen der verknüpften Notizen.
**Logik-Beispiele:**
* **Quelle `experience` → Ziel `value`**
* *Standard:* `references`
* *Matrix:* `based_on` (Erfahrungen basieren auf Werten).
* **Quelle `principle` → Ziel `source` (Buch)**
* *Standard:* `references`
* *Matrix:* `derived_from` (Prinzipien stammen aus Quellen).
* **Quelle `project` → Ziel `tool`**
* *Standard:* `references`
* *Matrix:* `uses` (Projekte nutzen Tools).
*Nutzen:* Dies erlaubt im Chat präzise Fragen wie: *"Auf welchen Werten basiert diese Entscheidung?"* (Suche nach eingehenden `based_on` Kanten).
* **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. Idempotenz & Konsistenz
## 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. Idempotenz & Konsistenz
Das System garantiert fachliche Konsistenz auch bei mehrfachen Importen.
* **Stabile IDs:** Importiert man dieselbe Datei zweimal, ändern sich die IDs der Knoten nicht.
* **Keine Duplikate:** Kanten werden dedupliziert. Die "stärkere" Quelle (Explicit > Smart > Rule) gewinnt.
* **Lösch-Garantie:** Wenn eine Notiz gelöscht wird, verschwinden auch alle ihre Chunks und ausgehenden Kanten (via `--sync-deletes`).
* **Stabile IDs:** Deterministische IDs verhindern Duplikate bei Re-Imports.
* **Deduplizierung:** Kanten werden anhand ihrer Identität erkannt. Die "stärkere" Provenance gewinnt.