2025-12-11 16:58:23 +01:00

24 KiB

Raw Blame History

Mindnet v2.4 – Fachliche Architektur

Datei: docs/mindnet_functional_architecture_v2.4.md Stand: 2025-12-11 Status: FINAL (Integrierter Stand WP01–WP11: Async Intelligence)

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

📖 Inhaltsverzeichnis (Klicken zum Öffnen)

Mindnet v2.4 – Fachliche Architektur

---

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.3.10 asynchron) erzeugt diese Artefakte deterministisch und idempotent (erneute Läufe überschreiben konsistent statt zu duplizieren). Die Import-Schritte sind: parse → chunk → embed → edge → 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).
Neu in v2.2: Alle Kanten entstehen ausschließlich zwischen Chunks (Scope="chunk"), nie zwischen Notes direkt. Notes dienen nur noch als Metadatencontainer.

Wichtig: Chunking-Profile (short/medium/long) 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.2 präzise zwischen verschiedenen Quellen der Evidenz:

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
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
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 Matrix-Logik (Kontextsensitive Kanten) – Neu in v2.4

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) oder "rule" (Typ-Defaults)
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.)

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: 1.0
types:
  concept:
    chunk_profile: medium
    edge_defaults: ["references", "related_to"]
    retriever_weight: 0.60
  project:
    chunk_profile: long
    edge_defaults: ["references", "depends_on"]
    retriever_weight: 0.97

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:

Semantik: Prüfung der Cosine-Similarity ("Sehr hohe textuelle Übereinstimmung").
Typ: Prüfung des retriever_weight ("Bevorzugt, da Entscheidung").
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.

6) Context Intelligence & Intent Router (WP06–WP11)

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 Intent-Router (Keyword & Semantik)

Der Router prüft vor jeder Antwort die Absicht über konfigurierbare Strategien (config/decision_engine.yaml):

FACT: Reine Wissensfrage ("Was ist Qdrant?"). → Standard RAG.
DECISION: Frage nach Rat oder Strategie ("Soll ich Qdrant nutzen?"). → Aktiviert die Decision Engine.
EMPATHY: Emotionale Zustände ("Ich bin gestresst"). → Aktiviert den empathischen Modus.
INTERVIEW (WP07): Wunsch, Wissen zu erfassen ("Neues Projekt anlegen"). → Aktiviert den Draft-Generator.
CODING: Technische Anfragen.

6.3 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.4 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.5 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.
Draft-Status: Fehlende Pflichtfelder werden mit [TODO] markiert.
UI-Integration: Das Frontend rendert statt einer Chat-Antwort einen interaktiven Editor (WP10), in dem der Entwurf finalisiert werden kann.

6.6 Active Intelligence (Link Suggestions) – Neu in v2.4

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.4 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`)

Physik definieren (config/types.yaml) Steuere, wie schwer der Inhalt wiegt und wie er vernetzt wird.

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

Effekt: Der Retriever spült diese Notizen bei relevanten Anfragen nach oben.

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.

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."
Gewichtung justieren (config/retriever.yaml) Standardmäßig sind alle Kanten gleich 1.0. Wenn Kausalität wichtiger ist als Ähnlichkeit, definiere dies hier:
```
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.
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).

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

depends_on(Chunk→Qdrant) mit rule_id=inline:rel, confidence≈0.95.
references(Chunk→Embeddings 101) mit rule_id=explicit:wikilink, confidence=1.0.
related_to(Chunk→Vector DB Basics) via Callout; rule_id=callout:edge, confidence≈0.90.
Typ-Defaults: Falls die Note vom Typ project ist, entstehen zusätzlich depends_on-Kanten zu den Zielen aus (2) und (3).

15) Referenzen (Projektdateien & Leitlinien)

Import-Pipeline & Registry-Auflösung: scripts/import_markdown.py.
Kantenbildung (V2-Logic): app/core/derive_edges.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.4.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	Intent-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 für WP07 Drafts.
WP11	Backend Intelligence	🟢 Live	Async Ingestion, Nomic Embeddings, Matrix Logic.

24 KiB Raw Blame History Unescape Escape