Lars/mindnet
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 21 Wiki Activity
e5db7011f3
mindnet/docs/99_Archive/alte_Versionen/V2.6.0/Knowledge_Design_Manual.md
Lars 620858a575
All checks were successful
Deploy mindnet to llm-node / deploy (push) Successful in 4s
Details
neue Dokumentationstruktur - (QS geprüft)
2025-12-13 18:38:37 +01:00

14 KiB
Raw Blame History

mindnet v2.4 – Knowledge Design Manual

Datei: docs/mindnet_knowledge_design_manual_v2.6.md Stand: 2025-12-12 Status: FINAL (Integrierter Stand WP01–WP15) Quellen: knowledge_design.md, TYPE_REGISTRY_MANUAL.md, chunking_strategy.md, mindnet_functional_architecture.md.

⚡ Die 5 Goldenen Regeln (TL;DR)

Damit Mindnet als dein Digitaler Zwilling funktioniert, beachte beim Schreiben diese Grundsätze:

  1. Atomare Gedanken: Eine Notiz = Ein Thema. Wenn du über zwei Projekte schreibst, mach zwei Notizen draus.
  2. Explizite Typen: Setze immer den type im Frontmatter. Mindnet behandelt eine decision ("Wir machen X") völlig anders als ein concept ("Was ist X").
  3. Semantische Links: Schreibe nicht nur [[Link]], sondern [[rel:depends_on Link]]. Sag dem System wie Dinge zusammenhängen.
  4. Werte & Ziele definieren: Damit die Decision Engine dich beraten kann, musst du deine Kriterien (type: value, type: goal) explizit als Notizen anlegen.
  5. Emotionales Bridging: Damit die Empathie funktioniert, nutze in Erfahrungsberichten (type: experience) emotionale Schlüsselwörter ("Krise", "Freude", "Angst"), damit der Vektor-Retriever sie bei Gefühls-Anfragen findet.

1. Zweck & Scope

Dieses Handbuch ist die primäre Arbeitsanweisung für dich als Mindmaster (Owner) und alle Autoren, die Inhalte im mindnet-Vault erstellen.

1.1 Zielsetzung

Mindnet ist mehr als eine Dokumentablage. Es ist ein vernetztes System, das deine Persönlichkeit, Entscheidungen und Erfahrungen abbildet. Seit Version 2.6 verfügt Mindnet über:

  • Hybrid Router: Das System erkennt, ob du Fakten, Entscheidungen oder Empathie brauchst.
  • Smart Edge Allocation: Das System prüft deine Links intelligent und bindet sie nur an die Textabschnitte (Chunks), wo sie wirklich relevant sind.
  • Web UI (WP10): Du kannst direkt sehen, welche Quellen genutzt wurden.
  • Active Intelligence (WP11): Das System hilft dir beim Schreiben und Vernetzen (Link-Vorschläge).

1.2 Der Vault als „Source of Truth“

Die Markdown-Dateien in deinem Vault sind die einzige Quelle der Wahrheit.

  • Mindnet importiert diesen Zustand deterministisch in die Datenbank (Qdrant).
  • Änderungen an IDs, Typen oder Inhalten müssen immer im Markdown erfolgen, niemals direkt in der Datenbank.
  • Was nicht im Markdown steht (z. B. implizites Wissen im Kopf), existiert für das System nicht.

2. Note-Struktur & Frontmatter

Jede Notiz benötigt einen YAML-Header (Frontmatter) am Dateianfang. Dieser Block macht die Notiz maschinenlesbar.

2.1 Pflichtfelder

Jede Datei muss mindestens folgende Felder enthalten, um korrekt verarbeitet zu werden:

---
id: 20251110-projekt-alpha-8a9b2c   # Eindeutige Kennung (YYYYMMDD-slug)
title: Projekt Alpha                 # Sprechender Titel (wird in Suchergebnissen angezeigt)
type: project                        # Steuert Verarbeitung & Vernetzung (siehe Kap. 3)
status: active                       # active, archived oder 'draft' (für generierte Notes)
created: 2025-11-10                  # Erstellungsdatum (ISO 8601 oder YYYY-MM-DD)
updated: 2025-12-07                  # Letzte Änderung
tags: [ki, entwicklung]              # Taxonomie für Filterung
---

2.2 Optionale Felder

Diese Felder sind technisch nicht zwingend, aber für bestimmte Typen sinnvoll:

lang: de                             # Sprache (Default: de)
aliases: [Alpha Projekt, Project A]  # Synonyme (WICHTIG für Exact Match in Intelligence)
visibility: internal                 # internal (default), public, private

Hinweis: Felder wie retriever_weight oder chunk_profile sollten nicht mehr manuell im Frontmatter gesetzt werden. Diese werden zentral über den type gesteuert (siehe Kap. 3), um die Wartbarkeit zu sichern.

2.3 Empfehlungen für IDs und Pfade

Die ID (Identifikator):

  • Muss global eindeutig und stabil sein.
  • Darf sich nicht ändern, wenn die Datei umbenannt oder verschoben wird.
  • Empfehlung: YYYYMMDD-slug (z. B. 20231027-vektor-db). Dies garantiert Eindeutigkeit und Chronologie.

Dateinamen & Pfade:

  • Pfade dienen der menschlichen Ordnung (Ordnerstruktur), sind für Mindnet aber sekundär.
  • Dateinamen sollten dem Titel entsprechen (Projekt Alpha.md) oder dem Slug (projekt-alpha.md).
  • Sonderzeichen vermeiden (außer Bindestrich und Unterstrich).

3. Note-Typen & Typ-Registry

Der type ist der wichtigste Hebel im Knowledge Design. Er steuert nicht nur das Gewicht bei der Suche, sondern seit WP-06 auch, wann eine Notiz aktiv in den Chat geholt wird ("Strategic Retrieval") und seit WP-15, ob Smart Edges aktiviert sind.

3.1 Übersicht der Kern-Typen

Mindnet unterscheidet verschiedene Wissensarten. Wähle den Typ, der die Rolle der Notiz am besten beschreibt:

Typ Beschreibung & Einsatzzweck Rolle im Chat (Intent) Interview Schema (WP07) Matrix-Logik (WP11)
concept Fachbegriffe, Theorien. Zeitloses Wissen. FACT Titel, Definition, Tags Ziel für uses
project Ein Vorhaben mit Ziel, Dauer und Aufgaben. FACT / DECISION Ziel, Status, Stakeholder Quelle für uses, depends_on
experience Persönliche Erfahrung, Lektion oder Erkenntnis. EMPATHY Situation, Erkenntnis, Emotionen Quelle für based_on, derived_from
decision Eine bewusst getroffene Entscheidung (ADR). DECISION Kontext, Entscheidung, Alternativen Quelle für depends_on, caused_by
value Ein persönlicher Wert oder ein Prinzip. DECISION Definition, Anti-Beispiel Ziel für based_on
principle Handlungsleitlinie. DECISION Regel, Ausnahme Quelle für derived_from
goal Ein strategisches Ziel (kurz- oder langfristig). DECISION Zeitrahmen, KPIs, Werte Ziel für related_to
risk Ein identifiziertes Risiko oder eine Gefahr. DECISION Auswirkung, Wahrscheinlichkeit Quelle für blocks
belief Glaubenssatz / Überzeugung. EMPATHY Ursprung, Mantra -
person Eine reale Person (Netzwerk, Autor). FACT Rolle, Kontext -
journal Zeitbezogener Log-Eintrag, Daily Note. FACT Datum, Tags -
source Externe Quelle (Buch, PDF, Artikel). FACT Autor, URL -

3.2 Zusammenspiel mit types.yaml

Der type steuert im Hintergrund drei technische Mechanismen:

  1. retriever_weight (Wichtigkeit):
    • Ein concept (0.6) wiegt weniger als ein project (0.97) oder eine decision (1.0).
  2. chunk_profile (Textzerlegung):
    • journal (short): Wird fein zerlegt.
    • experience (sliding_smart_edges): Wird intelligent analysiert.
  3. enable_smart_edge_allocation (WP15):
    • Wenn true: Das System analysiert jeden Abschnitt mit KI, um zu prüfen, ob verlinkte Themen dort wirklich relevant sind. Das erhöht die Präzision massiv.

4. Edges & Referenzen in Notes

Um aus isolierten Dateien ein Netzwerk zu machen, nutzen wir Verlinkungen. In Version 2.2 sind diese Verlinkungen die Basis für den Hybrid Retriever (Suche über Nachbarn).

4.1 Wikilinks (Die Basis-Referenz)

Der klassische Obsidian-Link.

Wir nutzen [[Qdrant]] als Vektordatenbank.
  • Bedeutung: "Diese Notiz erwähnt Qdrant."
  • Edge-Typ: references

4.2 Inline-Relationen (Semantische Verknüpfung)

Dies ist die mächtigste Methode. Du sagst dem System explizit, wie Dinge zusammenhängen.

Daher [[rel:depends_on Qdrant]].
Dieses Konzept ist [[rel:similar_to Pinecone]].
  • Syntax: [[rel:RELATION ZIEL]].
  • Gültige Relationen:
    • depends_on: Hängt ab von / Benötigt. (Trigger für hohe Graph-Relevanz).
    • similar_to: Ähnelt / Ist vergleichbar mit.
    • related_to: Hat zu tun mit (allgemein).
    • caused_by: Wurde verursacht durch (Kausalität).
    • solves: Löst (Problem).
    • blocks: Blockiert oder gefährdet (z.B. Risiko -> Projekt).
    • derived_from: Stammt ab von (z.B. Prinzip -> Buch, Erfahrung -> Wert).
    • based_on: Basiert auf (Fundament).
    • uses: Nutzt (Werkzeug/Konzept).

4.3 Callout-Edges (Kuratierte Listen)

Für Zusammenfassungen oder "Siehe auch"-Blöcke am Ende einer Notiz.

> [!edge] related_to: [[Vector Embeddings]] [[AI Agents]]
  • Funktion: Erzeugt related_to-Kanten zu allen genannten Zielen in dieser Zeile.

5. Schreiben für den KI-Zwilling (New in v2.3/2.4)

Damit der RAG-Chat (WP05/06) nicht nur dumm Fakten wiedergibt, sondern dich berät, musst du "Futter" für die Decision Engine und das Empathie-Modul liefern.

5.1 Futter für die Decision Engine (DECISION)

Das System soll abwägen: "Passt Tool X zu mir?". Dazu muss es wissen, was "Du" bist.

Best Practice: Werte definieren Erstelle Notizen mit type: value.

---
type: value
title: Prinzip: Datensparsamkeit
---
# Prinzip: Datensparsamkeit
Wir speichern nur das Minimum an Daten. Cloud-Uploads persönlicher Daten sind verboten, es sei denn, sie sind E2E-verschlüsselt.

Best Practice: Ziele definieren Erstelle Notizen mit type: goal.

---
type: goal
title: Ziel: Unabhängigkeit 2026
---
# Ziel: Unabhängigkeit 2026
Bis Ende 2026 wollen wir alle SaaS-Abos durch Self-Hosted Lösungen ersetzt haben.

Effekt: Wenn du fragst "Soll ich Notion nutzen?", lädt die Engine diese beiden Notizen und antwortet: "Nein, Notion ist SaaS und nicht E2E-verschlüsselt. Das verletzt dein Prinzip der Datensparsamkeit und dein Ziel der Unabhängigkeit."

5.2 Futter für den Empathie-Modus (EMPATHY)

Das System soll dich verstehen, wenn du sagst: "Alles ist grau." Dazu braucht es deine Resonanzerfahrungen.

Best Practice: Erfahrungen & Bridging Erstelle Notizen mit type: experience. Nutze im Text emotionale Brückenwörter, damit der Retriever auch bei abstrakten Gefühlen ("grau") einen Treffer landet.

---
type: experience
title: Erfahrung: Der Durchbruch nach der Krise
tags: [krise, hoffnung, grau, angst]
---
# Erfahrung: Der Durchbruch nach der Krise
Es gibt Projektphasen, da wirkt alles **sinnlos** und **grau**.
Ich habe gelernt: Das ist oft das Zeichen kurz vor dem Durchbruch.
Mein Mantra in solchen Zeiten: "Einfach weitermachen, der Nebel lichtet sich."

Effekt: Wenn du im Chat jammerst ("Alles ist sinnlos"), findet das System diese Notiz und spiegelt dir deine eigene Erfahrung zurück.

5.3 Schreiben für den Chat (UI Optimization)

Da deine Notizen im Web-Interface (WP10) angezeigt werden:

  • Kurze Absätze: Das LLM liest besser, und der Mensch scannt schneller.
  • Klare Headings: Nutze H1/H2, um dem Chunker logische Trennlinien zu geben.

5.4 Der Interview-Modus (Auto-Drafting)

Seit v2.4 (WP07) kann Mindnet Notizen für dich entwerfen.

  • Wie: Schreibe im Chat einfach: "Ich möchte ein neues Projekt 'Alpha' anlegen, Ziel ist die Markteroberung."
  • Was passiert: Mindnet erkennt den Wunsch (INTERVIEW), wählt das Schema für project und generiert sofort einen Markdown-Entwurf.
  • Ergebnis: Du erhältst einen Code-Block mit status: draft. Diesen kannst du im Draft-Editor (UI) direkt bearbeiten und herunterladen.
  • Drafts: Enthalten oft Platzhalter [TODO]. Das ist Absicht. Ergänze sie im Editor.

5.5 Futter für das Risikomanagement (DECISION)

Damit Mindnet dich vor Fehlern warnen kann, musst du Risiken explizit machen.

Best Practice: Risiken definieren Erstelle Notizen mit type: risk. Nutze blocks oder related_to, um sie mit Projekten zu verknüpfen.

---
type: risk
title: Risiko: Vendor Lock-in bei Cloud-DBs
tags: [architektur, kosten, abhängigkeit]
---
# Risiko: Vendor Lock-in bei Cloud-DBs
Die Nutzung proprietärer Cloud-Datenbanken führt langfristig zu hohen Migrationskosten.
Dies [[rel:blocks Ziel Unabhängigkeit 2026]].

Effekt: Wenn du fragst "Soll ich AWS DynamoDB nutzen?", erkennt die Decision Engine den Konflikt mit deinem Ziel "Unabhängigkeit" durch die Kante blocks und den hohen retriever_weight des Risikos.

6. Best Practices & Beispiele (Klassik)

6.1 Beispiel: Projekt-Notiz

Projekte profitieren von depends_on, um Abhängigkeiten zu klären.

---
id: 20251115-proj-mindnet
title: Mindnet Implementierung
type: project
status: active
---

# Mindnet Implementierung

Wir bauen ein persönliches Wissensnetz.

## Tech Stack
Wir nutzen [[rel:depends_on Qdrant]] für die Vektorsuche und [[rel:depends_on FastAPI]] für das Backend.

## Architektur
Das Konzept basiert auf [[RAG Architecture]]. (Automatisch 'depends_on' durch Typ-Default).

6.2 Beispiel: Entscheidung (Decision Record)

Entscheidungen sind hoch gewichtet (retriever_weight: 1.0).

---
id: 20251120-adr-vektordb
title: ADR: Wahl von Qdrant
type: decision
status: final
tags: [architektur, db]
---

# Entscheidung: Qdrant

Wir haben uns für Qdrant entschieden.

## Alternativen
Wir haben auch [[rel:similar_to Pinecone]] und [[rel:similar_to Weaviate]] betrachtet.

## Begründung
Qdrant erlaubt lokalen Betrieb und [[rel:solves Payload Filtering Requirements]].

7. Langfristige Stabilität & Virtual Schema Layer

Mindnet ist auf Langlebigkeit ausgelegt.

7.1 Das "Virtual Schema" Prinzip

Wir vermeiden es, Logik in den Markdown-Dateien hart zu kodieren.

  • Statt in jeder Notiz zu schreiben chunk_size: 500, schreiben wir nur type: essay.
  • Wie groß ein Chunk für ein Essay ist, definieren wir in der Konfiguration (types.yaml).

7.2 Was bedeutet das für dich?

  • Du kannst dich auf den Inhalt konzentrieren.
  • Wenn wir in Zukunft basierend auf Feedback lernen, dass "Projekte" noch wichtiger sind, ändern wir eine Zeile in der Konfiguration, und das gesamte System passt sich beim nächsten Import an.