2025-12-07 11:52:09 +01:00
# mindnet v2.2 –
**Datei:** `docs/mindnet_knowledge_design_manual_v2.2.md`
2025-12-08 16:14:52 +01:00
**Stand:** 2025-12-08
**Status:** **FINAL** (Integrierter Stand WP01–
**Quellen:** `knowledge_design.md` , `TYPE_REGISTRY_MANUAL.md` , `chunking_strategy.md` , `mindnet_functional_architecture.md` .
2025-12-07 11:52:09 +01:00
---
## 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
2025-12-08 16:14:52 +01:00
Mindnet ist mehr als eine Dokumentablage. Es ist ein vernetztes System, das deine Persönlichkeit, Entscheidungen und Erfahrungen abbildet.
Seit Version 2.2 verfügt Mindnet über:
* **Explanation Engine:** Das System erklärt, warum es Notizen findet (über Edges).
* **RAG-Chat (KI-Zwilling):** Das System antwortet in natürlicher Sprache. **Wie** du schreibst, bestimmt, **wie schlau** die KI antwortet.
2025-12-07 11:52:09 +01:00
### 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
2025-12-08 16:14:52 +01:00
> **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.
2025-12-07 11:52:09 +01:00
### 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:
2025-12-08 16:14:52 +01:00
| Typ | Beschreibung & Einsatzzweck | Wichtigkeit für Chat |
| :--- | :--- | :--- |
| ** `concept` ** | Fachbegriffe, Theorien. Zeitloses Wissen. | Mittel (Basiswissen) |
| ** `project` ** | Ein Vorhaben mit Ziel, Dauer und Aufgaben. | Hoch (Kontext) |
| ** `experience` ** | Persönliche Erfahrung, Lektion oder Erkenntnis. | Sehr Hoch (Persönlichkeit) |
| ** `decision` ** | Eine bewusst getroffene Entscheidung (ADR). | **Kritisch** (Begründung "Warum") |
| ** `value` ** | Ein persönlicher Wert oder ein Prinzip. | **Kritisch** (Moralischer Kompass) |
| ** `person` ** | Eine reale Person (Netzwerk, Autor). | Niedrig |
| ** `journal` ** | Zeitbezogener Log-Eintrag, Daily Note. | Mittel (Historie) |
| ** `source` ** | Externe Quelle (Buch, PDF, Artikel). | Niedrig (Faktenbasis) |
2025-12-07 11:52:09 +01:00
### 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).
2025-12-08 16:14:52 +01:00
* **Warum?** Bei einer Suche nach "Datenbank" soll Mindnet bevorzugt deine *Entscheidung* ("Warum wir X nutzen") anzeigen.
2025-12-07 11:52:09 +01:00
2. ** `chunk_profile` (Textzerlegung):**
2025-12-08 16:14:52 +01:00
* `journal` (short): Wird fein zerlegt.
* `project` (long): Längere Kontext-Fenster.
2025-12-07 11:52:09 +01:00
3. ** `edge_defaults` (Automatische Vernetzung):**
* Mindnet ergänzt automatisch Kanten.
2025-12-08 16:14:52 +01:00
* Beispiel: Ein Link in einem `project` wird automatisch als `depends_on` (Abhängigkeit) interpretiert.
2025-12-07 11:52:09 +01:00
---
## 4. Edges & Referenzen in Notes
2025-12-08 16:14:52 +01:00
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).
2025-12-07 11:52:09 +01:00
### 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)
2025-12-08 16:14:52 +01:00
Dies ist die **mächtigste** Methode. Du sagst dem System explizit, **wie** Dinge zusammenhängen.
2025-12-07 11:52:09 +01:00
Daher [[rel:depends_on Qdrant]].
Dieses Konzept ist [[rel:similar_to Pinecone]].
2025-12-08 16:14:52 +01:00
* **Syntax:** `[[rel:RELATION ZIEL]]` .
2025-12-07 11:52:09 +01:00
* **Gültige Relationen:**
2025-12-08 16:14:52 +01:00
* `depends_on` : Hängt ab von / Benötigt. (Trigger für hohe Graph-Relevanz).
2025-12-07 11:52:09 +01:00
* `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)
2025-12-08 16:14:52 +01:00
Für Zusammenfassungen oder "Siehe auch"-Blöcke am Ende einer Notiz.
2025-12-07 11:52:09 +01:00
> [!edge] related_to: [[Vector Embeddings]] [[AI Agents]]
* **Funktion:** Erzeugt `related_to` -Kanten zu allen genannten Zielen in dieser Zeile.
---
## 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]].
---
## 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.
2025-12-08 16:14:52 +01:00
* 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.
---
## 7. Schreiben für den KI-Zwilling (New in v2.2)
Damit der **RAG-Chat (WP05)** gute Antworten liefert, beachte diese Regeln:
1. **Atomare Konzepte:**
* Der Chatbot baut seine Antwort aus mehreren kleinen Text-Stücken ("Chunks") zusammen.
* Schreibe so, dass ein Absatz auch für sich allein verständlich ist.
2. **Explizite Entscheidungen:**
* Wenn du eine Meinung hast ("Tool X ist schlecht"), schreibe sie nicht in einen Nebensatz.
* Erstelle eine Notiz `type: experience` oder `decision` ("Warum Tool X nicht geeignet ist").
* Die KI sucht gezielt nach `[DECISION]` -Typen, um "Warum"-Fragen zu beantworten.
3. **Werte definieren:**
* Erstelle Notizen mit `type: value` (z.B. "Datenschutz First").
* Die KI nutzt diese, um bei Konflikten ("Soll ich Cloud oder Lokal nutzen?") in deinem Sinne zu argumentieren.
4. **Verlinken ist Pflicht:**
* Der Chatbot nutzt **Hybrid Search** . Er findet Notizen nur, wenn sie über Kanten verbunden sind.
* Eine isolierte Notiz (ohne Links) ist für die KI fast unsichtbar.
