neue Dokumentationstruktur - (QS geprüft)
Deploy mindnet to llm-node / deploy (push) Successful in 4s

This commit is contained in:
Lars committed 2025-12-13 18:38:37 +01:00
1 parent 0bb5f57cc6
commit 620858a575
39 files changed
+1840

No files matched your search

+111
View File
@@ -0,0 +1,111 @@
---
doc_type: user_manual
audience: user, mindmaster
scope: chat, ui, feedback
status: active
version: 2.6
context: "Anleitung zur Nutzung der Web-Oberfläche, der Chat-Personas und des Feedbacks."
---
# Chat Usage Guide
**Quellen:** `user_guide.md`
## 1. Was Mindnet für dich tut
Mindnet ist ein **assoziatives Gedächtnis** mit Persönlichkeit. Es unterscheidet sich von einer reinen Suche dadurch, dass es **kontextsensitiv** agiert.
**Das Gedächtnis (Der Graph):**
Wenn du nach "Projekt Alpha" suchst, findet Mindnet auch:
* **Abhängigkeiten:** "Technologie X wird benötigt".
* **Entscheidungen:** "Warum nutzen wir X?".
* **Ähnliches:** "Projekt Beta war ähnlich".
**Der Zwilling (Die Personas):**
Mindnet passt seinen Charakter an: Mal ist es der neutrale Bibliothekar, mal der strategische Berater, mal der empathische Spiegel.
---
## 2. Die Oberfläche (Web UI)
Seit Version 2.3.1 bedienst du Mindnet über eine grafische Oberfläche im Browser.
### 2.1 Der Chat-Bereich
* **Intent-Badge:** Über jeder Antwort siehst du ein Label (z.B. **⚖️ Intent: DECISION**).
* **Quellen-Karten:** Unter der Antwort findest du ausklappbare Karten ("Expanders").
* **Grüner Punkt:** Hohe Relevanz (Score > 0.8).
* **Klick darauf:** Zeigt den Textauszug und die **Begründung** (Explanation Layer).
### 2.2 Die Sidebar
* **Modus-Wahl:** Umschalten zwischen "💬 Chat" und "📝 Manueller Editor".
* *Feature:* Der Editor nutzt ein "Resurrection Pattern" – deine Eingaben bleiben erhalten, auch wenn du den Tab wechselst.
* **Settings:** Hier kannst du `Top-K` (Anzahl der Quellen) und `Explanation Layer` steuern.
---
## 3. Den Chat steuern (Intents)
Du steuerst die Persönlichkeit von Mindnet durch deine Wortwahl. Der **Hybrid Router v5** unterscheidet intelligent:
### 3.1 Frage-Modus (Wissen abrufen)
Ausgelöst durch `?` oder W-Wörter.
* **Entscheidung ("Soll ich?"):** Der **Berater**.
* Mindnet lädt deine Werte (`type: value`) und Ziele (`type: goal`).
* *Beispiel:* "Soll ich Tool X nutzen?" -> "Nein, Tool X speichert Daten in den USA. Das verstößt gegen dein Prinzip 'Privacy First'."
* **Empathie ("Ich fühle..."):** Der **Spiegel**.
* Mindnet lädt deine Erfahrungen (`type: experience`).
* *Beispiel:* "Ich bin frustriert." -> "Das erinnert mich an Projekt Y, da ging es uns ähnlich..."
* **Fakten ("Was ist?"):** Der **Bibliothekar**.
* Liefert präzise Definitionen.
### 3.2 Befehls-Modus (Interview)
Ausgelöst durch Aussagen wie "Neues Projekt", "Ich will festhalten".
* **Was passiert:** Mindnet sucht nicht, sondern öffnet den **Draft-Editor**.
* **Beispiel:** "Neue Erfahrung: Streit am Recyclinghof." -> Das System erstellt sofort eine strukturierte Notiz mit den Feldern "Situation", "Reaktion" und "Learning".
---
## 4. Ergebnisse interpretieren (Explanation Layer)
Mindnet liefert eine **Begründung** ("Reasons"), warum es etwas gefunden hat.
Öffne eine Quellen-Karte, um zu sehen:
* *"Hohe textuelle Übereinstimmung."* (Semantik)
* *"Bevorzugt aufgrund des Typs 'decision'."* (Wichtigkeit)
* *"Verweist auf 'Projekt X' via 'depends_on'."* (Graph-Kontext)
---
## 5. Feedback & Lernen
Mindnet wird schlauer, wenn du es pflegst.
* **Globales Feedback (Sterne):** Bewertet die generierte Antwort (Prompting, Tonfall).
* **Granulares Feedback (Smileys):** Bewertet die einzelne Quelle.
* 😞 (Sad): Irrelevant. (Senkt das Gewicht dieser Verbindung).
* 😀 (Grin): Perfekter Treffer! (Stärkt diesen Typ/Kante).
---
## 6. Neues Wissen beisteuern (Authoring & Intelligence)
Mindnet lebt von deinem Input. Du hast drei Wege, Wissen einzugeben:
### 6.1 Weg A: Der Interview-Assistent (Auto-Drafting)
1. **Start:** Schreibe im Chat: *"Ich möchte ein neues Projekt 'Apollo' starten."*
2. **Generierung:** Mindnet erkennt `INTERVIEW`, wählt das Schema und erstellt einen Entwurf.
3. **Editor:** Die UI zeigt den Entwurf (`status: draft`).
* *Healing UI:* Falls das LLM Syntax-Fehler gemacht hat, hat der Editor sie bereits repariert.
4. **Speichern:** Klicke auf "💾 Speichern".
### 6.2 Weg B: Der Intelligence-Workflow
Wenn du im **manuellen Editor** schreibst, unterstützt dich Mindnet aktiv bei der Vernetzung:
1. **Schreiben:** Tippe deinen Text im Tab **"✏️ Inhalt"**.
2. **Analysieren:** Wechsle zum Tab **"🧠 Intelligence"** und klicke auf **"🔍 Analyse starten"**. Das System scannt deinen Text (Vektor-Suche & Exact Match).
3. **Vorschläge nutzen:**
* **Exakte Treffer:** Das System erkennt Begriffe wie "KI-Gedächtnis" als Alias für "Mindnet".
* **Semantische Treffer:** Das System findet inhaltlich verwandte Notizen.
* **Klick auf "➕ Einfügen":** Fügt den Link (z.B. `[[rel:related_to Mindnet]]`) an der Cursor-Position ein.
4. **Speichern:** Der Text wird sofort in den Vault geschrieben und indiziert.
+192
View File
@@ -0,0 +1,192 @@
---
doc_type: user_manual
audience: user, author
scope: vault, markdown, schema
status: active
version: 2.6
context: "Regelwerk für das Erstellen von Notizen im Vault. Die 'Source of Truth' für Autoren."
---
# Knowledge Design Manual
**Quellen:** `knowledge_design.md`, `TYPE_REGISTRY_MANUAL.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").
---
## 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
---
```
**Optionale Felder:**
* `aliases`: [Alpha Projekt] – Wichtig für "Active Intelligence" (Exact Match).
* `visibility`: internal (default) / public.
> **Wichtig:** Felder wie `retriever_weight` oder `chunk_profile` werden zentral über `types.yaml` gesteuert und müssen nicht mehr manuell gesetzt werden (Virtual Schema Layer).
---
## 3. Typ-Referenz & Verhalten
Wähle den Typ, der die **Rolle** der Notiz am besten beschreibt. Der Typ steuert Chunking, Gewichtung und Kanten-Logik.
| Typ | Beschreibung & Einsatzzweck | Rolle im Chat (Intent) | Matrix-Logik |
| :--- | :--- | :--- | :--- |
| **`concept`** | Fachbegriffe, Theorien. Zeitloses Wissen. | **FACT** | Ziel für `uses` |
| **`project`** | Ein Vorhaben mit Ziel, Dauer und Aufgaben. | **FACT / DECISION** | Quelle für `depends_on` |
| **`experience`** | Persönliche Erfahrung, Lektion oder Erkenntnis. | **EMPATHY** | Quelle für `based_on` |
| **`decision`** | Eine bewusst getroffene Entscheidung (ADR). | **DECISION** | Quelle für `caused_by` |
| **`value`** | Ein persönlicher Wert oder ein Prinzip. | **DECISION** | Ziel für `based_on` |
| **`principle`** | Handlungsleitlinie. | **DECISION** | Quelle für `derived_from` |
| **`goal`** | Ein strategisches Ziel. | **DECISION** | Ziel für `related_to` |
| **`risk`** | Ein identifiziertes Risiko. | **DECISION** | Quelle für `blocks` |
| **`journal`** | Zeitbezogener Log-Eintrag. | **FACT** | - |
---
## 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).
### 4.2 Callout-Edges
Für Zusammenfassungen am Ende einer Notiz:
```markdown
> [!edge] related_to: [[Vector Embeddings]] [[AI Agents]]
```
---
## 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`.
**Beispiel Notiz:**
```yaml
---
type: value
title: Prinzip: Datensparsamkeit
---
Wir speichern nur das Minimum an Daten. Cloud-Uploads persönlicher Daten sind verboten, es sei denn, sie sind E2E-verschlüsselt.
```
* **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.
---
## 6. Best Practices & Beispiele (Klassik)
Hier sind vollständige Vorlagen für häufige Typen.
### 6.1 Beispiel: Projekt-Notiz
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]]. (Automatisch 'depends_on' durch Typ-Default, falls konfiguriert).
```
### 6.2 Beispiel: Entscheidung (Decision Record)
Entscheidungen sind hoch gewichtet (`retriever_weight: 1.0`).
```markdown
---
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
Wir nutzen das Prinzip des **Virtual Schema Layers**. Wir kodieren keine Logik (wie `chunk_size`) in die Notizen. Das wird zentral in der `types.yaml` verwaltet. Das bedeutet für dich: Du kannst dich rein auf den Inhalt konzentrieren. Wenn wir die Chunking-Strategie ändern, müssen wir nicht 1000 Markdown-Dateien anfassen.