Lars
4f2296b9b0
All checks were successful
Deploy mindnet to llm-node / deploy (push) Successful in 3s
266 lines
13 KiB
Markdown
266 lines
13 KiB
Markdown
---
|
|
doc_type: user_manual
|
|
audience: user, author
|
|
scope: vault, markdown, schema
|
|
status: active
|
|
version: 2.8.0
|
|
context: "Regelwerk für das Erstellen von Notizen im Vault. Die 'Source of Truth' für Autoren."
|
|
---
|
|
|
|
# Knowledge Design Manual
|
|
|
|
**Quellen:** `knowledge_design.md`, `types.yaml`
|
|
|
|
## ⚡ 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").
|
|
6. **Narrative Tiefe (Fleisch am Knochen):** Fakten allein reichen für Sessions und Biografien nicht aus. Erhalte die "Warum"-Ebene und Coach-Interpretationen. Die Erzählebene sichert, dass die KI die *Intention* versteht und der Mensch die *Bedeutung* nachvollziehen kann.
|
|
---
|
|
|
|
## 1. Zweck & Scope
|
|
|
|
Mindnet ist mehr als eine Dokumentablage. Es ist ein vernetztes System, das deine Persönlichkeit abbildet. Die Markdown-Dateien in deinem Vault sind die **einzige Quelle der Wahrheit** ("Source of Truth"). Was nicht im Markdown steht, existiert für das System nicht.
|
|
|
|
---
|
|
|
|
## 2. Note-Struktur & Frontmatter
|
|
|
|
Jede Notiz benötigt einen YAML-Header (Frontmatter).
|
|
|
|
**Pflichtfelder:**
|
|
|
|
```yaml
|
|
---
|
|
id: 20251212-projekt-alpha # Eindeutige Kennung (YYYYMMDD-slug empfohlen)
|
|
title: Projekt Alpha # Sprechender Titel
|
|
type: project # Steuert Chunking & Wichtigkeit
|
|
status: active # active, archived, draft
|
|
created: 2025-12-12 # ISO 8601
|
|
tags: [ki, entwicklung] # Taxonomie
|
|
aliases: [KI Projekt, Codename Quickhack]
|
|
---
|
|
```
|
|
|
|
### **2.1 [NEU] Naming Convention: Intuitiv vs. Technisch**
|
|
Für die Benutzerfreundlichkeit und die intuitive Navigation in Obsidian wird die Nutzung von **menschenlesbaren Titeln** bevorzugt (z. B. `Mein Persönliches Leitbild 2025` statt `leitbild_identity`).
|
|
- Die technische Eindeutigkeit wird primär über die `id` im Frontmatter sichergestellt.
|
|
- Die KI nutzt die Semantik des Dateinamens als zusätzlichen Kontext-Vektor.
|
|
|
|
|
|
|
|
### 2.3 Advanced Overrides: Die KI-Steuerung übernehmen
|
|
|
|
In 95% der Fälle setzt der `type` (z.B. "concept") automatisch die richtigen Einstellungen. In Spezialfällen kannst du diese manuell im Frontmatter überschreiben, um das Verhalten der KI zu erzwingen.
|
|
|
|
#### A. `retriever_weight`: Die Sichtbarkeit steuern
|
|
Dieser Faktor (Default: 1.0) ist ein Multiplikator für das Ranking in der Vektorsuche. Er entscheidet, welche Notiz "gewinnt", wenn zwei Texte inhaltlich ähnlich sind.
|
|
|
|
* **Standard (1.0):** Normale Wichtigkeit.
|
|
* **Boost (1.2 - 2.0):** "Das hier ist die Wahrheit."
|
|
* *Einsatz:* Finale Entscheidungen, Kernprinzipien, die "Single Source of Truth".
|
|
* *Effekt:* Verdrängt weniger wichtige Notizen (z.B. Meeting-Protokolle) aus dem Kontext-Fenster der KI.
|
|
* **Deboost (0.5 - 0.8):** "Nur Kontext, keine Fakten."
|
|
* *Einsatz:* Glossare, externe Quellen (`source`), reine Datensammlungen.
|
|
* *Effekt:* Die Notiz wird nur gefunden, wenn man sehr spezifisch danach sucht.
|
|
|
|
#### B. `chunking_profile`: Die Zerstückelung steuern
|
|
Das Profil bestimmt, wie der Text für die Datenbank zerschnitten wird. Falsches Chunking zerreißt den Kontext. Wähle das Profil basierend auf der **Struktur** deines Textes.
|
|
|
|
| Profil-Name | Strategie | Einsatzzweck & Wirkung |
|
|
| :--- | :--- | :--- |
|
|
| **`sliding_standard`** | Sliding Window | **Der Allrounder.** Für Fließtexte (Tagebuch, Artikel). Der Text wird in überlappende Fenster geschnitten. Gut, wenn der Inhalt von oben nach unten fließt. |
|
|
| **`sliding_short`** | Sliding Window (Klein) | **Für Dichte.** Für Texte mit sehr hoher Informationsdichte (Glossare, Task-Listen), wo jeder Satz wichtig ist. Erzeugt viele kleine Chunks. |
|
|
| **`sliding_smart_edges`** | Sliding + AI | **Der Intelligente.** Wie Standard, aber das LLM analysiert jeden Chunk zusätzlich auf implizite Querverweise. Standard für `concept` und `project`. |
|
|
| **`structured_smart_edges`** | Heading Split (Soft) | **Für Strukturierte Texte.** Trennt an Überschriften (H2). *Besonderheit:* Wenn ein Abschnitt sehr kurz ist, wird er mit dem nächsten verschmolzen ("Soft Mode"), um den Kontext zu wahren. |
|
|
| **`structured_smart_edges_strict`** | Heading Split (Hard) | **Für Listen & Kataloge.** Trennt *zwingend* an jeder H2-Überschrift. Verhindert das Verschmelzen. <br>**Wichtig für:** `decision` (Option A darf nicht mit Option B verschmelzen), `value`, `profile`. |
|
|
|
|
**Beispiel für ein Override:**
|
|
|
|
```yaml
|
|
---
|
|
title: Sammlung meiner Passwörter-Regeln
|
|
type: list
|
|
# Wir erzwingen eine strikte Trennung, damit Regel 1 nicht mit Regel 2 vermischt wird.
|
|
chunking_profile: structured_smart_edges_strict
|
|
# Extrem wichtig, soll immer beachtet werden.
|
|
retriever_weight: 1.5
|
|
---
|
|
```
|
|
|
|
---
|
|
## 3. Frontmatter Felder und ihre Bedeutung
|
|
### 3.1 Typ-Referenz & Verhalten
|
|
|
|
Wähle den Typ, der die **Rolle** der Notiz am besten beschreibt. Der Typ setzt die Defaults für die oben genannten Parameter.
|
|
|
|
| Typ | Default Profil | Default Gewicht | Einsatzzweck |
|
|
| :--- | :--- | :--- | :--- |
|
|
| **`concept`** | `sliding_smart_edges` | 0.60 | Fachbegriffe, Theorien. Zeitloses Wissen. |
|
|
| **`project`** | `sliding_smart_edges` | 0.97 | Aktive Vorhaben mit Ziel und Status. |
|
|
| **`experience`**| `sliding_smart_edges` | **1.10 [NEU]** | Biografische Lektionen & Prägungen. |
|
|
| **`insight` [NEU]** | `sliding_smart_edges` | **1.20** | Konkrete Beobachtungen/Erkenntnisse (z.B. Erziehung). |
|
|
| **`trait` [NEU]** | `structured_..._strict`| **1.10** | Persönliche Eigenschaften & Potenziale. |
|
|
| **`obstacle` [NEU]**| `structured_..._strict`| **1.00** | Ängste, Blockaden & Hindernisse. |
|
|
| **`decision`** | **`structured_..._strict`** | **1.00** | Entscheidungen. Muss atomar getrennt sein (Optionen vs. Ergebnis). |
|
|
| **`value`** | **`structured_..._strict`** | **1.00** | Werte/Prinzipien. |
|
|
| **`principle`**| `structured_..._strict_L3`| 0.95 | Handlungsleitlinien (Trennt bis Ebene H3). |
|
|
| **`goal`** | `sliding_smart_edges` | 0.95 | Strategische Ziele (Nordsterne). |
|
|
| **`risk`** | `sliding_short` | 0.85 | Risiken (kurz und prägnant). |
|
|
| **`journal`** | `sliding_standard` | 0.80 | Zeitbezogene Logs. |
|
|
| **`source`** | `sliding_standard` | 0.50 | Externe Quellen (niedrig gewichtet). |
|
|
|
|
### 3.2 Status und Bedeutung
|
|
|
|
| Status | Bedeutung | Auswirkung auf die KI |
|
|
| :--- | :--- | :--- |
|
|
| **`stable`** | **Geprüftes Wissen.** Die Notiz ist inhaltlich korrekt, finalisiert und verlässlich (Gold-Standard). | **🚀 Bevorzugt (Bonus):** Die KI vertraut diesen Inhalten mehr (+20% Relevanz-Score). Bei widersprüchlichen Infos gewinnt `stable`. |
|
|
| **`active`** | **Standard.** Aktuelle Arbeitsnotizen, Projekte oder Dokumentationen (Default, wenn leer). | **🔵 Neutral:** Standard-Gewichtung (Faktor 1.0). |
|
|
| **`draft`** | **Entwurf.** Brainstorming, unstrukturierte Mitschriften oder rohe Ideen. | **🔻 Gedämpft (Malus):** Die KI nutzt diese Infos nur, wenn es keine besseren Treffer gibt (Relevanz auf 50% reduziert). Reduziert "Rauschen" in den Antworten. |
|
|
| **`system`** | **Intern.** Konfigurationsdateien, technische Logs oder Admin-Skripte. | **❌ Ignoriert (Hard Skip):** Die Datei wird **nicht** in den Suchindex aufgenommen und ist für den Chat unsichtbar. |
|
|
| **`template`**| **Vorlage.** Leere Gerüste für neue Notizen (z.B. für Obsidian). | **❌ Ignoriert (Hard Skip):** Verhindert, dass leere Vorlagen als Suchergebnisse auftauchen. |
|
|
|
|
### Wann nutze ich welchen Status?
|
|
|
|
1. **Ideenfindung:** Setzen Sie neue Ideen immer auf **`draft`**. So können Sie frei schreiben, ohne dass die KI sofort "Halbwissen" als Fakten verkauft.
|
|
2. **Finalisierung:** Sobald eine Entscheidung getroffen oder ein Konzept fertig ist, ändern Sie den Status auf **`stable`**.
|
|
3. **Konfiguration:** Nutzen Sie **`system`** für Dateien wie die `01_edge_vocabulary.md`, damit die KI nicht die Definition der Kanten zitiert, wenn Sie eigentlich nach Inhalten suchen.
|
|
---
|
|
|
|
## 4. Edges & Verlinkung
|
|
|
|
Mindnet versteht Zusammenhänge durch Kanten.
|
|
|
|
### 4.1 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]]."
|
|
|
|
**Gültige Relationen:**
|
|
* `depends_on`: Hängt ab von / Benötigt.
|
|
* `blocks`: Blockiert oder gefährdet (z.B. Risiko -> Projekt).
|
|
* `caused_by`: Wurde verursacht durch (Kausalität).
|
|
* `similar_to`: Ähnelt / Ist vergleichbar mit.
|
|
* `solves`: Löst (Problem).
|
|
* `based_on`: Basiert auf (Fundament).
|
|
* **`prev` / `next` [NEU]**: Markiert chronologische oder evolutionäre Abfolgen (z.B. Leitbild-Evolution).
|
|
|
|
### 4.2 Callout-Edges
|
|
Für Zusammenfassungen am Ende einer Notiz:
|
|
|
|
```markdown
|
|
> [!edge] related_to: [[Vector Embeddings]] [[AI Agents]]
|
|
```
|
|
|
|
### 4.3 Implizite Bidirektionalität (Edger-Logik) [NEU] [PRÜFEN!]
|
|
In Mindnet musst du Kanten **nicht** manuell in beide Richtungen pflegen. Der **Edger** übernimmt die Paarbildung automatisch im Hintergrund.
|
|
|
|
**Deine Aufgabe:** Setze die Kante in der Datei, die du gerade bearbeitest, so wie es der **logische Fluss** vorgibt.
|
|
|
|
* **Blick zurück (Rückwärtslink):** Wenn du ein Ergebnis dokumentierst, nutze `derived_from`, `based_on` oder `prev`.
|
|
* **Blick nach vorn (Vorwärtslink):** Wenn du einen Plan oder ein Protokoll schreibst, nutze `resulted_in`, `supports` oder `next`.
|
|
|
|
**System-Logik (Beispiele):**
|
|
- Schreibst du in Note A: `next: [[B]]`, weiß das System automatisch: `B prev A`.
|
|
- Schreibst du in Note B: `derived_from: [[A]]`, weiß das System automatisch: `A resulted_in B`.
|
|
|
|
**Vorteil:** Keine redundante Datenpflege, kein "Link-Nightmare", volle Konsistenz im Graphen.
|
|
|
|
---
|
|
|
|
## 5. Schreiben für den KI-Zwilling (Szenarien)
|
|
|
|
Damit der **RAG-Chat** dich berät, musst du "Futter" für die Decision Engine liefern.
|
|
|
|
### Szenario A: Decision Engine (`DECISION`)
|
|
* **Ziel:** Das System soll abwägen: "Passt Tool X zu mir?"
|
|
* **Vorgehen:** Erstelle Notizen mit `type: value` oder `type: goal`.
|
|
|
|
* **Effekt:** Wenn du fragst "Soll ich Notion nutzen?", lädt die Engine diese Notiz und antwortet: *"Nein, Notion ist SaaS ohne E2E. Das verletzt dein Prinzip der Datensparsamkeit."*
|
|
|
|
### Szenario B: Empathie (`EMPATHY`)
|
|
* **Ziel:** Das System soll dich verstehen.
|
|
* **Vorgehen:** Erstelle `type: experience` mit **emotionalen Brückenwörtern**.
|
|
|
|
**Beispiel Notiz:**
|
|
```yaml
|
|
---
|
|
type: experience
|
|
title: Erfahrung: Der Durchbruch nach der Krise
|
|
tags: [krise, hoffnung, grau, angst]
|
|
---
|
|
Es gibt Projektphasen, da wirkt alles **sinnlos** und **grau**.
|
|
Ich habe gelernt: Das ist oft das Zeichen kurz vor dem Durchbruch.
|
|
```
|
|
* **Effekt:** Bei "Alles ist grau" findet das System diese Notiz und spiegelt die Lektion zurück.
|
|
|
|
### **Szenario C: Forward-Mapping (Lücken-Analyse) [NEU]**
|
|
* **Ziel:** Strategische Wissenslücken füllen.
|
|
* **Vorgehen:** Erstelle Hub-Notizen mit Forward-Links auf noch nicht existierende Dateien (z. B. `[[Besten Version meiner Selbst]]`).
|
|
* **Effekt:** Das System erkennt die semantische Bedeutung des geplanten Wissens und kann proaktiv Fragen stellen, um diese Lücken zu schließen.
|
|
|
|
### **Szenario D: Narratives Gedächtnis (Intention) [NEU]**
|
|
* **Ziel:** Das System soll verstehen, *warum* eine Entscheidung getroffen wurde, um in ähnlichen künftigen Situationen konsistent zu beraten.
|
|
* **Vorgehen:** Nutze in `journal`- oder `experience`-Notizen Abschnitte für "Hintergrund" und "Interpretation".
|
|
* **Beispiel:** Statt "Wert: Disziplin" schreibe "Ich wähle Disziplin, weil ich in meiner Kindheit erlebt habe, wie Willkür schadet."
|
|
* **Effekt:** Die KI spiegelt nicht nur die Regel, sondern die Überzeugung dahinter.
|
|
---
|
|
|
|
## 6. Best Practices & Beispiele
|
|
|
|
### 6.1 Beispiel: Projekt-Notiz (Standard)
|
|
Projekte profitieren von `depends_on`, um Abhängigkeiten zu klären.
|
|
|
|
```markdown
|
|
---
|
|
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]].
|
|
```
|
|
|
|
### 6.2 Beispiel: Advanced Tuning (Manuelles Override)
|
|
Hier zwingen wir das System, eine Entscheidung extrem kleinteilig (`strict`) zu zerlegen und in der Suche maximal zu priorisieren.
|
|
|
|
```markdown
|
|
---
|
|
id: 20251120-adr-vektordb
|
|
title: ADR: Wahl von Qdrant
|
|
type: decision
|
|
status: final
|
|
tags: [architektur, db]
|
|
chunking_profile: structured_smart_edges_strict
|
|
retriever_weight: 1.5
|
|
---
|
|
|
|
# Entscheidung: Qdrant
|
|
|
|
Wir haben uns für Qdrant entschieden.
|
|
|
|
## Alternativen
|
|
Wir haben auch [[rel:similar_to Pinecone]] und [[rel:similar_to Weaviate]] betrachtet.
|
|
```
|
|
|
|
---
|
|
|
|
## 7. Virtual Schema Layer
|
|
|
|
Grundsätzlich gilt das Prinzip des **Virtual Schema Layers**. Die Logik (wie `chunk_size`) wird zentral in der `types.yaml` verwaltet.
|
|
**Aber:** Als Power-User hast du über die Overrides jederzeit die Möglichkeit, aus diesem Standard auszubrechen. |