270 lines
12 KiB
Markdown
270 lines
12 KiB
Markdown
# mindnet v2.4 – Knowledge Design Manual
|
||
**Datei:** `docs/mindnet_knowledge_design_manual_v2.4.md`
|
||
**Stand:** 2025-12-10
|
||
**Status:** **FINAL** (Integrierter Stand WP01–WP10a)
|
||
**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.3.1 verfügt Mindnet über:
|
||
* **Hybrid Router:** Das System erkennt, ob du Fakten, Entscheidungen oder Empathie brauchst.
|
||
* **Context Intelligence:** Das System lädt je nach Situation unterschiedliche Notiz-Typen (z.B. Werte bei Entscheidungen).
|
||
* **Web UI (WP10):** Du kannst direkt sehen, welche Quellen genutzt wurden.
|
||
* **Interview Modus (WP07):** Du kannst Notizen direkt im Chat entwerfen lassen.
|
||
|
||
### 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 für die Suche
|
||
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-hash` (z. B. `20231027-vektor-db-a1b2`). 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 **welche Felder** im Interview abgefragt werden.
|
||
|
||
### 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) |
|
||
| :--- | :--- | :--- | :--- |
|
||
| **`concept`** | Fachbegriffe, Theorien. Zeitloses Wissen. | **FACT** | Titel, Definition, Tags |
|
||
| **`project`** | Ein Vorhaben mit Ziel, Dauer und Aufgaben. | **FACT / DECISION** | Ziel, Status, Stakeholder, Steps |
|
||
| **`experience`** | Persönliche Erfahrung, Lektion oder Erkenntnis. | **EMPATHY** | Situation, Erkenntnis, Emotionen |
|
||
| **`decision`** | Eine bewusst getroffene Entscheidung (ADR). | **DECISION** | Kontext, Entscheidung, Alternativen |
|
||
| **`value`** | Ein persönlicher Wert oder ein Prinzip. | **DECISION** | Definition, Anti-Beispiel |
|
||
| **`goal`** | Ein strategisches Ziel (kurz- oder langfristig). | **DECISION** | Zeitrahmen, KPIs, Werte |
|
||
| **`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).
|
||
* **Warum?** Bei einer Suche nach "Datenbank" soll Mindnet bevorzugt deine *Entscheidung* ("Warum wir X nutzen") anzeigen.
|
||
2. **`chunk_profile` (Textzerlegung):**
|
||
* `journal` (short): Wird fein zerlegt.
|
||
* `project` (long): Längere Kontext-Fenster.
|
||
3. **`edge_defaults` (Automatische Vernetzung):**
|
||
* Mindnet ergänzt automatisch Kanten.
|
||
* Beispiel: Ein Link in einem `project` wird automatisch als `depends_on` (Abhängigkeit) interpretiert.
|
||
|
||
---
|
||
|
||
## 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.
|
||
* `solves`: Löst (Problem).
|
||
|
||
### 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)
|
||
|
||
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.
|
||
|
||
---
|
||
|
||
## 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 (WP08) 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. |