mindnet/Programmmanagement/Programmplan_V2.2.md

# mindnet v2.2 — Programmplan
**Version:** 2.3.0 (Post-WP05 RAG Integration)
**Stand:** 2025-12-08
**Status:** Aktiv

---

## 1. Programmauftrag

mindnet v2.2 entwickelt ein persönliches, wachsendes KI-Gedächtnis, das:

- Wissen, Erfahrungen, Werte und Entscheidungen speichert,
- diese Informationen semantisch verknüpft und rekonstruierbar macht,
- einen KI-Zwilling aufbaut, der ähnlich argumentiert, entscheidet und reflektiert wie du,
- über mehrere Kanäle gefüttert wird:
  - Obsidian-Markdown (primäre Quelle),
  - Chat-basierter Agent (RAG-Chat aktiv),
  - später: Interview-Assistent (strukturierte Dialogerfassung),
- automatisch neue Zusammenhänge erkennt und vernetzt (Edges, Typen, Hinweise),
- sich durch Rückmeldungen (Feedback) selbst verbessert (Self-Tuning).

Langfristig soll mindnet als **digitales Gegenüber** funktionieren, das:

- dich versteht,
- deine Denkweise reflektiert,
- deine Werte kennt und verwendet,
- Entscheidungen begründen kann („Warum?“),
- Erinnerungen einordnet,
- und für deine Nachkommen als dialogfähiger Gesprächspartner zur Verfügung steht.

mindnet ist **kein statisches Wissensarchiv**, sondern ein **lebendes, lernendes Gedächtnismodell** mit Fokus auf:

- persönliche Perspektive,
- erklärbare Begründungspfade (Why-Layer),
- kontinuierliche Erweiterbarkeit,
- robuste technische Basis (lokal, nachvollziehbar, versioniert).

---

## 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 über Edges, Scores, Werte-Bezüge und Herkunftsnotizen begründbar sein. Das System kann Entscheidungen auf zugrundeliegende `[DECISION]`-Notizen zurückführen.

- **Wachstum:**
  Das System arbeitet von Anfang an mit unvollständigen Daten, kann aber schrittweise dichter werden, ohne dass alte Notizen massenhaft manuell angepasst werden müssen.

- **Flexibilität (Late Binding):**
  Semantik wird überwiegend in Konfiguration (z. B. `types.yaml`, `prompts.yaml`, Policies) festgelegt. Die Persönlichkeit entsteht durch das Prompt-Design, nicht durch Hardcoding.

- **Autonomie & Self-Healing:**
  mindnet schlägt fehlende Typen, Relationen und Edges vor (z. B. aus Inline-Relationen, Edge-Defaults, Ähnlichkeitsbeziehungen) und baut damit einen „self-healing graph“ auf.

- **Lernen & Self-Tuning:**
  Feedback zu Antworten (gut/schlecht, relevant/nicht relevant) fließt in Score-Gewichte, Policies und ggf. Edge-Struktur ein.

- **Persönlichkeit:**
  Entscheidungen werden wert- und erfahrungsbasiert begründet; das System agiert als KI-Zwilling durch Nutzung lokaler LLMs (z.B. Phi-3/Mistral).

- **Incremental Growth:**
  Das System muss mit wenigen, heterogenen Notizen starten und sich fortlaufend verdichten können – ohne Retro-Massenmigrationen im Vault.

---

## 3. Programmziele

### 3.1 Kurzfristig (Abgeschlossen / Laufend)

- Automatische Sammlung von Wissen aus Markdown-Vault.
- Aufbau eines stabilen Graph-Speichers in Qdrant (`*_notes`, `*_chunks`, `*_edges`).
- Semantischer und graphbasierter Retriever (WP-04a abgeschlossen).
- **Erklärbarkeit:** Why-Layer liefert Begründungen zu Treffern (WP-04b abgeschlossen).
- **Feedback-Loop:** Systematisches Logging von Suche und Bewertung (WP-04c abgeschlossen).
- **RAG-Chat:** KI antwortet in natürlicher Sprache auf Basis von Wissen und Persönlichkeit (WP-05 abgeschlossen).
- Technische Basis: FastAPI, Qdrant, Ollama (Local LLM).
- Automatisierte Erkennung von Beziehungen:
  - Wikilinks, Inline-Relationen, Callout-Edges, Typ-Defaults.
- Schrittweises Lernen über Feedback (Score-Tuning, noch „manuell“ konfiguriert).
- „Mitwachsendes“ Schema ohne Obsidian-Umstrukturierungen:
  - Neues Wissen kann sofort erfasst werden,
  - bestehende Notizen bleiben gültig (Virtual Schema Layer).

### 3.2 Mittelfristig (Nächste Schritte)

- **Decision Engine (WP-06):** Das System berät aktiv bei Entscheidungen, indem es `type: value` und `type: principle` Notizen gegen eine Fragestellung abwägt.
- **Chat Interface (WP-10):** Ablösung der Terminal-Interaktion durch ein Web-Frontend (Streamlit/React) für bessere UX und einfacheres Feedback-Geben.
- Interview-Assistent erstellt neue Notes automatisch (strukturierte Dialoge → Markdown).
- mindnet erzeugt Vorschläge für neue Notes & Edges und bietet einen „Vernetzungs-Assistenten“ für manuell angelegte Notizen.
- Agenten können über MCP-Tools (`mindnet_query`, `mindnet_chat`) auf mindnet zugreifen.

### 3.3 Langfristig

- KI-Zwilling, der deinen Stil, deine Werte und deine typische Denkweise repräsentiert.
- Weitgehend autonomes Self-Tuning der Wissensstruktur (auf Basis gespeicherter Feedback-Daten & Policies).
- Lebenslanges Gedächtnis, das
  - konsistent bleibt,
  - wächst,
  - sich weiterentwickelt,
  - und deine Geschichte für deine Nachkommen erzählbar und erlebbar macht.

---

## 4. Architekturprinzipien

Die folgenden Prinzipien steuern alle Workpackages und Entscheidungen:

1. **Late Binding (späte Semantik)**
   - Struktur und Interpretation werden in Konfigurationen (z. B. `types.yaml`, `prompts.yaml`, Policies) definiert, nicht direkt in den Vault-Dateien.
   - Die "Persönlichkeit" des Chats ist ein Prompt-Template, kein Code.

2. **Virtual Schema Layer**
   - Typen, Regeln, Policies, Edge-Defaults werden im Schema-Layer beschrieben.
   - Markdown-Dateien benötigen nur minimale, robuste Angaben (Titel, Typ, optionale Properties).

3. **Self-Healing Graph**
   - Der Graph wird regelmäßig analysiert (Edges, Centrality, fehlende Links).
   - Automatisierte Jobs ergänzen fehlende Kanten.

4. **Deterministische IDs**
   - Notes, Chunks und Edges erhalten stabile IDs (z. B. UUIDv5).
   - Der Graph ist jederzeit wiederaufbaubar (Import-Pipeline idempotent).

5. **Full Explainability & Context Enrichment**
   - Jeder Score, jede Beziehung muss nachvollziehbar sein.
   - Dem LLM werden Metadaten (`[DECISION]`, `[PROJECT]`) injiziert, um Halluzinationen zu vermeiden und logische Schlüsse zu ermöglichen.

6. **Persistence First**
   - Obsidian bleibt die primäre Quelle der Wahrheit.
   - mindnet ergänzt, schlägt Änderungen vor, schreibt aber nur kontrolliert.

7. **Minimalinvasives Schreiben**
   - Automatische Veränderungen an Markdown-Dateien erfolgen ausschließlich nach expliziter Zustimmung.

8. **Incremental Growth & Early Value**
   - Das System muss bereits mit wenigen Notizen und einem kleinen Vault sinnvolle Antworten liefern.
   - Feedback-Mechanismen werden früh eingeführt.

9. **Observability & Testbarkeit**
   - Jeder Importlauf, jede Retriever-Anfrage und jede Policy-Änderung soll prüfbar sein.
   
10. **Local First & Privacy**
    - Nutzung lokaler LLMs (Ollama/Phi-3) für Inference. Keine Daten verlassen den Server.

---

## 5. Programmstruktur (Phasenmodell)

    Phase A – Fundament & Import (Fertig)
    Phase B – Semantik, Graph & Lernen (Fertig)
    Phase C – Persönlichkeitsmodell & KI-Zwilling (Laufend)
    Phase D – Agenten, MCP & Interaktion (Startend)
    Phase E – Review, Refactoring, Dokumentation

Alle Workpackages sind einer Phase zugeordnet. WP-01 bis WP-05 sind bereits erfolgreich abgeschlossen.

---

## 6. Workpackages – detaillierte Übersicht

### Legende Aufwand / Komplexität

- Aufwand: Niedrig / Mittel / Hoch
- Komplexität: Niedrig / Mittel / Hoch

Die Status-Ampel zeigt den aktuellen Stand gemäß Programmfortschritt.

---

### WP-01 – Wissensdesign (abgeschlossen)

**Phase:** A
**Status:** 🟢 abgeschlossen

**Ziel:**
Grundlegendes Schema für mindnet festlegen (`knowledge_design.md`), inkl.:
- Note-Typen (z. B. `concept`, `experience`, `project`, `decision`, `value`).
- Standard-Properties und Grundstruktur von Edges.
- Abbildung zentraler Lebens-Bereiche.

**Erreichte Ergebnisse:**
- `knowledge_design.md` und `types.yaml` definieren die Zielarchitektur.

---

### WP-02 – Chunking & Hash-Strategie (abgeschlossen)

**Phase:** A
**Status:** 🟢 abgeschlossen

**Ziel:**
Festlegen und implementieren einer robusten Chunking-Strategie und einer Hash-Logik zur Änderungserkennung.

**Erreichte Ergebnisse:**
- Implementierte Chunker-Logik mit Overlap.
- Stabile Hash-Strategie zur sicheren Änderungserkennung.

---

### WP-03 – Import-Pipeline & Edge-System v2 (abgeschlossen)

**Phase:** A/B
**Status:** 🟢 abgeschlossen

**Ziel:**
Durchgängige Import-Pipeline von Markdown → Notes/Chunks/Edges in Qdrant mit deterministischen IDs.

**Erreichte Ergebnisse:**
- Vollständige E2E-Import-Pipeline.
- Vollständiges Edge-Modell (Strukturkanten, Wikilinks, Inline-Relationen).

---

### WP-04a – Retriever & Graph-Scoring (abgeschlossen)

**Phase:** B
**Status:** 🟢 abgeschlossen

**Ziel:**
Aufbau eines hybriden Retrievers, der Semantik, Typwissen und Graph-Informationen kombiniert.

**Erreichte Ergebnisse:**
- Hybrides Scoring-Modell (Semantic + Edge + Centrality).
- Konfiguration über `retriever.yaml`.
- `/query` Endpoint aktiv.

---

### WP-04b – Explanation Layer ("Why-Layer") (abgeschlossen)

**Phase:** B
**Status:** 🟢 abgeschlossen

**Ziel:**
Treffererklärungen liefern, die verständlich machen, warum ein Ergebnis gewählt wurde.

**Erreichte Ergebnisse:**
- **DTO-Erweiterung:** `QueryHit` enthält `explanation`, `breakdown` und `reason`.
- **Logic:** Graph-Adapter unterstützt `incoming_edges` (Reverse Lookup) für Authority-Erklärungen.
- **Output:** `/query` Endpoint liefert auf Wunsch (`explain: true`) menschenlesbare Begründungen ("Verweist auf...").

---

### WP-04c – Feedback Logging & Bewertungsdaten (abgeschlossen)

**Phase:** B
**Status:** 🟢 abgeschlossen

**Ziel:**
Grundlage für Self-Tuning schaffen durch systematisches Logging.

**Erreichte Ergebnisse:**
- **Data Flywheel:** Logging von Queries und User-Feedback in lokalen JSONL-Dateien.
- **Search Log:** Speichert Query + Score-Snapshot in `data/logs/search_history.jsonl`.
- **Feedback Log:** Speichert User-Ratings in `data/logs/feedback.jsonl`.
- **Traceability:** Durchgängige `query_id` von Request bis Feedback.

---

### WP-05 – Persönlichkeitsmodell & RAG-Chat (abgeschlossen)

**Phase:** C
**Status:** 🟢 abgeschlossen

**Ziel:**
Aufbau eines RAG-Systems, das in natürlicher Sprache antwortet und Kontext versteht.

**Erreichte Ergebnisse:**
- **Infrastruktur:** Integration von Ollama (Phi-3 Mini) in den Service-Layer.
- **Router:** `/chat` Endpoint mit "Hybrid Retrieval Enforcement".
- **Context Enrichment:** Injection von Metadaten (`[TYPE]`, `[SCORE]`) in den Prompt, damit kleine Modelle (SLMs) komplexe Zusammenhänge ("Warum?") verstehen.
- **Config:** `prompts.yaml` steuert System-Prompt und RAG-Template.

**Aufwand / Komplexität:**
- Aufwand: Mittel
- Komplexität: Mittel

---

### WP-05b – Advanced Chat (Optional)

**Phase:** C
**Status:** ⚪ optional

**Ziel:**
Erweiterung des Chats um Gedächtnis (History) und einfache Tools.

**Umfang:**
- Implementierung von `ChatHistory` (vergangene Nachrichten in den Kontext).
- Einfache Tool-Nutzung (z.B. "Suche in Web").

---

### WP-06 – Decision Engine (geplant)

**Phase:** C
**Status:** 🟡 geplant (Priorität A)

**Ziel:**
Entscheidungsunterstützung auf Basis von Wissen, Persönlichkeit und Zielen – inklusive nachvollziehbarer Begründung.

**Umfang:**
- Erweiterung des RAG-Kontexts um gezieltes Nachladen von `type: value` und `type: principle`.
- Prompt-Engineering für "Trade-off Analyse" (Pro/Contra basierend auf Werten).
- Output-Formatierung als Entscheidungsvorlage.

**Aufwand / Komplexität:**
- Aufwand: Mittel
- Komplexität: Hoch

---

### WP-07 – Interview-Assistent (geplant)

**Phase:** C
**Status:** 🟡 geplant

**Ziel:**
Dialogbasierter Erfassungs-Assistent, der strukturierte Interviews führt und daraus konsistente Markdown-Notizen generiert.

**Umfang:**
- Design von Interview-Flows.
- Konvertierung von Dialogtranskripten in typisierte Notes.

**Aufwand / Komplexität:**
- Aufwand: Niedrig/Mittel
- Komplexität: Mittel

---

### WP-08 – Self-Tuning v1/v2 (geplant)

**Phase:** B/C
**Status:** 🟡 geplant

**Ziel:**
Aufbau eines Self-Tuning-Mechanismus, der auf Basis von Feedback-Daten (WP-04c) Vorschläge für Retriever- und Policy-Anpassungen macht.

**Umfang:**
- Auswertung der JSONL-Feedback-Daten.
- Regel-basierte Anpassungs-Vorschläge für `retriever.yaml` und Typ-Prioritäten.

**Aufwand / Komplexität:**
- Aufwand: Hoch
- Komplexität: Hoch

---

### WP-09 – Vault-Onboarding & Migration (geplant)

**Phase:** B
**Status:** 🟡 geplant

**Ziel:**
Sicherstellen, dass bestehende und neue Obsidian-Vaults schrittweise in mindnet integriert werden können – ohne Massenumbau.

**Umfang:**
- Tools zur Analyse des Vault-Status.
- Empfehlungen für minimale Anpassungen.

**Aufwand / Komplexität:**
- Aufwand: Mittel
- Komplexität: Niedrig/Mittel

---

### WP-10 – Chat-Interface & Writeback (geplant)

**Phase:** D
**Status:** 🟡 geplant (Priorität B - "Quick Win")

**Ziel:**
Ablösung der Terminal-Interaktion durch ein grafisches Interface.

**Umfang:**
- Technologie: Streamlit oder einfaches HTML/JS Frontend.
- Funktionen: Chat-Verlauf, Anzeige der Quellen (mit Scores), Daumen-hoch/runter für WP-04c Feedback.
- Funktionen für Q&A sowie Vorschlag neuer Notes/Edges.

**Aufwand / Komplexität:**
- Aufwand: Hoch (durch Writeback) / Mittel (für reines Frontend)
- Komplexität: Hoch

---

### WP-11 – Knowledge-Builder & Vernetzungs-Assistent (geplant)

**Phase:** D
**Status:** 🟡 geplant

**Ziel:**
Assistent, der manuell erstellte oder importierte Notizen analysiert und Vorschläge für Typen, Edges und Einordnung macht.

**Aufwand / Komplexität:**
- Aufwand: Hoch
- Komplexität: Hoch

---

### WP-12 – Knowledge Rewriter (Soft Mode, geplant)

**Phase:** C/D
**Status:** 🟡 geplant

**Ziel:**
Optionaler Assistent, der vorhandene Notes „aufräumt“, zusammenfasst oder reorganisiert – ausschließlich mit expliziter Freigabe.

**Aufwand / Komplexität:**
- Aufwand: Niedrig/Mittel
- Komplexität: Mittel

---

### WP-13 – MCP-Integration & Agenten-Layer (geplant)

**Phase:** D
**Status:** 🟡 geplant

**Ziel:**
mindnet als MCP-Server bereitstellen, damit Agenten/LLMs standardisierte Tools nutzen können.

**Umfang:**
- MCP-Server mit Tools (`mindnet_query`, `mindnet_explain`, etc.).

**Aufwand / Komplexität:**
- Aufwand: Mittel
- Komplexität: Mittel

---

### WP-14 – Review / Refactoring / Dokumentation (geplant)

**Phase:** E
**Status:** 🟡 geplant

**Ziel:**
Aufräumen, dokumentieren, stabilisieren – insbesondere für Onboarding Dritter und Langfrist-Betrieb.

**Aufwand / Komplexität:**
- Aufwand: Mittel
- Komplexität: Niedrig/Mittel

---

## 7. Abhängigkeiten (vereinfacht, aktualisiert)

    WP01 → WP02 → WP03 → WP04a
    WP04a → WP04b → WP04c → WP08
    WP03 → WP05 → WP06 → WP07
    WP03 → WP09
    WP01/WP03 → WP10 → WP11 → WP12
    WP03/WP04 → WP13
    Alles → WP14

---

## 8. Laufzeit- & Komplexitätsindikatoren (aktualisiert)

| WP    | Aufwand        | Komplexität      |
|-------|----------------|------------------|
| WP04b | Mittel         | Hoch             |
| WP04c | Mittel         | Mittel/Hoch      |
| WP05  | Mittel         | Mittel           |
| WP06  | Mittel         | Hoch             |
| WP07  | Niedrig/Mittel | Mittel           |
| WP08  | Hoch           | Hoch             |
| WP09  | Mittel         | Niedrig/Mittel   |
| WP10  | Hoch           | Hoch             |
| WP11  | Hoch           | Hoch             |
| WP12  | Niedrig/Mittel | Mittel           |
| WP13  | Mittel         | Mittel           |
| WP14  | Mittel         | Niedrig/Mittel   |

---

## 9. Programmfortschritt (Ampel, aktualisiert)

| WP    | Status |
|-------|--------|
| WP01  | 🟢     |
| WP02  | 🟢     |
| WP03  | 🟢     |
| WP04a | 🟢     |
| WP04b | 🟢     |
| WP04c | 🟢     |
| WP05  | 🟢     |
| WP05b | ⚪     |
| WP06  | 🟡     |
| WP07  | 🟡     |
| WP08  | 🟡     |
| WP09  | 🟡     |
| WP10  | 🟡     |
| WP11  | 🟡     |
| WP12  | 🟡     |
| WP13  | 🟡     |
| WP14  | 🟡     |

---

## 10. Governance & Versionierung

- Versionierung über Gitea (Branches, Tags, Releases).
- Feature-Branch Workflow mit "Sync First" Strategie.
- Jede wesentliche Änderung an Architektur/Schema erhält einen eigenen Commit.
- Jedes Workpackage erhält ein eigenes Chat-Fenster mit dediziertem Prompt (WP-Hand-Over).
- Programmleitung verantwortet Konsistenz und Priorisierung.
- **Modell-Governance:** Das verwendete LLM (z.B. `phi3:mini`) wird in der `.env` und `config.py` festgeschrieben. Updates erfordern Tests gegen die "Why-Layer" Referenzfragen.

---

## 11. Executive Summary

mindnet v2.2 ist so aufgesetzt, dass:

- du **schrittweise** Wissen erfassen kannst (Obsidian + Chat + später Interview-Assistent),
- die Struktur **mitwächst**, ohne Retro-Massenarbeit im Vault,
- ein **hybrider Retriever** qualitativ hochwertige, erklärbare Antworten liefert,
- ein **Self-Healing- und Self-Tuning-Mechanismus** vorbereitet ist (durch WP-04c Feedback-Daten),
- ein **Persönlichkeitsmodell** und eine **Decision Engine** entstehen,
- langfristig ein **KI-Zwilling** aufgebaut wird, der deine Werte, Erfahrungen und Denkweise spiegelt,
- die technische Architektur (FastAPI, Qdrant, YAML-Policies, MCP-Integration) lokal, nachvollziehbar und erweiterbar bleibt.

Dieser Programmplan bildet die konsolidierte Grundlage (v2.3.0) für alle weiteren Arbeiten.