# mindnet v2.2 — Programmplan
**Version:** 2.2.1 (Post-WP04 Update)
**Stand:** 2025-12-07
**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 (mindnet-Assistent),
  - 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,
- 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.

- **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`, Policies, Knowledge-Design) festgelegt, nicht in jeder einzelnen Markdown-Datei.

- **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; mittelfristig entsteht ein Persönlichkeitsmodell, das den KI-Zwilling trägt.

- **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 (nächste Monate)

- Automatische Sammlung von Wissen aus Markdown-Vault und ersten Chat-Dialogen.
- 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).
- 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).
- Technische Basis für die späteren Agenten und den KI-Zwilling:
  - lokaler FastAPI-Dienst,
  - Qdrant als Graph-Backend,
  - konfigurierbarer Retriever (`retriever.yaml`).

### 3.2 Mittelfristig

- Persönlichkeitsprofil wird stabil erkannt und für Antworten genutzt (Typen, Werte-Notizen, Entscheidungsnotizen).
- **RAG-Chat:** KI antwortet in natürlicher Sprache auf Basis von Wissen und Persönlichkeit (WP-05).
- Why-Layer: KI-Assistenz für Entscheidungen mit nachvollziehbarer Argumentation.
- 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_subgraph`, `mindnet_store_note`, `mindnet_explain`) 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`, Policies, `knowledge_design.md`) definiert, nicht direkt in den Vault-Dateien.
   - Erlaubt spätere Anpassungen ohne manuelle Massenänderungen.

2. **Virtual Schema Layer**
   - Typen, Regeln, Policies, Edge-Defaults werden im Schema-Layer beschrieben (z. B. `knowledge_design.md`, `mindnet_functional_architecture.md`, `types.yaml`).
   - 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 (ähnliche Inhalte, typisierte Standardbeziehungen, Backlinks).

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

5. **Full Explainability**
   - Jeder Score, jede Beziehung, jeder Vorschlag muss über:
     - Edges,
     - Scoring-Komponenten (Semantik, Typ, Edge-Bonus, Centrality),
     - Provenienz (Notizen, Chunks, rule_id, confidence) nachvollziehbar sein.

6. **Persistence First**
   - Obsidian bleibt die primäre Quelle der Wahrheit.
   - mindnet ergänzt, schlägt Änderungen vor, schreibt aber nur kontrolliert (z. B. über Rewriter oder Vernetzungs-Assistent mit Freigabe).

7. **Minimalinvasives Schreiben**
   - Automatische Veränderungen an Markdown-Dateien erfolgen ausschließlich nach expliziter Zustimmung.
   - Rewriter und Vernetzungs-Assistent arbeiten grundsätzlich im Vorschlagsmodus.

8. **Incremental Growth & Early Value**
   - Das System muss bereits mit wenigen Notizen und einem kleinen Vault sinnvolle Antworten liefern (Retrieval-MVP).
   - Spätere Erweiterungen (Typen, Policies, zusätzliche Edges) dürfen bestehende Notizen nicht „ungültig“ machen, sondern ergänzen sie.
   - Feedback-Mechanismen werden früh eingeführt, auch wenn sie anfangs noch nicht vollautomatisch ausgewertet werden.

9. **Observability & Testbarkeit**
   - Jeder Importlauf, jede Retriever-Anfrage und jede Policy-Änderung soll prüfbar sein (Logs, Traces, Tests, Reports).

---

## 5. Programmstruktur (Phasenmodell)

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

Alle Workpackages sind einer Phase zugeordnet. WP-01 bis WP-04c 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 (Neu)

**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 (Neu)

**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 (Startbereit)

**Phase:** C
**Status:** 🟡 geplant (Nächster Schritt)

**Ziel:**
Aufbau eines RAG-Systems, das nicht nur sucht, sondern in natürlicher Sprache antwortet und dabei eine definierte Persönlichkeit (Werte, Prinzipien) einnimmt.

**Umfang:**
- **Config:** `config/prompts.yaml` für System-Prompts, Werte und RAG-Templates.
- **Service:** `llm_service.py` für Text-Generierung (Ollama-Anbindung).
- **Router:** `/chat` Endpoint (Kontext-Assembly -> Prompt -> LLM).
- **Persönlichkeit:** Definition von "Mindnet" als KI-Zwilling (Stil, Haltung).

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

---

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

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

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

**Umfang:**
- Identifikation typischer Entscheidungssituationen.
- Integration von fachlichem Wissen, Erfahrungen und Persönlichkeitsmodell.
- Ableitung von Entscheidungs-Templates / Heuristiken.

**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

**Ziel:**
Chat-basierter mindnet-Agent, der sowohl Fragen beantwortet als auch neue Notizen erzeugen/aktualisieren kann (Writeback Richtung Vault).

**Umfang:**
- Chat-Frontend.
- Funktionen für Q&A sowie Vorschlag neuer Notes/Edges.

**Aufwand / Komplexität:**
- Aufwand: Hoch
- 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  | 🟡     |
| 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.

---

## 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.2.1) für alle weiteren Arbeiten.