mindnet/docs/knowledge_design.md

# mindnet – Knowledge Design  
**Version:** 1.4.0 (aktualisiert 2025-10-06)

## 1. Gesamtziel und Systemverständnis

**mindnet** ist ein lokales Wissensnetzwerk, das alle meine Notizen, Projekte, Gedanken, Erfahrungen und Pläne als Markdown-Dateien speichert, automatisch importiert, semantisch in **Chunks** zerlegt und als **Graph-Struktur in Qdrant** ablegt.  
Es ist die Grundlage für ein agentenfähiges, lokal betriebenes LLM-System, das meine Daten verknüpft, abfragt und erweitert.

**Zentrale Ziele**
- Vollständige Repräsentation persönlichen Wissens in strukturierter, maschinenlesbarer Form  
- Reproduzierbare Verarbeitung: Import → Chunking → Embedding → Edges → Graph  
- Verlustfreie Roundtrip-Fähigkeit (Import ⇄ Export)  
- Erweiterbarkeit für Agenten, RAG-Retriever und semantische Suche  

**Prinzipien**
- **Deterministisch:** IDs, Hashes und Edges wiederholbar  
- **Portabel:** Markdown + YAML  
- **Robust:** fehlertoleranter Parser  
- **Idempotent:** keine Duplikate bei Re-Import  
- **Erweiterbar:** neue Typen und Edge-Arten ohne Migration  

---

## 2. YAML-Frontmatter-Schema

| Feld | Typ | Beschreibung |
|-------|-----|--------------|
| `title` | string | Menschlich lesbarer Titel |
| `id` | string | Eindeutige Note-ID (Slug) |
| `type` | enum | `concept`, `thought`, `experience`, `task`, `project`, `journal`, `person`, `meeting`, `milestone` |
| `status` | enum | `draft`, `active`, `done`, `archived` |
| `created` | date | ISO-Datum |
| `updated` | date | Letzte Änderung |
| `area` | string | Themen- oder Lebensbereich |
| `project` | string | Zugehöriges Projekt |
| `tags` | list | Strukturierte Tags (`area/…`, `topic/…`) |
| `depends_on` | list | IDs anderer Notizen |
| `assigned_to` | list | Beteiligte Personen |
| `embedding_exclude` | bool | Falls `true`, keine Embeddings |
| `hash_mode` | enum | Hash-Modus beim Import (`body`, `frontmatter`, `full`) |
| `priority` | enum/int | 1–5 oder `low` / `med` / `high` |
| `effort_min`, `due` | int/date | Aufwand / Termin |
| `aliases` | list | Alternative IDs |
| `lang` | string | ISO-Sprachcode |
| `source` | string | Herkunft / Referenzquelle |

**Pflichtfelder:** `title`, `id`, `type`, `status`, `created`  
**Optionale Felder:** alle übrigen

---

## 3. Dateinamen und Ordner

- Format: `YYYY-MM-DD_title.md` oder `slug.md`  
- Strukturierte Ordner:  
  - `10_thoughts/`, `20_concepts/`, `30_projects/`, `40_experiences/`, …  
- Alle Pfade relativ; Unterstriche statt Leerzeichen  

---

## 4. Link- und Edge-Design

**Verlinkungen**
- Wikilinks: `[[note-id]]` oder `[[Titel|note-id]]`
- Automatische Edges aus Text und Frontmatter

**Edge-Typen in Qdrant**

| Typ | Bedeutung | Quelle | Scope |
|------|------------|--------|--------|
| `belongs_to` | Chunk → Note | intern | chunk |
| `prev` / `next` | Reihenfolge | intern | chunk |
| `references` | explizite Wikilinks | Text | chunk |
| `backlink` | Gegenkante zu `references` | abgeleitet | note |
| `depends_on` | YAML-Abhängigkeiten | YAML | note |
| `assigned_to` | YAML-Zuweisung | YAML | note |
| `unresolved` | Ziel fehlt (Stub) | abgeleitet | chunk |

**Edge-Schlüssel**
- `source_id`, `target_id`, `kind`, `scope`, `note_id`
- Dedup-Schlüssel: Kombination aus `(kind, source_id, target_id, scope)`

---

## 5. Chunking-Modell

**Chunk-Datenstruktur**
| Feld | Beschreibung |
|-------|---------------|
| `note_id` | Zugehörige Note |
| `chunk_index` | Laufende Nummer |
| `text` | Originalabschnitt |
| `window` | Text + Overlap links/rechts |
| `overlap_left` | Länge des linken Overlaps |
| `overlap_right` | Länge des rechten Overlaps |
| `embedding` | 384-dimensionaler Vektor |
| `tokens` | Tokenanzahl (optional) |

**Chunking-Regeln (aus `chunking_strategy.md`)**
- Trennung nach Absätzen, Überschriften, Listen, Tabellen  
- Token-Zielgröße 350–500 (max 600)  
- Overlap: 30–40 % für semantische Kohärenz  
- Overlap wird in `window` integriert, sodass `text ≠ window`  

---

## 6. Hash-Strategie und Änderungsverfolgung

**Zweck:** Nur bei realer Inhaltsänderung re-indexieren

| Umgebungsvariable | Beschreibung |
|--------------------|--------------|
| `MINDNET_HASH_COMPARE` | Vergleichsquelle (`Body`, `Full`, `Frontmatter`) |
| `MINDNET_HASH_SOURCE` | Rohtext vs. geparst (`raw` / `parsed`) |
| `MINDNET_HASH_NORMALIZE` | Normalisierung (`canonical` / `none`) |

**Basismodi**
- `body` → Nur Textkörper  
- `frontmatter` → Nur Metadaten  
- `full` → Kombination  
- Hash = SHA-256(canonicalized_input)

Bei Änderung: Re-Import, neue Embeddings, Edges werden aktualisiert.  

---

## 7. Qdrant-Speicherstruktur

| Collection | Inhalt | Primärfelder | Embedding |
|-------------|---------|---------------|------------|
| `mindnet_notes` | Notes mit Fulltext & Hash | `note_id` | optional |
| `mindnet_chunks` | Chunks mit Text, Window, Embedding | `chunk_id`, `note_id` | 384 d |
| `mindnet_edges` | Graphkanten | `edge_id`, `source_id`, `target_id` | — |

**Upsert-Strategie**
- Idempotente UUIDv5-IDs  
- Keine Duplikate durch deterministische Signaturen  
- `purge-before-upsert` zur Bereinigung  

**Indizes**
- notes: `note_id`, `hash_signature`  
- chunks: `note_id`, `chunk_index`  
- edges: `(kind, source_id, target_id, scope)`

---

## 8. Fehler-Toleranz und Parser-Robustheit

- UTF-8 mit Fallback: ersetzt ungültige Bytes (`errors="replace"`)  
- Ignoriert Nullbytes, BOM, exotische Zeilenenden  
- Erkennt defekte oder leere YAML-Header und überspringt sie  
- Logt Problemfälle (`read_markdown failed`, `make_note_payload returned non-dict`)  
- Bei Fehlern: Import → warn → continue  

---

## 9. Tests & Validierung

**Integrationstests**
- Roundtrip: Import → Export → Compare (`compare_vaults.py`)  
- Chunk-Integrität: `verify_chunks_integrity.py`  
- Hash-Audit: `hash_reporter.py`  
- Window-Vergleich: `check_chunks_window_vs_text.py`  

**Erwartete Ergebnisse**
- Alle Notes werden erkannt  
- `window ≠ text` bei > 60 % der Chunks  
- Roundtrip-Vergleich liefert „OK“  
- Edge-Anzahl entspricht Modell (belongs_to = #Chunks, next/prev ≈ #Chunks – 1)  

---

## 10. Export & Roundtrip-Verhalten

- `export_markdown.py` erzeugt identische Markdown-Dateien  
- Schreibt YAML + Body in korrekter Reihenfolge  
- Roundtrip-Prüfung (`compare_vaults.py`) validiert:
  - vollständigen Body  
  - unveränderte Hash-Signatur  
  - gleiche Chunkzahl  

---

## 11. Graph-Schicht und WP-04-Integration

- Qdrant fungiert als Graph-Backend  
- `graph/service.py` (WP-04): stellt API für Mehrhop-Abfragen bereit  
- Unterstützt:  
  - `expand(note_id, hops=2)`  
  - `resolve_unresolved()`  
  - `neighbors(kind=…)`  
- Grundlage für spätere **Retriever-Funktionen** (LLM / Agenten)  

---

## 12. Agenten- und LLM-Integration

**Retriever-Pipeline**
1. Suche top-k Chunks (cosine distance)  
2. Erweiterung um Edges (`references`, `backlinks`)  
3. Kontext-Assembling via `window`-Text  
4. Prompt-Generierung  

**Agent-Use-Cases**
- Automatisches Tagging (`type`, `status`)  
- Vorschläge für neue Edges  
- Auflösen von `unresolved`-Referenzen  
- Auto-Import externer Quellen (MediaWiki, PDFs, Webseiten)  

---

## 13. Erweiterbarkeit

- Neue Edge-Typen: `inspired_by`, `relates_to`, `contradicts`  
- Neue Note-Typen: `decision`, `resource`, `recommendation`  
- Embedding-Engines austauschbar (MiniLM → LaBSE → E5)  
- Versionierte Chunking-Strategien (`chunk_config.py`)  

---

## 14. Qualitätssicherung und Best Practices

- Validierung vor Upsert  
- Keine Leer-Chunks  
- Vollständige Metadaten in Notes  
- Tests in `tests/` automatisch ausführbar (`run_e2e_roundtrip.sh`)  
- Ergebnis: „Roundtrip OK“ und `verify_chunks_integrity` = OK  

---

## 15. Änderungsverlauf

**v1.4.0 (2025-10-06)**
- Neu: `window` vs `text` Feld in `mindnet_chunks`  
- Neu: Hash-Modi (`body`, `frontmatter`, `full`) mit Env-Steuerung  
- Neu: Baseline-Modus für Vergleich  
- Parser → fehlertolerant (UTF-8 replace)  
- Roundtrip-Test vollständig integriert  
- Graph-Service und Mehrhop-Abfragen (WP-04-Vorbereitung)  
- `purge-before-upsert` und `--note-scope-refs` Parameter ergänzt  

**v1.3.0 (2025-09-09)**  
- Hash-Normalisierung und Edge-Scope  
- Roundtrip-Tests, Agenten-Integration  

**v1.2.0 (2025-09-02)**  
- Grundstruktur des Knowledge-Designs  

---