From c56a31c6bce8c1bc234d8fabe66c4290f106ab45 Mon Sep 17 00:00:00 2001 From: Lars Date: Sun, 7 Dec 2025 11:52:09 +0100 Subject: [PATCH] =?UTF-8?q?docs/Knowledge=5FDesign=5FManual.md=20hinzugef?= =?UTF-8?q?=C3=BCgt?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/Knowledge_Design_Manual.md | 214 ++++++++++++++++++++++++++++++++ 1 file changed, 214 insertions(+) create mode 100644 docs/Knowledge_Design_Manual.md diff --git a/docs/Knowledge_Design_Manual.md b/docs/Knowledge_Design_Manual.md new file mode 100644 index 0000000..3578e6e --- /dev/null +++ b/docs/Knowledge_Design_Manual.md @@ -0,0 +1,214 @@ +# mindnet v2.2 – Knowledge Design Manual +**Datei:** `docs/mindnet_knowledge_design_manual_v2.2.md` +**Stand:** 2025-12-07 +**Status:** **FINAL** (Konsolidiert aus WP01–WP04a) +**Quellen:** `knowledge_design.md`, `TYPE_REGISTRY_MANUAL.md`, `chunking_strategy.md`, `mindnet_functional_architecture.md`, `WP03/WP04 Hinweise`. + +--- + +## 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. Damit der **Retriever** (die Suchmaschine) und spätere **KI-Agenten** dieses Wissen nutzen können, müssen Notizen einer klaren Struktur folgen. + +### 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 + title: Projekt Alpha # Sprechender Titel (wird in Suchergebnissen angezeigt) + type: project # Steuert Verarbeitung & Vernetzung (siehe Kap. 3) + status: active # Status (z.B. draft, active, archived) + 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). + +### 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 verknüpft die Notiz mit der Konfiguration in `config/types.yaml`. + +### 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 | +| :--- | :--- | +| **`concept`** | Fachbegriffe, Theorien, Modelle. Zeitloses Wissen. (z. B. "Vektordatenbank") | +| **`project`** | Ein Vorhaben mit Ziel, Dauer und Aufgaben. (z. B. "Aufbau Homelab") | +| **`experience`** | Persönliche Erfahrung, Lektion oder Erkenntnis. (z. B. "Learning: Docker Networking") | +| **`decision`** | Eine bewusst getroffene Entscheidung inkl. Alternativen und Begründung. (z. B. "ADR-001: Nutzung von Qdrant") | +| **`value`** | Ein persönlicher Wert oder ein Prinzip. (z. B. "Datensparsamkeit") | +| **`person`** | Eine reale Person (Netzwerk, Autor). | +| **`event`** | Ein Ereignis (Konferenz, Meeting). | +| **`journal`** | Zeitbezogener Log-Eintrag, Daily Note. | +| **`source`** | Externe Quelle (Buch, PDF, Artikel), die exzerpiert wird. | + +### 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). + * Ziel: Mindnet soll bei Fragen eher *deine Entscheidungen* und *Projekte* finden als reine Definitionen. +2. **`chunk_profile` (Textzerlegung):** + * `journal` (short): Wird fein zerlegt, da sich Themen schnell ändern. + * `concept` (medium): Standard-Absätze. + * `project` (long): Längere Kontext-Fenster, um Zusammenhänge zu wahren. +3. **`edge_defaults` (Automatische Vernetzung):** + * Mindnet ergänzt automatisch Kanten. + * Beispiel: Ein Link in einem `project` wird automatisch als `depends_on` (Abhängigkeit) interpretiert, sofern nicht anders angegeben. + +--- + +## 4. Edges & Referenzen in Notes + +Um aus isolierten Dateien ein **Netzwerk** zu machen, nutzen wir Verlinkungen. Mindnet v2.2 (WP03) bietet hierfür präzise Werkzeuge. + +### 4.1 Wikilinks (Die Basis-Referenz) +Der klassische Obsidian-Link. + + Wir nutzen [[Qdrant]] als Vektordatenbank. + +* **Bedeutung:** "Diese Notiz erwähnt Qdrant." +* **Edge-Typ:** `references` +* **Confidence:** 1.0 + +### 4.2 Inline-Relationen (Semantische Verknüpfung) +Wenn du ausdrücken willst, **wie** Dinge zusammenhängen. Dies ist essenziell für die Erklärbarkeit ("Warum ist das relevant?"). + + Daher [[rel:depends_on Qdrant]]. + Dieses Konzept ist [[rel:similar_to Pinecone]]. + +* **Syntax:** `[[rel:RELATION ZIEL]]`. (Wichtig: Das `rel:` Präfix steht *innerhalb* der Klammer). +* **Gültige Relationen:** + * `depends_on`: Hängt ab von / Benötigt. + * `similar_to`: Ähnelt / Ist vergleichbar mit. + * `related_to`: Hat zu tun mit (allgemein). + * `caused_by`: Wurde verursacht durch. + * `solves`: Löst (Problem). + * `implements`: Setzt um (Konzept). +* **Nicht unterstützt:** `rel: depends_on [[Ziel]]` (alte Syntax, funktioniert nicht mehr!). + +### 4.3 Callout-Edges (Kuratierte Listen) +Für Zusammenfassungen oder "Siehe auch"-Blöcke am Ende einer Notiz, die nicht im Fließtext stehen sollen. + + > [!edge] related_to: [[Vector Embeddings]] [[AI Agents]] + +* **Funktion:** Erzeugt `related_to`-Kanten zu allen genannten Zielen in dieser Zeile. +* **Nutzen:** Erlaubt schnelle Listenpflege ohne den Textfluss zu stören. + +### 4.4 Strukturkanten (Automatisch) +Diese musst du nicht schreiben, sie entstehen automatisch: +* `belongs_to`: Verknüpft jeden Textabschnitt (Chunk) mit seiner Ursprungsnotiz. +* `next` / `prev`: Verknüpft Absätze in Lesereihenfolge (ermöglicht Agenten das "Weiterlesen"). +* `has_part` / `part_of`: (Zukünftig) Basierend auf Ordnerstrukturen. + +--- + +## 5. Best Practices & Beispiele + +### 5.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). + +### 5.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]]. + +### 5.3 Typische Anti-Patterns (Bitte vermeiden!) + +1. **Der "Alles"-Zettel:** Eine Notiz "Ideen 2025", die 50 verschiedene Themen enthält. + * *Besser:* Atomare Notizen ("Idee A", "Idee B") erstellen und verlinken. +2. **Manuelle Gewichtung:** `retriever_weight: 0.9` im Frontmatter setzen. + * *Problem:* Wenn du das System tunen willst, musst du hunderte Dateien ändern. + * *Besser:* Den `type` korrekt setzen und das Gewicht zentral in `types.yaml` steuern. +3. **Link-Wüsten:** Eine Notiz, die nur aus einer Liste von 100 Links besteht ohne Text. + * *Problem:* Der Vektor-Sucher findet keinen kontextuellen "Anker" (Text). + * *Besser:* Kurze Beschreibung zu jedem Link hinzufügen. + +--- + +## 6. Langfristige Stabilität & Virtual Schema Layer + +Mindnet ist auf Langlebigkeit ausgelegt. + +### 6.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`). + +### 6.2 Was bedeutet das für dich? +* Du kannst dich auf den Inhalt konzentrieren. +* Wenn wir in Zukunft entscheiden, dass "Projekte" stärker gewichtet werden sollen, ändern wir **eine Zeile** in der Konfiguration, und das gesamte System passt sich beim nächsten Import an. +* Deine Notizen bleiben sauber und zukunftssicher. \ No newline at end of file