docs/knowledge_design.md aktualisiert

docs/knowledge_design.md

@@ -1,504 +1,249 @@
----
+# mindnet – Knowledge Design  
-title: "mindnet – Knowledge Design"
+**Version:** 1.4.0 (aktualisiert 2025-10-06)
-id: "design-knowledge-architecture"
-type: "guide"
-status: "active"
-version: "1.3.0"
-created: 2025-09-02
-updated: 2025-09-09
-tags: ["type/guide","area/mindnet","topic/obsidian","topic/knowledge-architecture"]
-owner: "Ich"
----
 
-# mindnet – Knowledge Design
+## 1. Gesamtziel und Systemverständnis
 
-## 1. Gesamtziel, Anspruch & Nutzen
+**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.
 
-**Ziel:**  
+**Zentrale Ziele**
-*mindnet* ist ein persönliches Wissensnetzwerk, das **alle** relevanten Informationen über mein Leben, meine Werte, Projekte, Erfahrungen, Pläne und Erkenntnisse **strukturiert** erfasst. Es bleibt **portabel** (Markdown + YAML), ist **parser-freundlich**, und so gestaltet, dass Tools (Obsidian + Dataview, Embeddings/Vektorsuche via Qdrant, Agenten) es **maschinenlesbar** nutzen können.
+- 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  
 
-**Anspruch an die Struktur:**
+**Prinzipien**
-- **Stabil**: robuste IDs, deterministische Dateinamen, konsistente Feldnamen  
+- **Deterministisch:** IDs, Hashes und Edges wiederholbar  
-- **Atomar**: eine Kernaussage/ein zentrales Thema pro Datei (keine Sammelcontainer)  
+- **Portabel:** Markdown + YAML  
-- **Erweiterbar**: neue Typen jederzeit möglich (ohne Migrationsschmerz)  
+- **Robust:** fehlertoleranter Parser  
-- **Portabel**: pures Markdown + YAML → funktioniert in Obsidian, Git, Parsern  
+- **Idempotent:** keine Duplikate bei Re-Import  
-- **Vernetzbar**: systematische Links/Backlinks bilden ein navigierbares Wissensnetz  
+- **Erweiterbar:** neue Typen und Edge-Arten ohne Migration  
-- **Parser-freundlich**: wiederkehrende Abschnittsüberschriften, klare Enums  
-
-**Nutzen / Einsatzzwecke:**
-- **Schnelles Wiederfinden**: Dataview-Abfragen, Filter, Dashboards  
-- **LLM-gestütztes Arbeiten**: Q&A mit Kontext-Zitaten aus Chunks (RAG)  
-- **Agenten**: Vorschläge für Verbindungen/Struktur; Auflösen von „unresolved links“  
-- **Projektnavigation**: Aufgabenbeziehungen, Abhängigkeiten  
-- **Langfristiges Gedächtnis**: Lebens-/Projektchronik (rückblickend und planend)  
-- **Automatisierung**: Vektor-Index (Qdrant), Embeddings, LLM-Q&A, Agenten-Workflows  
 
 ---
 
 ## 2. YAML-Frontmatter-Schema
 
-> **Pflichtfelder:** `title`, `id`, `type`, `status`, `created`, `tags`  
+| Feld | Typ | Beschreibung |
-> **Empfohlen:** `updated`, `area`, `project`, `priority`, `aliases`, `lang`, `people`, `depends_on`, `source` u. a.
+|-------|-----|--------------|
+| `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 |
 
-### 2.1 Feldübersicht
+**Pflichtfelder:** `title`, `id`, `type`, `status`, `created`  
-
+**Optionale Felder:** alle übrigen
-| Feld               | Typ                           | Bedeutung                                                                 |
-|--------------------|-------------------------------|---------------------------------------------------------------------------|
-| `title`            | string                        | Menschlich lesbarer Titel                                                 |
-| `id`               | string (slug/identifier)      | **Stabile** ID; referenzierbar über Wikilinks                             |
-| `type`             | enum                          | `concept`, `thought`, `experience`, `task`, `project`, `journal`, `person`, `meeting`, `milestone`, … |
-| `status`           | enum                          | `draft` \| `active` \| `done` \| `archived`                               |
-| `created`          | date                          | Erstellungsdatum (ISO)                                                    |
-| `updated`          | date                          | Letzte Änderung (ISO)                                                     |
-| `area`             | string                        | Themen-/Lebensbereich (z. B. „mindnet“, „gesundheit“, „familie“)          |
-| `project`          | string                        | Projekt-/Arbeitskontext                                                   |
-| `tags`             | list<string>                  | Taxonomische Tags (präfixiert, s. Abschnitt 4)                            |
-| `aliases`          | list<string>                  | Alternative IDs/Titel (Slug-Resolver)                                     |
-| `lang`             | string                        | Sprache, optional (z. B. `de`, `en`)                                      |
-| `priority`         | enum/int                      | Priorität, optional (`low`/`med`/`high` oder 1–5)                         |
-| `due`, `effort_min`| date/int                      | Für Aufgaben/Projekte (Fälligkeit, Aufwand in Minuten)                    |
-| `people`           | list<string>                  | Beteiligte Personen/IDs                                                   |
-| `depends_on`       | list<string>                  | Abhängigkeiten auf andere IDs                                             |
-| `source`           | string                        | Quelle (Artikel, Buch, Video, …)                                          |
-| `slug`             | string                        | Stabiler Pfad-/Dateiname, falls abweichend                                |
-
-### 2.2 Konventionen
-- `id` ist **menschenlesbar** (Slug), eindeutig im Vault; `aliases` dienen als Fallback-IDs.  
-- Datumsformat: ISO `YYYY-MM-DD`.  
-- Keine duplizierten Tags; Präfixe nutzen (`area/…`, `type/…`, `topic/…`).  
-- Frontmatter nur Fakten/Metadaten, **keine** ausufernden Inhalte (die stehen in den Body-Abschnitten).
-
-### 2.3 Minimalbeispiel Frontmatter
-
-    title: "Gedanke: YAML-Standards"
-    id: thought-yaml-standards
-    type: thought
-    status: draft
-    created: 2025-09-02
-    updated: 2025-09-09
-    area: mindnet
-    project: project-mindnet
-    tags: [area/mindnet, type/thought, topic/yaml]
-    aliases: [yaml-gedanken]
-    lang: de
-
-### 2.4 Enum-Werte (Beispiele)
-- `type`: `concept`, `thought`, `experience`, `task`, `project`, `journal`, `person`, `meeting`, `milestone`, `manifesto`  
-- `status`: `draft`, `active`, `done`, `archived`  
-- `priority`: `low`, `med`, `high` oder 1–5
 
 ---
 
-## 3. Dateinamen-Konventionen
+## 3. Dateinamen und Ordner
-- `YYYY-MM-DD_title.md` oder `slug.md`.  
+
-- Pfade **relativ** zum Vault; keine absoluten Pfade (einheitliche Slashes `/`).  
+- Format: `YYYY-MM-DD_title.md` oder `slug.md`  
-- Verzeichnisse nach eigener Ordnung, empfohlen: `10_thoughts/`, `20_concepts/`, `30_projects/`, `40_journal/`, …  
+- Strukturierte Ordner:  
+  - `10_thoughts/`, `20_concepts/`, `30_projects/`, `40_experiences/`, …  
+- Alle Pfade relativ; Unterstriche statt Leerzeichen  
 
 ---
 
-## 4. Tagging-Regeln & Taxonomie
+## 4. Link- und Edge-Design
-- Präfixe verwenden: `area/…`, `type/…`, `topic/…`, `status/…`.  
+
-- Möglichst **keine** losen Ein-Wort-Tags ohne Präfix (verhindert Wildwuchs).  
+**Verlinkungen**
-- Für Dataview konsistente Namespaces beibehalten (z. B. `topic/llm`, `topic/lernen`).  
+- 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. Backlink- & Link-Regeln
+## 5. Chunking-Modell
 
-- **Wikilinks**: `[[stabile-id]]` oder `[[Titel|stabile-id]]`  
+**Chunk-Datenstruktur**
-- Im **Fließtext** verlinken (Forwardlinks); am **Ende** optional **„Mögliche Verbindungen“** redaktionell pflegen:
+| 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) |
 
-    ## Mögliche Verbindungen
+**Chunking-Regeln (aus `chunking_strategy.md`)**
-    - [[concept-persoenliches-leitbild]]
+- Trennung nach Absätzen, Überschriften, Listen, Tabellen  
-    - [[project-mindnet]]
+- Token-Zielgröße 350–500 (max 600)  
-
+- Overlap: 30–40 % für semantische Kohärenz  
-- **Linkrichtung:** „aufwärts“ (Detail → Konzept/Leitbild) und „seitwärts“ (verwandte Knoten).  
+- Overlap wird in `window` integriert, sodass `text ≠ window`  
-- Optional zusätzliche **ID-Relationen** im YAML (`related_ids`) für Parser.  
-- **Unresolved Links:** Links auf noch nicht existierende Ziele sind zulässig; der Importer schreibt `status: unresolved`-Edges (später durch Resolver/Agent heilbar).
 
 ---
 
-## 5.1 Edge-Typen & Semantik (Graph)
+## 6. Hash-Strategie und Änderungsverfolgung
 
-Beziehungen werden als **Edges** mit neuem Payload-Schema gespeichert:
+**Zweck:** Nur bei realer Inhaltsänderung re-indexieren
 
-    kind        : "belongs_to" | "next" | "prev" | "references" | "backlink" | "unresolved"
+| Umgebungsvariable | Beschreibung |
-    source_id   : ID des Quellknotens (Chunk- oder Note-ID)
+|--------------------|--------------|
-    target_id   : ID des Zielknotens  (Note- oder Chunk-ID)
+| `MINDNET_HASH_COMPARE` | Vergleichsquelle (`Body`, `Full`, `Frontmatter`) |
-    scope       : "chunk" | "note"
+| `MINDNET_HASH_SOURCE` | Rohtext vs. geparst (`raw` / `parsed`) |
-    note_id     : Owner-Note des Edges (für schnelles Filtern/Purge)
+| `MINDNET_HASH_NORMALIZE` | Normalisierung (`canonical` / `none`) |
-    status      : optional, z. B. "unresolved"
 
-**Kantenarten**
+**Basismodi**
-- **belongs_to** — *Chunk → Note*  
+- `body` → Nur Textkörper  
-  Jeder Chunk gehört zu **genau einer** Note. *Scope:* `chunk`.  
+- `frontmatter` → Nur Metadaten  
+- `full` → Kombination  
+- Hash = SHA-256(canonicalized_input)
 
-- **prev / next** — *Chunk → Chunk*  
+Bei Änderung: Re-Import, neue Embeddings, Edges werden aktualisiert.  
-  Lineare Reihenfolge innerhalb derselben Note; **symmetrisch** angelegt (d. h. `prev` und `next` konsistent). *Scope:* `chunk`.  
-
-- **references** — *Chunk → Note*  
-  Aus `[[Wikilinks]]` oder Markdown-Links im **Chunk-Text** (präzise Herkunft). *Scope:* `chunk`.  
-
-- **backlink** — *Note → Note*  
-  Automatisch generierte Gegenkante zu `references` (pro Note **dedupliziert**). *Scope:* `note`.  
-
-- **unresolved**  
-  Edge mit `status: "unresolved"`, wenn `target_id` (noch) nicht existiert. Wird später vom Resolver/Agent ersetzt.  
-
-- **Optional:** `references:note` — *Note → Note*  
-  Zusätzliche Forwardlinks auf Note-Ebene; standardmäßig **deaktiviert**, um Doppelzählungen mit `references` (Chunk-Scope) zu vermeiden. Aktivierung per ENV/Flag möglich.
-
-**Performanzhinweise (Qdrant)**
-- Edges werden dedupliziert über `(kind, source_id, target_id, scope)`.  
-- `note_id` ist Pflichtfeld im Edge-Payload (Owner-Note).  
-- Payload-Indizes für Qdrant anlegen:
-
-      edges  : kind (KEYWORD), scope (KEYWORD), source_id (KEYWORD), target_id (KEYWORD), note_id (KEYWORD)
-      chunks : note_id (KEYWORD), chunk_index (INTEGER)
-      notes  : note_id (KEYWORD)
 
 ---
 
-## 6. Abschnitts-Konventionen im Body
+## 7. Qdrant-Speicherstruktur
 
-Einheitliche Überschriften erleichtern Parser, Chunking und Abfragen. Typ-spezifische Empfehlungen:
+| 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` | — |
 
-- **Gedanke (`thought`)**  
+**Upsert-Strategie**
-  `## Zusammenfassung` · `## Begründung / Details` · `## Belege / Quellen` · `## Nächste Schritte` · `## Mögliche Verbindungen`
+- Idempotente UUIDv5-IDs  
+- Keine Duplikate durch deterministische Signaturen  
+- `purge-before-upsert` zur Bereinigung  
 
-- **Erfahrung (`experience`)**  
+**Indizes**
-  `## Kontext` · `## Beobachtung` · `## Interpretation` · `## Implikationen` · `## Mögliche Verbindungen`
+- notes: `note_id`, `hash_signature`  
-
+- chunks: `note_id`, `chunk_index`  
-- **Aufgabe (`task`)**  
+- edges: `(kind, source_id, target_id, scope)`
-  `## Checkliste` · `## Notizen` · `## Nächste Schritte` · `## Mögliche Verbindungen`
-
-- **Projekt (`project`)**  
-  `## Scope` · `## Arbeitspakete` · `## Risiken & Gegenmaßnahmen` · `## Status / Fortschritt` · `## Mögliche Verbindungen`
-
-- **Journal (`journal`)**  
-  `## Tageszusammenfassung` · `## Highlights` · `## Learnings` · `## Mögliche Verbindungen`
-
-- **Meeting (`meeting`)**  
-  `## Agenda` · `## Notizen` · `## Entscheidungen` · `## Aufgaben` · `## Mögliche Verbindungen`
 
 ---
 
-## 7. Abbildung persönlicher Inhalte auf Typen
+## 8. Fehler-Toleranz und Parser-Robustheit
 
-**Richtlinien:**  
+- UTF-8 mit Fallback: ersetzt ungültige Bytes (`errors="replace"`)  
-- Wähle den Typ nach **Hauptintention** (Definition, Gedanke, Beobachtung, Aufgabe, Projekt, …).  
+- Ignoriert Nullbytes, BOM, exotische Zeilenenden  
-- **Konzepte** (`concept`): langlebige Definitionen, Prinzipien, Leitbilder.  
+- Erkennt defekte oder leere YAML-Header und überspringt sie  
-- **Gedanken** (`thought`): explorative Ideen, noch nicht stabil (können später bei Reife in `concept` überführt werden).  
+- Logt Problemfälle (`read_markdown failed`, `make_note_payload returned non-dict`)  
-- **Erfahrungen** (`experience`): Beobachtungen & Learnings aus der Praxis.  
+- Bei Fehlern: Import → warn → continue  
-- **Aufgaben** (`task`): konkrete, umsetzbare To-dos mit `due`/`effort_min`.  
-- **Projekte** (`project`): Ziele, Deliverables, Arbeitspakete, Abhängigkeiten.  
-- **Journal** (`journal`): tagesbasierte Notizen, Reflexionen, Reiseberichte.  
-- **Personen** (`person`): Kontakte, Profile, Bezüge, Gespräche.  
-- **Meetings** (`meeting`): Agenda, Notizen, Entscheidungen, Folgeaufgaben.  
-- **Meilensteine** (`milestone`): wichtige Wendepunkte im Lebens-/Projektverlauf.
 
 ---
 
-## 8. Beispiel-Notizen
+## 9. Tests & Validierung
 
-### 8.1 Gedanke (`thought`) – Beispiel
+**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`  
 
-**Frontmatter**
+**Erwartete Ergebnisse**
-
+- Alle Notes werden erkannt  
-    title: "Gedanke: Übungen für tiefe Arbeit"
+- `window ≠ text` bei > 60 % der Chunks  
-    id: thought-deep-work-uebungen
+- Roundtrip-Vergleich liefert „OK“  
-    type: thought
+- Edge-Anzahl entspricht Modell (belongs_to = #Chunks, next/prev ≈ #Chunks – 1)  
-    status: active
-    created: 2025-08-21
-    updated: 2025-09-05
-    area: lernen
-    project: project-self-improvement
-    tags: [area/lernen, type/thought, topic/fokus]
-    aliases: [deep-work-ideen]
-    lang: de
-
-**Body (Ausschnitt)**
-
-    ## Zusammenfassung
-    Kurze tägliche Routinen (z. B. Timer-Blöcke, Ablenkungslog) erhöhen meinen Fokus.
-
-    ## Begründung / Details
-    - 25–45 Min Timerblöcke mit 5 Min Pause
-    - Ablenkungen sofort notieren
-    - Abschluss-Log am Ende des Tages
-
-    ## Mögliche Verbindungen
-    - [[concept-deep-work]]
-    - [[project-productivity-week]]
-
-### 8.2 Konzept (`concept`) – Beispiel
-
-**Frontmatter**
-
-    title: "Konzept: Deep Work"
-    id: concept-deep-work
-    type: concept
-    status: active
-    created: 2024-05-14
-    updated: 2025-08-01
-    area: lernen
-    tags: [area/lernen, type/concept, topic/fokus]
-    aliases: [konzept-tiefe-arbeit]
-    lang: de
-
-**Body (Ausschnitt)**
-
-    ## Definition
-    Tiefe Arbeit = kognitiv anspruchsvolle Arbeit ohne Ablenkung.
-
-    ## Belege / Quellen
-    - Buch: Cal Newport – Deep Work
-
-    ## Mögliche Verbindungen
-    - [[thought-deep-work-uebungen]]
-
-### 8.3 Aufgabe (`task`) – Beispiel
-
-**Frontmatter**
-
-    title: "Task: Wochenplanung erstellen"
-    id: task-week-planning
-    type: task
-    status: active
-    created: 2025-09-07
-    updated: 2025-09-07
-    due: 2025-09-11
-    effort_min: 45
-    area: organisation
-    project: project-productivity-week
-    tags: [area/organisation, type/task, topic/planung]
-    lang: de
-
-**Body (Ausschnitt)**
-
-    ## Checkliste
-    - Ziele der Woche definieren
-    - 5 Fokusblöcke eintragen
-    - 2 Lerneinheiten terminieren
-
-    ## Mögliche Verbindungen
-    - [[project-productivity-week]]
-    - [[thought-deep-work-uebungen]]
 
 ---
 
-## 9. Schrittweise Migration bestehender freier Notizen
+## 10. Export & Roundtrip-Verhalten
 
-1. **Frontmatter ergänzen** (min. `id`, `title`, `type`, `status`, `created`, `tags`).  
+- `export_markdown.py` erzeugt identische Markdown-Dateien  
-2. **Abschnittsstruktur** an Typ anpassen (Konventionen s. Abschnitt 6).  
+- Schreibt YAML + Body in korrekter Reihenfolge  
-3. **Wikilinks** im Body setzen (statt bloßer Erwähnungen).  
+- Roundtrip-Prüfung (`compare_vaults.py`) validiert:
-4. **Tags normalisieren** (Präfixe, Kleinschreibung, keine Dubletten).  
+  - vollständigen Body  
-5. **Aliases** angeben, falls Notiz zuvor unter anderem Namen existierte.  
+  - unveränderte Hash-Signatur  
-6. **Testlauf**: Import (Dry-Run), danach Apply, Audit/Validate prüfen.  
+  - gleiche Chunkzahl  
 
 ---
 
-## 10. Dataview-Beispiele (direkt nutzbar)
+## 11. Graph-Schicht und WP-04-Integration
 
-**Aktive Gedanken der letzten 30 Tage**
+- Qdrant fungiert als Graph-Backend  
-
+- `graph/service.py` (WP-04): stellt API für Mehrhop-Abfragen bereit  
-    TABLE title, created, updated, area
+- Unterstützt:  
-    FROM "10_thoughts"
+  - `expand(note_id, hops=2)`  
-    WHERE type = "thought" AND status = "active" AND created >= date(today) - dur(30 days)
+  - `resolve_unresolved()`  
-    SORT updated DESC
+  - `neighbors(kind=…)`  
-
+- Grundlage für spätere **Retriever-Funktionen** (LLM / Agenten)  
-**Offene Tasks mit Fälligkeit**
-
-    TABLE title, due, effort_min, project, area
-    FROM "30_tasks"
-    WHERE type = "task" AND status = "active" AND due
-    SORT due ASC
-
-**Konzepte je Topic**
-
-    TABLE title, area, tags
-    FROM "20_concepts"
-    WHERE contains(tags, "type/concept")
-    GROUP BY choice(regexreplace(join(filter(tags, (t) => startswith(t, "topic/")), ", "), "^topic/", ""))
-
-**Verknüpfungskandidaten (redaktionell, nicht automatisch)**  
-*(Liste am Ende der jeweiligen Notiz in „Mögliche Verbindungen“)*
 
 ---
 
-## 11. Validierung & Pflege
+## 12. Agenten- und LLM-Integration
 
-- **Linter/Validator** prüfen Pflichtfelder und Wertebereiche (Enums, ISO-Datum).  
+**Retriever-Pipeline**
-- **Resolver** löst `unresolved`-Edges, wenn neue Notizen/Aliases entstehen.  
+1. Suche top-k Chunks (cosine distance)  
-- **Idempotente Re-Imports**: Hash-Steuerung konfigurierbar:  
+2. Erweiterung um Edges (`references`, `backlinks`)  
-  - `MINDNET_HASH_MODE`: `body` \| `frontmatter` \| `body+frontmatter` (Default: `body`)  
+3. Kontext-Assembling via `window`-Text  
-  - `MINDNET_HASH_NORMALIZE`: `canonical` \| `none` (Default: `canonical`)  
+4. Prompt-Generierung  
-- **Edge-Invarianten** (Audit):  
+
-  - `belongs_to == #Chunks`  
+**Agent-Use-Cases**
-  - `next == prev == Σ(max(chunks_in_note−1, 0))`  
+- Automatisches Tagging (`type`, `status`)  
-  - `references (chunk) == Σ(Chunk-Wikilinks)`  
+- Vorschläge für neue Edges  
-  - `backlink == Σ(eindeutige Wikilinks je Note)`  
+- Auflösen von `unresolved`-Referenzen  
-- **Roundtrip-Test**: Import → Export → Diff muss Body verlustfrei rekonstruieren.
+- Auto-Import externer Quellen (MediaWiki, PDFs, Webseiten)  
 
 ---
 
-## 12. Qdrant-Ablage & Indizes
+## 13. Erweiterbarkeit
 
-**Collections**  
+- Neue Edge-Typen: `inspired_by`, `relates_to`, `contradicts`  
-- `{prefix}_notes` – Vektor optional (Nullvektor oder Zentroid), Payload inkl. Frontmatter & `fulltext`  
+- Neue Note-Typen: `decision`, `resource`, `recommendation`  
-- `{prefix}_chunks` – 384d Embedding je Chunk, Payload inkl. `text`, `chunk_index`, `note_id`  
+- Embedding-Engines austauschbar (MiniLM → LaBSE → E5)  
-- `{prefix}_edges` – 1d Dummy-Vektor, Payload im neuen Schema (s. 5.1)
+- Versionierte Chunking-Strategien (`chunk_config.py`)  
-
-**IDs & Idempotenz**  
-- Deterministisch/UUIDv5 über stabile Schlüssel (`note_id`, `chunk_id = note_id#cNN`, `edge_id` aus `(kind, source_id, target_id, scope)`)  
-- Re-Imports erzeugen keine Duplikate (Upsert)
-
-**Payload-Indizes (Performance)**
-
-    notes  : note_id (KEYWORD)
-    chunks : note_id (KEYWORD), chunk_index (INTEGER)
-    edges  : kind (KEYWORD), scope (KEYWORD), source_id (KEYWORD), target_id (KEYWORD), note_id (KEYWORD)
-
-**Delete/Purge**  
-- Selektives Löschen in Edges/Chunks per `note_id`-Filter (schnell, sicher).  
-- `--sync-deletes` (geplant): Qdrant→Vault Diffs gezielt entfernen (mit Dry-Run).
 
 ---
 
-## 13. LLM/RAG & Agenten – Arbeitsweise (Überblick)
+## 14. Qualitätssicherung und Best Practices
 
-**Retriever (Hybrid)**  
+- Validierung vor Upsert  
-1) **kNN (Chunks)** in Qdrant → Top-k Kandidaten (Semantik).  
+- Keine Leer-Chunks  
-2) **Nachbarschafts-Expand** (1 Hop) über Edges (`belongs_to`, `references`, `backlink`) → zusätzliche Kontexte.  
+- Vollständige Metadaten in Notes  
-3) **Rerank** (optional BM25/LLM-score).  
+- Tests in `tests/` automatisch ausführbar (`run_e2e_roundtrip.sh`)  
-4) **Prompt** mit Zitaten/Belegen (Verweis auf `path` + Abschnittstitel).
+- Ergebnis: „Roundtrip OK“ und `verify_chunks_integrity` = OK  
-
-**Agentisches Einordnen (neue Inputs)**  
-- **Chunking + Embedding** → **kNN-Kandidaten**  
-- Klassifikation (`type`, `area`, `project`) via Heuristik/LLM  
-- Edge-Vorschläge: `references` (Semantik + geteilte Tags/Area), `belongs_to` (beste Einordnung)  
-- Falls kein Ziel existiert → `unresolved` erzeugen oder **Stub-Note** anlegen  
-- **Human-in-the-loop**: Vorschläge bestätigen, dann Commit via Importer
-
-**Graph-Layer (optional, empfohlen)**  
-- Zusätzliche SQLite/Postgres-Tabellen `nodes/edges/aliases` für 2–3-Hop-Queries, Pfadsuche, Zählungen.  
-- Importer pflegt Qdrant **und** SQL (UPSERT).  
-- Graph-Features (Degree, Communities, optional PageRank) regelmäßig berechnen und als Felder in `notes.payload` speichern.
 
 ---
 
-## 14. Versions- & Änderungsrichtlinien
+## 15. Änderungsverlauf
 
-- **Kleine Änderungen** direkt in der bestehenden Notiz (Frontmatter `updated` anpassen).  
+**v1.4.0 (2025-10-06)**
-- **Große Strukturänderungen** (z. B. neuer Typ) als neue Notiz mit Verweis; alte Note verlinken/archivieren (`status: archived`).  
+- Neu: `window` vs `text` Feld in `mindnet_chunks`  
-- **IDs nie recyceln** (Konstanz für Referenzen und Edges).  
+- Neu: Hash-Modi (`body`, `frontmatter`, `full`) mit Env-Steuerung  
-- **Aliases** nutzen, wenn sich Titel/Slug ändert (Resolver kann beides auflösen).  
+- Neu: Baseline-Modus für Vergleich  
-- **Commit-Meldungen** im Git prägnant strukturieren:  
+- Parser → fehlertolerant (UTF-8 replace)  
-  - `feat(note): …` · `fix(frontmatter): …` · `chore(tags): …` · `refactor(structure): …`
+- 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  
 
 ---
-
-## 15. Typen-Kurzreferenz
-
-- **concept** — Definitionen, Leitbilder, Prinzipien  
-  Empfohlene Abschnitte: *Definition*, *Beispiele*, *Belege*, *Mögliche Verbindungen*
-
-- **thought** — Ideen, Entwürfe, Skizzen  
-  Abschnitte: *Zusammenfassung*, *Details*, *Nächste Schritte*, *Mögliche Verbindungen*
-
-- **experience** — Beobachtungen, Learnings  
-  Abschnitte: *Kontext*, *Beobachtung*, *Interpretation*, *Implikationen*, *Mögliche Verbindungen*
-
-- **task** — konkrete To-dos  
-  Felder: `due`, `effort_min`; Abschnitte: *Checkliste*, *Notizen*, *Mögliche Verbindungen*
-
-- **project** — Ziele, Deliverables, Arbeitspakete  
-  Abschnitte: *Scope*, *Arbeitspakete*, *Risiken*, *Status*, *Mögliche Verbindungen*
-
-- **journal** — tagesbasierte Einträge  
-  Abschnitte: *Tageszusammenfassung*, *Highlights*, *Learnings*, *Mögliche Verbindungen*
-
-- **person** — Kontakte, Profile  
-  Felder: `people` (Selbst-/Fremd-ID), *Notizen*, *Mögliche Verbindungen*
-
-- **meeting** — Termine, Protokolle  
-  Abschnitte: *Agenda*, *Notizen*, *Entscheidungen*, *Aufgaben*, *Mögliche Verbindungen*
-
-- **milestone** — Wendepunkte  
-  Abschnitte: *Kontext*, *Bedeutung*, *Verknüpfungen*
-
----
-
-## 16. Erweiterungen
-
-- Neue Typen (z. B. `decision`, `recommendation`, `resource`) können ohne Bruch ergänzt werden.  
-- Personalisierung durch zusätzliche Properties (`values`, `goals`) in Frontmatter.  
-- Internationale Inhalte: `lang` pflegen, optional **mehrsprachige** Embeddings (z. B. mE5).
-
----
-
-## 17. Anhang – Beispiele & Snippets
-
-**Beispiel: YAML-Frontmatter für Projekt**
-
-    title: "Projekt: Produktivität Woche 37"
-    id: project-productivity-week
-    type: project
-    status: active
-    created: 2025-09-08
-    updated: 2025-09-09
-    area: organisation
-    tags: [area/organisation, type/project, topic/planung]
-    people: [ich]
-    depends_on: [concept-deep-work]
-    lang: de
-
-**Beispiel: Redaktions-Sektion (keine Kanten-Erzeugung)**
-
-    ## Mögliche Verbindungen
-    - [[concept-wochenplanung]]
-    - [[thought-deep-work-uebungen]]
-    - [[journal-2025-09-08]]
-
-**CLI: Import & Audit**
-
-    # Dry-Run Import
-    python3 -m scripts.import_markdown --vault ./vault
-
-    # Apply mit strenger Hash-Erkennung (jede Änderung zählt)
-    python3 -m scripts.import_markdown --vault ./vault --apply --hash-normalize none
-
-    # Audit Edges vs. Erwartungen
-    python3 -m scripts.audit_edges_vs_expectations --vault ./vault
-
----
-
-## 18. Glossar
-
-- **Alias**: alternativer Name/Slug, der auf dieselbe Note verweist  
-- **Backlink**: automatisch erzeugte Gegenkante zu `references` (Note-Scope)  
-- **Chunk**: semantisch sinnvoller Textabschnitt einer Note, inkl. Embedding  
-- **Owner-Note**: Note, zu der ein Edge gehört (`note_id` im Edge-Payload)  
-- **Resolver**: Prozess/Script, das `unresolved`-Edges bei späterer Ziel-Existenz heilt  
-
----
-
-## 19. Verweise
-
-- `chunking_strategy.md` – Details zu Chunkgrößen, Overlaps, Abschnittsregeln  
-- `schemas/note.schema.json` – Validierung von Frontmatter‐Feldern  
-- Import/Export-Skripte: `scripts/import_markdown.py`, `scripts/export_markdown.py`  
-- Qdrant-Client/Setup: `app/core/qdrant.py`, `app/core/qdrant_points.py`
-
----
-
-## 20. Änderungsverlauf
-
-- **1.3.0 (2025-09-09)**  
-  - Edge-Politik präzisiert: `references` (Chunk-Scope), `backlink` (Note-Scope), `references:note` optional.  
-  - `note_id` als Pflichtfeld im Edge-Payload (Owner).  
-  - Qdrant-Payload-Indizes ergänzt (Performanz).  
-  - Beispiele & Dataview-Snippets erweitert.
-
-- **1.2.0 (2025-09-02)**  
-  - Erstfassung des Knowledge-Designs.