# 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.