# Mindnet v2.4 – Fachliche Architektur
**Datei:** `docs/mindnet_functional_architecture_v2.6.md`
**Stand:** 2025-12-12
**Status:** **FINAL** (Integrierter Stand WP01–WP15: Smart Edges & Traffic Control)

> Dieses Dokument beschreibt **was** Mindnet fachlich tut und **warum** – mit Fokus auf die Erzeugung und Nutzung von **Smart Edges** (Kanten), die Logik des Retrievers und den **RAG-Chat** (Decision Engine, Interview-Modus & Persönlichkeit).

---
<details>
<summary>📖 <b>Inhaltsverzeichnis (Klicken zum Öffnen)</b></summary>

- [Mindnet v2.4 – Fachliche Architektur](#mindnet-v24--fachliche-architektur)
  - [](#)
  - [0) Zielbild \& Grundprinzip](#0-zielbild--grundprinzip)
  - [1) Notizen \& Chunks (fachliche Perspektive)](#1-notizen--chunks-fachliche-perspektive)
    - [1.1 Notiz (Note)](#11-notiz-note)
    - [1.2 Chunk](#12-chunk)
  - [2) Edges – fachliche Typen \& Bedeutung](#2-edges--fachliche-typen--bedeutung)
    - [2.1 Struktur-Kanten (Das Skelett)](#21-struktur-kanten-das-skelett)
    - [2.2 Inhalts-Kanten (explizit)](#22-inhalts-kanten-explizit)
    - [2.3 Typ-basierte Default-Kanten (Regelbasiert)](#23-typ-basierte-default-kanten-regelbasiert)
    - [2.4 Smart Edge Allocation (LLM-gefiltert) – Neu in v2.6](#24-smart-edge-allocation-llm-gefiltert--neu-in-v26)
    - [2.5 Matrix-Logik (Kontextsensitive Kanten)](#25-matrix-logik-kontextsensitive-kanten)
  - [3) Edge-Payload – Felder \& Semantik](#3-edge-payload--felder--semantik)
  - [4) Typ-Registry (`config/types.yaml`)](#4-typ-registry-configtypesyaml)
    - [4.1 Zweck](#41-zweck)
    - [4.2 Beispiel (auslieferungsnah)](#42-beispiel-auslieferungsnah)
  - [5) Der Retriever (Funktionaler Layer)](#5-der-retriever-funktionaler-layer)
    - [5.1 Scoring-Modell](#51-scoring-modell)
    - [5.2 Erklärbarkeit (Explainability) – WP04b](#52-erklärbarkeit-explainability--wp04b)
    - [5.3 Graph-Expansion](#53-graph-expansion)
  - [6) Context Intelligence \& Intent Router (WP06–WP15)](#6-context-intelligence--intent-router-wp06wp15)
    - [6.1 Das Problem: Statische vs. Dynamische Antworten](#61-das-problem-statische-vs-dynamische-antworten)
    - [6.2 Der Hybrid Router v5 (Action vs. Question)](#62-der-hybrid-router-v5-action-vs-question)
    - [6.3 Traffic Control (Realtime vs. Background)](#63-traffic-control-realtime-vs-background)
    - [6.4 Strategic Retrieval (Injektion von Werten)](#64-strategic-retrieval-injektion-von-werten)
    - [6.5 Reasoning (Das Gewissen)](#65-reasoning-das-gewissen)
    - [6.6 Der Interview-Modus (One-Shot Extraction)](#66-der-interview-modus-one-shot-extraction)
    - [6.7 Active Intelligence (Link Suggestions)](#67-active-intelligence-link-suggestions)
  - [7) Future Concepts: The Empathic Digital Twin (Ausblick)](#7-future-concepts-the-empathic-digital-twin-ausblick)
    - [7.1 Antizipation durch Erfahrung](#71-antizipation-durch-erfahrung)
    - [7.2 Empathie \& "Ich"-Modus](#72-empathie--ich-modus)
    - [7.3 Glaubenssätze \& Rituale](#73-glaubenssätze--rituale)
  - [8) Erweiterbarkeit \& Teaching (Context Intelligence)](#8-erweiterbarkeit--teaching-context-intelligence)
    - [A. Workflow: Einen neuen Typ implementieren (z. B. `type: risk`)](#a-workflow-einen-neuen-typ-implementieren-z-b-type-risk)
    - [B. Workflow: Neue Beziehungen nutzen (z. B. `beeinflusst_von`)](#b-workflow-neue-beziehungen-nutzen-z-b-beeinflusst_von)
  - [9) Feedback \& Lernen – WP04c/WP10](#9-feedback--lernen--wp04cwp10)
    - [9.1 Der Feedback-Loop](#91-der-feedback-loop)
  - [10) Confidence \& Provenance – wozu?](#10-confidence--provenance--wozu)
  - [11) Semantik ausgewählter `kind`-Werte](#11-semantik-ausgewählter-kind-werte)
  - [12) Frontmatter-Eigenschaften – Rolle \& Empfehlung](#12-frontmatter-eigenschaften--rolle--empfehlung)
  - [13) Lösch-/Update-Garantien (Idempotenz)](#13-lösch-update-garantien-idempotenz)
  - [14) Beispiel – Von Markdown zu Kanten](#14-beispiel--von-markdown-zu-kanten)
  - [15) Referenzen (Projektdateien \& Leitlinien)](#15-referenzen-projektdateien--leitlinien)
  - [16) Workpackage Status (v2.6.0)](#16-workpackage-status-v260)

</details>
---

## 0) Zielbild & Grundprinzip

Mindnet wandelt Obsidian-Markdown-Notizen in einen **dynamischen Graphen aus Punkten und Kanten** um.
Die drei zentralen Artefakt-Sammlungen lauten:

- `mindnet_notes` – genau **eine** Note pro Markdown-Datei (Metadaten & Hashes)
- `mindnet_chunks` – semantische Teilstücke einer Note (Fenster/„Chunks“)
- `mindnet_edges` – gerichtete Beziehungen zwischen Knoten (Chunks/Notes)

Die Import-Pipeline (seit v2.6 mit **Traffic Control** und **Smart Edges**) erzeugt diese Artefakte **deterministisch** und **idempotent** (erneute Läufe überschreiben konsistent statt zu duplizieren). Die Import-Schritte sind: *parse → chunk → embed → smart-edge-allocation → upsert*.

---

## 1) Notizen & Chunks (fachliche Perspektive)

### 1.1 Notiz (Note)
- Repräsentiert eine fachliche Einheit (z. B. *„Vector DB Basics“*, *„KI-Projekt“*).
- Trägt Eigenschaften (Titel, Typ, Zeitstempel, optionale Policies).
- **Typ** (*type*) steuert u. a. Chunk-Profil und Default-Relationen (siehe §4).
- **retriever_weight** und **chunk_profile** werden systematisch an Note **und** Chunks gespiegelt, damit der Retriever beides nutzen kann.

### 1.2 Chunk
- Ausschnitt/Textfenster aus der Note, als eigenständiger Such-Anker.
- Jeder Chunk gehört **genau einer** Note.
- Chunks bilden eine Sequenz (1…N) – das ermöglicht *next/prev*.
- **Update v2.4:** Chunks werden jetzt durch das Modell `nomic-embed-text` in **768-dimensionale Vektoren** umgewandelt. Dies erlaubt eine deutlich höhere semantische Auflösung als frühere Modelle (384 Dim).
- **Update v2.6 (Smart Chunking):** Ein Chunk ist nicht mehr nur ein dummer Textblock, der alle Links der Mutter-Notiz erbt. Durch die **Smart Edge Allocation (WP15)** "weiß" jeder Chunk genau, welche Kanten inhaltlich zu ihm gehören (siehe 2.4).

> **Wichtig:** Chunking-Profile (short/medium/long/sliding_smart_edges) kommen aus `types.yaml` (per Note-Typ), können aber lokal überschrieben werden. Die effektiven Werte werden bei der Payload-Erzeugung bestimmt.

---

## 2) Edges – fachliche Typen & Bedeutung

Edges kodieren Beziehungen. Sie sind **gerichtet** und werden in `mindnet_edges` gespeichert. Die Erzeugung folgt einer strengen Priorität: **Inline > Callout > Defaults > Struktur**.

### 2.1 Struktur-Kanten (Das Skelett)
- **belongs_to**: *Chunk → Note* (Zuordnung)
- **next / prev**: Kettenbeziehungen zwischen aufeinanderfolgenden Chunks derselben Note.
  → ermöglichen „lineares Weiterlesen“ oder Kontextpfade in Antworten.
Diese Kanten entstehen immer, unabhängig von Inhalten.

### 2.2 Inhalts-Kanten (explizit)
Hier unterscheidet v2.6 präzise zwischen verschiedenen Quellen der Evidenz:

1.  **Explizite Inline-Relationen (Höchste Priorität):**
    Im Fließtext notierte, semantisch qualifizierte Relationen.
    * Syntax: `[[rel:depends_on Embeddings 101]]`
    * Fachliche Aussage: "Hängt ab von", "Ähnlich zu".
    * *rule_id*: `inline:rel`
    * *confidence*: ~0.95

2.  **Callout-Edges (Kuratierte Listen):**
    Redaktionell gepflegte Listen am Ende einer Notiz (z.B. "Siehe auch").
    * Syntax: `> [!edge] related_to: [[Vector DB Basics]]`
    * *rule_id*: `callout:edge`
    * *confidence*: ~0.90

3.  **Wikilinks (Standard-Referenzen):**
    Der klassische Obsidian-Link.
    * Syntax: `[[Vector DB Basics]]`
    * Typ: `references`
    * *rule_id*: `explicit:wikilink`
    * *confidence*: 1.0

> Alle expliziten Quellen (Wikilink, Inline-Rel, Callout) sind **Primärbelege**.

### 2.3 Typ-basierte Default-Kanten (Regelbasiert)
Jede Note hat einen *Typ* (z. B. `concept`, `project`, `profile`). In `config/types.yaml` definieren wir pro Typ **edge_defaults**, z. B.:

- `concept`: `["references","related_to"]`
- `project`: `["references","depends_on"]`

Regel: **Für jede gefundene explizite Referenz** (s. o.) werden **zusätzliche** Edges nach diesen Defaults erzeugt.
Beispiel: Ein *project* mit `edge_defaults=["depends_on"]` erzeugt zu *jedem* explizit referenzierten Ziel **zusätzlich** eine `depends_on`-Kante.
Diese Kanten tragen *provenance=rule* und eine **rule_id** der Form `edge_defaults:{note_type}:{relation}` sowie eine geringere Confidence (~0.7).

### 2.4 Smart Edge Allocation (LLM-gefiltert) – Neu in v2.6
Mit **WP15** wurde ein intelligenter Filter eingeführt, um das Problem des "Broadcasting" zu lösen. Früher erbte jeder Chunk einer Notiz *alle* Links der Notiz, was zu unpräzisem Retrieval führte.

**Der neue Prozess:**
1.  **Scan:** Das System sammelt alle expliziten Links der gesamten Notiz.
2.  **Chunking:** Der Text wird in Abschnitte zerlegt.
3.  **Analyse (LLM):** Ein lokales LLM (Semantic Analyzer) liest jeden Chunk einzeln.
4.  **Entscheidung:** Das LLM entscheidet für jeden Link aus Schritt 1: *"Ist dieser Link im Kontext dieses spezifischen Textabschnitts relevant?"*
5.  **Zuweisung:** Nur wenn das LLM zustimmt, wird die Kante am Chunk erstellt.

*Steuerung:* Dies ist pro Typ in der `types.yaml` konfigurierbar (`enable_smart_edge_allocation: true`).

### 2.5 Matrix-Logik (Kontextsensitive Kanten)
Mit WP-11 wurde eine Intelligenz eingeführt, die Kanten-Typen nicht nur anhand des Quell-Typs, sondern auch anhand des Ziel-Typs bestimmt ("Matrix").

**Beispiel für `Source Type: experience`:**
* Wenn Ziel ist `value` -> Kante: `based_on`
* Wenn Ziel ist `principle` -> Kante: `derived_from`
* Wenn Ziel ist `project` -> Kante: `related_to`

Dies ermöglicht im Graphen präzise Abfragen wie "Zeige alle Erfahrungen, die auf Wert X basieren" (via `based_on`), was mit generischen `related_to` Kanten nicht möglich wäre.

---

## 3) Edge-Payload – Felder & Semantik

Jede Kante hat mindestens:

- `kind` – Beziehungsart *(belongs_to, next, prev, references, related_to, depends_on, similar_to, based_on, uses, …)*
- `scope` – `"chunk"` (Standard in v2.2)
- `source_id`, `target_id` – Quell-/Ziel-Knoten (Chunk-IDs oder Note-Titel bei unresolved Targets)
- `note_id` – **Owner-Note** (die Note, aus der die Kante stammt)

Erweiterte/abgeleitete Felder (WP03 Superset):

- `provenance` – `"explicit"` (Wikilink/Inline/Callout), `"rule"` (Typ-Defaults) oder neu `"smart"` (vom LLM validiert).
- `rule_id` – maschinenlesbare Regelquelle (z.B. `inline:rel`, `edge_defaults:project:depends_on`)
- `confidence` – 0.0–1.0; Heuristik zur Gewichtung im Scoring.

**Dedup-Schlüssel** (fachlich): Gleichlautende `(source_id, target_id, kind, scope, rule_id)` werden nicht mehrfach geschrieben.

---

## 4) Typ-Registry (`config/types.yaml`)

### 4.1 Zweck
- Steuert **Chunking-Profile** (`short|medium|long`) **pro Typ**
- Liefert **retriever_weight** (Note-/Chunk-Gewichtung im Ranking) **pro Typ**
- Definiert **edge_defaults** je Typ (s. o.)
- **Neu in v2.6:** Steuert `enable_smart_edge_allocation` (LLM-Filter) und `detection_keywords` für den Hybrid Router.

Der Importer lädt die Registry aus `MINDNET_TYPES_FILE` oder nutzt Fallbacks. **Frontmatter-Overrides** für Profile werden in v2.2 weitgehend ignoriert zugunsten einer zentralen Governance in der YAML-Datei.

### 4.2 Beispiel (auslieferungsnah)
    version: 2.6.0
    types:
      concept:
        chunk_profile: medium
        edge_defaults: ["references", "related_to"]
        retriever_weight: 0.60
      experience:
        chunk_profile: sliding_smart_edges
        enable_smart_edge_allocation: true  # WP15: LLM prüft Kanten
        detection_keywords: ["passiert", "erlebt", "situation"] # WP06: Router-Trigger
        schema: # WP07: Interview-Struktur
          - "Situation (Was ist passiert?)"
          - "Meine Reaktion (Was habe ich getan?)"

**Auflösung im Importer**
- `effective_chunk_profile(note_type, registry)` → `"short|medium|long"|None`
- `effective_retriever_weight(note_type, registry)` → `float|None`
- Ergebnis wird in `note_payload` **und** `chunk_payloads` gespiegelt.

---

## 5) Der Retriever (Funktionaler Layer)

Der Retriever ist in v2.2 der zentrale Zugangspunkt. Er realisiert die **Hybride Suche**.

### 5.1 Scoring-Modell
Die Relevanz eines Treffers ergibt sich nicht mehr nur aus Textähnlichkeit, sondern aus einer gewichteten Formel:

    total_score =
        semantic_weight   * semantic_score
      + edge_weight       * edge_bonus
      + centrality_weight * centrality_bonus
      + type_weight       * retriever_weight

* **semantic_score:** Vektorähnlichkeit (Qdrant).
* **retriever_weight:** Wichtigkeit des Typs (z.B. Projekte > Quellen).
* **edge_bonus:** Belohnung für Chunks, die im Kontext der Anfrage stark vernetzt sind (Summe der Confidence eingehender relevanter Kanten).
* **centrality_bonus:** Belohnung für Knoten, die zentrale Hubs im lokalen Graphen darstellen.

### 5.2 Erklärbarkeit (Explainability) – WP04b
Der Retriever ist keine Blackbox mehr. Er liefert auf Wunsch (`explain=True`) eine strukturierte Begründung (`Explanation`-Objekt).

**Die "Warum"-Logik:**
1.  **Semantik:** Prüfung der Cosine-Similarity ("Sehr hohe textuelle Übereinstimmung").
2.  **Typ:** Prüfung des `retriever_weight` ("Bevorzugt, da Entscheidung").
3.  **Graph (Kontext):**
    * **Hub (Outgoing):** Worauf verweist dieser Treffer? ("Verweist auf Qdrant").
    * **Authority (Incoming):** Wer verweist auf diesen Treffer? ("Wird referenziert von Projekt Alpha").
    
Die API gibt diese Analysen als menschenlesbare Sätze (`reasons`) und als Datenstruktur (`score_breakdown`) zurück.

### 5.3 Graph-Expansion
Der Hybrid-Modus lädt dynamisch die Nachbarschaft der Top-K Vektor-Treffer ("Seeds") über `graph_adapter.expand`. Dies baut einen temporären `NetworkX`-artigen Graphen im Speicher (Klasse `Subgraph`), auf dem Boni berechnet werden.

---

## 6) Context Intelligence & Intent Router (WP06–WP15)

Seit WP06 agiert Mindnet nicht mehr statisch, sondern passt seine Suchstrategie dem **Intent** (der Absicht) des Nutzers an. Dies ist die Transformation vom reinen Wissens-Abrufer zum strategischen Partner.

### 6.1 Das Problem: Statische vs. Dynamische Antworten
* **Früher (Pre-WP06):** Jede Frage ("Was ist X?" oder "Soll ich X?") wurde gleich behandelt -> Fakten-Retrieval.
* **Heute (WP06):** Das System erkennt, *was* der User will (Rat, Fakten oder Datenerfassung) und wechselt den Modus.

### 6.2 Der Hybrid Router v5 (Action vs. Question)
Der Router wurde in v2.6 (WP15) weiterentwickelt, um Fehlalarme zu vermeiden.

1.  **Frage-Erkennung:**
    * Das System prüft zuerst: Enthält der Satz ein `?` oder typische W-Wörter (Wer, Wie, Was)?
    * Wenn **JA** -> Gehe in den **RAG Modus** (Intent `FACT` oder `DECISION`). Interviews werden hier blockiert.
    
2.  **Befehls-Erkennung (Fast Path):**
    * Wenn **NEIN** (keine Frage), prüft das System auf Keywords in `types.yaml` ("Projekt", "Erfahrung").
    * Treffer -> **INTERVIEW Modus** (Erfassen). Das Schema wird aus `types.yaml` geladen.

3.  **LLM Fallback (Slow Path):**
    * Wenn beides fehlschlägt, entscheidet das LLM über den Intent.

### 6.3 Traffic Control (Realtime vs. Background)
Um den Live-Betrieb (Chat) nicht durch den ressourcenintensiven Smart-Import (LLM-Analyse) zu gefährden, implementiert v2.6 ein **Traffic Control System** im `LLMService`.

* **Realtime Lane (Chat):** Anfragen aus dem Chat erhalten `priority="realtime"`. Sie umgehen alle Warteschlangen und werden sofort bearbeitet.
* **Background Lane (Import):** Anfragen zur Kantenanalyse erhalten `priority="background"`. Sie werden durch eine **Semaphore** gedrosselt (Standard: max 2 parallel), um die Hardware nicht zu überlasten.

### 6.4 Strategic Retrieval (Injektion von Werten)
Im Modus `DECISION` führt das System eine **zweite Suchstufe** aus. Es sucht nicht nur nach semantisch passenden Texten zur Frage, sondern erzwingt das Laden von strategischen Notizen wie:
* **Values (`type: value`):** Moralische Werte (z.B. "Privacy First").
* **Principles (`type: principle`):** Handlungsanweisungen.
* **Goals (`type: goal`):** Strategische Ziele.

### 6.5 Reasoning (Das Gewissen)
Das LLM erhält im Prompt die explizite Anweisung: *"Wäge die Fakten (aus der Suche) gegen die injizierten Werte ab."*
Dadurch entstehen Antworten, die nicht nur technisch korrekt sind, sondern subjektiv passend ("Tool X passt nicht zu deinem Ziel Z").

### 6.6 Der Interview-Modus (One-Shot Extraction)
Wenn der User Wissen erfassen will ("Ich möchte ein neues Projekt anlegen"), wechselt Mindnet in den **Interview-Modus**.

* **Late Binding Schema:** Das System lädt ein konfiguriertes Schema für den Ziel-Typ (z.B. `project`: Pflichtfelder sind Titel, Ziel, Status).
* **One-Shot Extraction:** Statt eines langen Dialogs extrahiert das LLM **sofort** alle verfügbaren Infos aus dem Prompt und generiert einen validen Markdown-Draft mit Frontmatter.
* **Healing Parser (v2.5):** Falls das LLM die YAML-Syntax beschädigt (z.B. fehlendes Ende), repariert das Frontend den Entwurf automatisch.
* **UI-Integration:** Das Frontend rendert statt einer Chat-Antwort einen **interaktiven Editor** (WP10), in dem der Entwurf finalisiert werden kann.

### 6.7 Active Intelligence (Link Suggestions)
Im **Draft Editor** (Frontend) unterstützt das System den Autor aktiv.
* **Analyse:** Ein "Sliding Window" scannt den Text im Hintergrund (auch lange Entwürfe).
* **Erkennung:** Es findet Begriffe ("Mindnet") und semantische Konzepte ("Autofahrt in Italien").
* **Matching:** Es prüft gegen den Index (Aliases und Vektoren).
* **Vorschlag:** Es bietet fertige Markdown-Links an (z.B. `[[rel:related_to ...]]`), die per Klick eingefügt werden.
* **Logik:** Dabei kommt die in 2.5 beschriebene **Matrix-Logik** zum Einsatz, um den korrekten Kanten-Typ vorzuschlagen.

---

## 7) Future Concepts: The Empathic Digital Twin (Ausblick)

Um Mindnet von einer Entscheidungsmaschine zu einem echten **Spiegel der Persönlichkeit** zu entwickeln, sind folgende Erweiterungen konzeptionell vorgesehen:

### 7.1 Antizipation durch Erfahrung
* **Konzept:** Das System soll Konsequenzen vorhersagen ("Was passiert, wenn...?").
* **Umsetzung:** Neben Werten werden vergangene Erfahrungen (`type: experience`) geladen.
* **Logik:** *"In einer ähnlichen Situation (Projekt A) hat Entscheidung X zu Ergebnis Y geführt."*

### 7.2 Empathie & "Ich"-Modus
* **Konzept:** Das System antwortet nicht wie ein Roboter, sondern im Tonfall und Stil des Nutzers.
* **Umsetzung (Few-Shot Prompting):** Der System-Prompt wird dynamisch mit Beispielen gefüttert, wie der Nutzer typischerweise auf E-Mails oder Fragen antwortet.
* **Datenbasis:** `type: profile` oder `type: manifesto` definieren das Selbstbild.

### 7.3 Glaubenssätze & Rituale
* **Konzept:** Berücksichtigung weicher Faktoren und Gewohnheiten.
* **Umsetzung:** Erweiterung der `decision_engine.yaml` um `inject_types: ["belief", "ritual"]`.
* **Szenario:** Bei Terminplanungen werden Rituale ("Keine Meetings vor 10 Uhr") automatisch als harte Restriktion gegen Anfragen geprüft.

---

## 8) Erweiterbarkeit & Teaching (Context Intelligence)

Mindnet lernt nicht durch klassisches Training (Fine-Tuning), sondern durch **Konfiguration**, **Vernetzung** und **Prompting**. Dies ist das **"Teach-the-AI" Paradigma**: Wenn du dem System ein neues Konzept beibringen willst, musst du an drei Stellen eingreifen.

### A. Workflow: Einen neuen Typ implementieren (z. B. `type: risk`)

1.  **Physik definieren (`config/types.yaml`)**
    Steuere, wie schwer der Inhalt wiegt und wie er vernetzt wird.
    ```yaml
    risk:
      chunk_profile: short      # Risiken sind oft kurze Statements
      retriever_weight: 0.90    # Hohe Priorität im Ranking
      edge_defaults: ["blocks"] # Automatische Kante zu verlinkten Projekten
      detection_keywords: ["gefahr", "risiko"] # Für den Hybrid Router
    ```
    *Effekt:* Der Router erkennt das Wort "Risiko" und bietet ein Interview an. Der Retriever spült diese Notizen bei relevanten Anfragen nach oben.

2.  **Semantik erklären (`config/prompts.yaml` / `decision_engine.yaml`)**
    Bringe dem LLM bei, wie es mit diesem Typ umgehen soll. Füge `risk` zur `DECISION`-Strategie hinzu (`inject_types`), damit es bei Entscheidungen geladen wird.

### B. Workflow: Neue Beziehungen nutzen (z. B. `beeinflusst_von`)

Beziehungen sind der Klebstoff für logische Schlussfolgerungen.

1.  **Erfassung im Vault (Markdown)**
    Nutze die Inline-Syntax. Du musst nichts vorab definieren.
    > "Die Entscheidung für Qdrant wurde [[rel:beeinflusst_von Budgetkürzung 2024]]."

2.  **Gewichtung justieren (`config/retriever.yaml`)**
    Standardmäßig sind alle Kanten gleich `1.0`. Wenn Kausalität wichtiger ist als Ähnlichkeit, definiere dies hier:
    ```yaml
    retriever:
      edge_weights:
        beeinflusst_von: 1.5  # Starker Boost: Zieht Ursachen in den Kontext
        related_to: 0.5       # Schwacher Boost: Nur "nice to know"
    ```
    *Effekt:* Bei der Frage nach "Qdrant" landet die "Budgetkürzung" (Ursache) im Kontext, weil die Kante stark ist.

3.  **Interpretation (Prompting)**
    Das LLM erkennt im RAG-Kontext: `Qdrant --[beeinflusst_von]--> Budgetkürzung`.
    Es kann daraus den Satz formulieren: *"Die Wahl fiel vermutlich aufgrund der Budgetkürzung auf Qdrant."*

**Fazit:** Nur wenn **Daten** (Vault), **Physik** (Config) und **Semantik** (Prompt) zusammenspielen, entsteht ein intelligenter Zwilling.

---

## 9) Feedback & Lernen – WP04c/WP10

Das System verfügt nun über ein **Kurzzeitgedächtnis für Interaktionen**, das die Basis für zukünftiges Lernen bildet.

### 9.1 Der Feedback-Loop
Die Interaktion erfolgt primär über das **Web-Interface (WP10)**.

1.  **Suche (Situation):**
    Wenn ein Nutzer eine Anfrage stellt, loggt Mindnet die "Situation":
    * Den Query-Text.
    * Die Top-K Ergebnisse.
    * Den exakten `score_breakdown` zu diesem Zeitpunkt.
    * Eine eindeutige `query_id` wird generiert.

2.  **Bewertung (Label):**
    Der Nutzer bewertet die Antwort (**Sterne**) oder einzelne Quellen (**Faces**) im Frontend.
    Dieses Feedback wird unter Referenzierung der `query_id` in `feedback.jsonl` gespeichert.

3.  **Lernen (Perspektive WP08):**
    Durch die Verknüpfung von Situation und Bewertung entstehen Trainingsdaten. Mindnet kann später analysieren: *"Nutzer bevorzugen Treffer mit hohem Edge-Bonus, auch wenn der Text weniger passt."* -> Konsequenz: `edge_weight` erhöhen.

---

## 10) Confidence & Provenance – wozu?

Der Retriever kann Edges gewichten:
- **provenance**: *explicit* > *smart* (Neu) > *rule*
- **confidence**: numerische Feinsteuerung
- **retriever_weight (Note/Chunk)**: skaliert die Relevanz des gesamten Knotens

Eine typische Gewichtung (konfigurierbar in `retriever.yaml`) ist:
`explicit: 1.0`, `smart: 0.9`, `rule: 0.8`. Damit bevorzugt der Graph **kuratiertes Wissen** (explizit notierte Links) vor „erweiterten“ Default-Ableitungen.

---

## 11) Semantik ausgewählter `kind`-Werte

- `references` – „Nutzt/erwähnt“; neutral, aber stützend für Kontext.
- `related_to` – Ähnlichkeit/Verwandtschaft (symmetrisch interpretierbar).
- `similar_to` – noch engere Ähnlichkeit; oft aus Inline-Rel (bewusst gesetzt).
- `depends_on` – fachliche Abhängigkeit (z. B. „Projekt X hängt von Y ab“).
- **Neu in v2.4 (Matrix):**
    - `based_on` – Erfahrung basiert auf Wert.
    - `derived_from` – Erkenntnis stammt aus Prinzip.
    - `uses` – Projekt nutzt Konzept.
- `belongs_to`, `next`, `prev` – Struktur.

> Symmetrische Relationen (z. B. `related_to`, `similar_to`) können **explizit** nur einseitig notiert sein, aber im Retriever beidseitig interpretiert werden.

---

## 12) Frontmatter-Eigenschaften – Rolle & Empfehlung

Frontmatter-Eigenschaften (Properties) bleiben **minimiert**:
- **type** – steuert Typ-Defaults via Registry (Pflicht für differenziertes Verhalten).
- **tags** – für klassische Filterung.
- **retriever_weight / chunk_profile** – Sollten **nicht** manuell gesetzt werden (Best Practice: `types.yaml` nutzen).
- **links** – Veraltet. Bitte Links primär über Text (Wikilink/Inline/Callout) pflegen.

---

## 13) Lösch-/Update-Garantien (Idempotenz)

- Jede Note hat einen stabilen **note_id** (Frontmatter/Hash).
- Vor einem Upsert können *alte Chunks/Edges einer Note* gefiltert gelöscht werden (`note_id`-Filter) – das hält Collections sauber bei Re-Imports.
- Die Import-Skripte unterstützen Modi wie `--purge-before-upsert` und `--sync-deletes`, um den Graph sauber zu halten.

---

## 14) Beispiel – Von Markdown zu Kanten

**Markdown (Auszug)**
    # Relations Showcase
    …
    Wir nutzen [[rel:depends_on Qdrant Vektordatenbank]] für die Suche.
    …
    Siehe auch: [[Embeddings 101]]
    
    > [!edge] related_to: [[Vector DB Basics]]

**Ergebnis (fachlich - Smart Edges)**
Das LLM analysiert jeden Chunk.
1.  Chunk 1 ("Wir nutzen..."): Enthält `depends_on(Chunk→Qdrant)`. Das LLM bestätigt: Relevant. -> Kante wird erstellt.
2.  Chunk 2 ("Siehe auch..."): Enthält `references(Chunk→Embeddings)`. Das LLM bestätigt.
3.  **Wichtig:** Ein Chunk 3 ("Die Benutzeroberfläche ist blau..."), der keine Erwähnung von Qdrant hat, bekommt **keine** `depends_on` Kante zu Qdrant, auch wenn die Note global verlinkt ist. Das ist der Gewinn von WP15.

---

## 15) Referenzen (Projektdateien & Leitlinien)

- Import-Pipeline & Registry-Auflösung: `scripts/import_markdown.py`.
- Kantenbildung (V2-Logic): `app/core/derive_edges.py`.
- Smart Chunking & Traffic Control: `app/core/chunker.py` & `app/services/llm_service.py`.
- Typ-Registry: `config/types.yaml` & `TYPE_REGISTRY_MANUAL.md`.
- Retriever-Scoring & Explanation: `app/core/retriever.py`.
- Persönlichkeit & Chat: `config/prompts.yaml` & `app/routers/chat.py`.
- Decision Engine: `config/decision_engine.yaml`.
- Logging Service: `app/services/feedback_service.py`.
- Frontend UI: `app/frontend/ui.py`.
- Intelligence Logic: `app/services/discovery.py`.

---

## 16) Workpackage Status (v2.6.0)

Aktueller Implementierungsstand der Module.

| WP | Titel | Status | Anmerkung |
| :--- | :--- | :--- | :--- |
| **WP01** | Knowledge Design | 🟢 Live | Typen, Frontmatter definiert. |
| **WP02** | Chunking Strategy | 🟢 Live | Profilbasiertes Chunking aktiv. |
| **WP03** | Edge Logic / Import | 🟢 Live | Neue Importer-Pipeline mit Provenance. |
| **WP04a**| Retriever Scoring | 🟢 Live | Hybrider Score (Semantik + Graph). |
| **WP04b**| Explanation Layer | 🟢 Live | API liefert Reasons & Breakdown. |
| **WP04c**| Feedback Loop | 🟢 Live | Logging (JSONL) & Traceability aktiv. |
| **WP05** | Persönlichkeit / Chat | 🟢 Live | RAG-Integration mit Context Enrichment. |
| **WP06** | Decision Engine | 🟢 Live | Hybrid Router, Strategic Retrieval. |
| **WP07** | Interview Assistent | 🟢 Live | **One-Shot Extractor & Schemas aktiv.** |
| **WP08** | Self-Tuning | 🔴 Geplant | Auto-Adjustment der Gewichte. |
| **WP10** | Chat Interface | 🟢 Live | Web-Interface (Streamlit). |
| **WP10a**| Draft Editor | 🟢 Live | **Interaktives UI & Healing Parser.** |
| **WP11** | Backend Intelligence | 🟢 Live | **Async Ingestion, Nomic Embeddings, Matrix Logic.** |
| **WP15** | Smart Edge Allocation | 🟢 Live | **LLM-Filter & Traffic Control aktiv.** |
| **WP16** | Auto-Discovery | 🟡 Geplant | UX & Retrieval Tuning. |
| **WP17** | Conversational Memory | 🟡 Geplant | Dialog-Gedächtnis. |