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

+109
View File
@@ -0,0 +1,109 @@
# Mindnet v2.6 – Documentation Map & Governance
**Status:** Active
**Context:** Central Navigation & Maintenance Guide
## 1. Zweck dieses Dokuments
Diese Karte dient Entwicklern, dem Mindmaster und KI-Agenten als **zentraler Einstiegspunkt**. Sie beantwortet zwei Fragen:
1. **Navigation:** In welcher Datei finde ich Informationen zu Thema X?
2. **Wartung:** Ich arbeite an Feature Y – welche Dateien muss ich aktualisieren?
---
## 2. Verzeichnisstruktur & Inhalte
Das Repository ist in **logische Domänen** unterteilt.
### 📂 00_General (Grundlagen)
*Zielgruppe: Alle*
| Datei | Inhalt & Zweck |
| :--- | :--- |
| `00_vision_and_strategy.md` | **Strategie.** Warum bauen wir das? Prinzipien (Privacy, Local-First), High-Level Architektur. |
| `00_glossary.md` | **Definitionen.** Was bedeutet "Smart Edge", "Traffic Control", "Chunk"? Verhindert Begriffsverwirrung. |
| `00_documentation_map.md` | **Dieser Index.** Navigationshilfe. |
### 📂 01_User_Manual (Anwendung)
*Zielgruppe: Mindmaster, Autoren, Power-User*
| Datei | Inhalt & Zweck |
| :--- | :--- |
| `01_chat_usage_guide.md` | **Bedienung.** Wie steuere ich die Personas (Berater, Spiegel)? Wie nutze ich das Feedback? |
| `01_knowledge_design.md` | **Content-Regeln.** Die "Bibel" für den Vault. Erklärt Note-Typen, Matrix-Logik und Markdown-Syntax. |
### 📂 02_Concepts (Fachliche Logik)
*Zielgruppe: Architekten, Product Owner*
| Datei | Inhalt & Zweck |
| :--- | :--- |
| `02_concept_graph_logic.md` | **Graph-Theorie.** Abstrakte Erklärung von Knoten, Kanten, Provenance und Idempotenz. |
| `02_concept_ai_personality.md`| **KI-Verhalten.** Konzepte hinter dem Hybrid Router, Empathie-Modell und "Teach-the-AI". |
### 📂 03_Technical_Reference (Technik & Code)
*Zielgruppe: Entwickler, DevOps. (Enthält JSON/YAML Beispiele)*
| Datei | Inhalt & Zweck |
| :--- | :--- |
| `03_tech_data_model.md` | **Datenbank.** Exakte Qdrant-Schemas (Payloads) und Index-Anforderungen. |
| `03_tech_ingestion_pipeline.md`| **Import.** Ablauflogik (13 Schritte), Chunker-Profile, Smart Edge Allocation. |
| `03_tech_retrieval_scoring.md` | **Suche.** Die mathematischen Formeln für Scoring, Hybrid Search und Explanation Layer. |
| `03_tech_chat_backend.md` | **API & LLM.** Implementation des Routers, Traffic Control (Semaphore) und Feedback-Traceability. |
| `03_tech_configuration.md` | **Config.** Referenztabellen für `.env`, `types.yaml` und `retriever.yaml`. |
### 📂 04_Operations (Betrieb)
*Zielgruppe: Administratoren*
| Datei | Inhalt & Zweck |
| :--- | :--- |
| `04_admin_operations.md` | **Runbook.** Installation, Docker-Setup, Backup/Restore, Troubleshooting Guide. |
### 📂 05_Development (Code)
*Zielgruppe: Entwickler*
| Datei | Inhalt & Zweck |
| :--- | :--- |
| `05_developer_guide.md` | **Workflow.** Hardware-Setup (Win/Pi/Beelink), Git-Flow, Test-Befehle, Modul-Interna. |
### 📂 06_Roadmap & 99_Archive
*Zielgruppe: Projektleitung*
| Datei | Inhalt & Zweck |
| :--- | :--- |
| `06_active_roadmap.md` | **Zukunft.** Aktive Workpackages (WP16+), Release-Planung und WP-Historie (Tabelle). |
| `99_legacy_workpackages.md` | **Vergangenheit.** Detaillierte Archivdaten zu abgeschlossenen WPs (WP01–WP15). |
---
## 3. Maintenance Guide: "Welche Datei muss ich ändern?"
Nutze diese Matrix, wenn du ein Workpackage bearbeitest, um die Dokumentation konsistent zu halten.
| Wenn du arbeitest an... | ...aktualisiere diese Dateien: |
| :--- | :--- |
| **Neuen Note-Typen** | 1. `01_knowledge_design.md` (Für Autoren)<br>2. `03_tech_configuration.md` (Technische Referenz)<br>3. `05_developer_guide.md` (Erweiterungs-How-To) |
| **Importer / Parsing** | `03_tech_ingestion_pipeline.md` |
| **Datenbank-Schema** | `03_tech_data_model.md` (Payloads anpassen) |
| **Retrieval / Scoring** | `03_tech_retrieval_scoring.md` (Formeln anpassen) |
| **Chat-Logik / Prompts**| 1. `02_concept_ai_personality.md` (Konzept)<br>2. `03_tech_chat_backend.md` (Tech)<br>3. `01_chat_usage_guide.md` (User-Sicht) |
| **Deployment / Server** | `04_admin_operations.md` |
| **Neuen Features (Allg.)**| `06_active_roadmap.md` (Status Update) |
---
## 4. Prinzipien für die Dokumentation (Governance)
Damit dieses System wartbar bleibt (auch für KI-Agenten wie NotebookLM), gelten folgende Regeln:
1. **Single Source of Truth:**
Kopiere keine Informationen. Referenziere sie.
* *Ausnahme:* Konkrete JSON-Beispiele in `03_Technical_Reference`. Diese müssen dort stehen, damit Entwickler nicht suchen müssen.
2. **Konkrete Beispiele:**
Technische Dokumente (`03_*`) müssen **immer** Code-Snippets (JSON, YAML, Shell) enthalten. Abstrakte Beschreibungen reichen nicht für die Implementierung.
3. **Human Readable:**
User Manuals (`01_*`) müssen Narrative und Szenarien enthalten ("Stell dir vor..."), keine technischen Auflistungen.
4. **KI-Optimiert (Context Header):**
Jede Datei muss mit einem YAML-Frontmatter beginnen, der `context`, `audience` und `scope` definiert. Dies hilft RAG-Systemen, den Inhalt korrekt einzuordnen.
```yaml
---
doc_type: technical_reference
audience: developer
context: "Beschreibung der Scoring-Formel."
---
```
+42
View File
@@ -0,0 +1,42 @@
---
doc_type: glossary
audience: all
status: active
version: 2.6
context: "Definitionen zentraler Begriffe und Entitäten im Mindnet-System."
---
# Mindnet Glossar
**Quellen:** `appendix.md`, `Overview.md`
## Kern-Entitäten
* **Note:** Repräsentiert eine Markdown-Datei. Die fachliche Haupteinheit.
* **Chunk:** Ein Textabschnitt einer Note (meist 512 Tokens). Die technische Sucheinheit (Vektor).
* **Edge:** Eine gerichtete Verbindung zwischen zwei Knoten (Chunks oder Notes).
* **Vault:** Der lokale Ordner mit den Markdown-Dateien (Source of Truth).
* **Frontmatter:** Der YAML-Header am Anfang einer Notiz (enthält `id`, `type`, `title`).
## Komponenten
* **Importer:** Das Python-Skript (`ingestion.py`), das Markdown liest und in Qdrant schreibt.
* **Retriever:** Die Komponente, die sucht. Nutzt hybrides Scoring (Semantik + Graph).
* **Decision Engine:** Teil des Routers, der entscheidet, wie auf eine Anfrage reagiert wird (z.B. Strategie wählen).
* **Hybrid Router v5:** Die Logik, die erkennt, ob der User eine Frage stellt (`RAG`) oder einen Befehl gibt (`INTERVIEW`).
* **Draft Editor:** Die Web-UI-Komponente, in der generierte Notizen bearbeitet werden.
* **Traffic Control:** Ein Mechanismus im `LLMService`, der Chat-Anfragen priorisiert und Hintergrund-Jobs (wie Import) drosselt.
## Konzepte & Features
* **Active Intelligence:** Feature im Web-Editor, das während des Schreibens automatisch Links vorschlägt.
* **Smart Edge Allocation (WP15):** Ein KI-Verfahren, das prüft, ob ein Link in einer Notiz für einen spezifischen Textabschnitt relevant ist.
* **Healing Parser:** UI-Funktion, die fehlerhaften Output des LLMs (z.B. defektes YAML) automatisch repariert.
* **Explanation Layer:** Die Schicht, die dem Nutzer erklärt, *warum* ein Suchergebnis gefunden wurde (z.B. "Weil Projekt X davon abhängt").
* **Provenance:** Die Herkunft einer Kante.
* `explicit`: Vom Mensch geschrieben.
* `smart`: Vom LLM validiert.
* `rule`: Durch Config-Regel erzeugt.
* **Matrix Logic:** Regelwerk, das den Typ einer Kante basierend auf Quell- und Ziel-Typ bestimmt (z.B. Erfahrung -> Wert = `based_on`).
* **Idempotenz:** Die Eigenschaft des Importers, bei mehrfacher Ausführung dasselbe Ergebnis zu liefern ohne Duplikate.
* **Resurrection Pattern:** UI-Technik, um User-Eingaben beim Tab-Wechsel zu erhalten.
+67
View File
@@ -0,0 +1,67 @@
---
doc_type: strategy
audience: all
status: active
version: 2.6
context: "Vision, Mission und Architekturprinzipien von Mindnet."
---
# Mindnet Vision & Strategie
**Quellen:** `Programmplan_V2.2.md`
## 1. Programmauftrag
Mindnet v2.6 entwickelt ein persönliches, wachsendes KI-Gedächtnis. Es ist ein **Digitaler Zwilling**, der:
- Wissen, Erfahrungen und Werte speichert.
- Semantisch verknüpft (Graphen-basiert).
- Als Dialogpartner agiert (RAG-Chat).
- **Lokal und privat** läuft (Privacy First).
Es ist **kein statisches Archiv**, sondern ein lebendes System, das durch Interaktion (Feedback, Smart Edges) besser wird.
## 2. Vision
> „Ein persönliches semantisches Gedächtnis, das mit mir wächst, meine Persönlichkeit spiegelt und mir als intelligenter, erklärbarer, lernender Begleiter dient.“
**Kernprinzipien der Vision:**
* **Erklärbarkeit:** Jede Antwort muss begründbar sein ("Why-Layer").
* **Wachstum:** Das System startet klein und verdichtet sich.
* **Autonomie:** Es schlägt fehlende Kanten selbstständig vor (Smart Edges).
* **Persönlichkeit:** Es entscheidet basierend auf *deinen* Werten.
---
## 3. Architekturprinzipien
Die folgenden Prinzipien steuern jede technische Entscheidung:
1. **Late Binding (Späte Semantik):**
Struktur und Interpretation werden in Konfigurationen (`types.yaml`, `prompts.yaml`) definiert, nicht direkt in den Vault-Dateien. Die "Persönlichkeit" ist Config, kein Code.
2. **Virtual Schema Layer:**
Markdown-Dateien benötigen nur minimale, robuste Angaben (Frontmatter). Komplexität (Chunk-Größe, Gewichte) wird zur Laufzeit injiziert.
3. **Self-Healing Graph:**
Der Graph wird regelmäßig auf Konsistenz geprüft. "Dangling Edges" werden bereinigt, fehlende Links durch Smart Edges ergänzt.
4. **Deterministische IDs:**
Notes und Chunks erhalten stabile IDs (UUIDv5). Der Graph ist jederzeit aus dem Markdown wiederaufbaubar.
5. **Full Explainability:**
Keine Blackbox. Jede Antwort liefert Metadaten (`[DECISION]`, `[PROJECT]`) und Begründungen.
6. **Persistence First:**
Obsidian (Markdown) bleibt die **einzige Quelle der Wahrheit**. Die Datenbank ist nur ein abgeleiteter Cache.
7. **Minimalinvasives Schreiben:**
Mindnet schreibt nie ungefragt in deine Notizen. Änderungen erfolgen nur über den Draft Editor oder mit expliziter Zustimmung.
8. **Incremental Growth:**
Das System muss bereits mit wenigen Notizen nützlich sein.
9. **Observability:**
Jeder Importlauf und jede Retriever-Anfrage ist logbar.
10. **Local First & Privacy:**
Nutzung lokaler LLMs (Ollama) für Inference. Keine Daten verlassen den Server.