Dateien nach "docs" hochladen

docs/mindnet_functional_architecture.md

@@ -0,0 +1,192 @@
+# Mindnet – Fachliche Architektur
+**Version:** 2.0 • **Datum:** 2025-11-09 • **Autor:** Fachkonzept (gemeinsam mit Owner)
+
+---
+
+## 0. Zweck dieses Dokuments
+Dieses Dokument beschreibt **Fachdomäne, Funktionsräume, Prozesse und Regeln** von *mindnet*. Es ergänzt die technische Architektur und macht die ursprünglichen Ziele, Designentscheidungen, Anti‑Patterns und Umsetzungsstrategien explizit nachvollziehbar.
+
+---
+
+## 1. Vision & Leitplanken
+- **Essenz bewahren:** Entscheidungen, Erlebnisse, Werte, Prinzipien und Konditionierungen so strukturieren, dass sie später erklärbar rekonstruiert werden können.  
+- **Antworten im eigenen Stil:** Ergebnisse sollen die Persönlichkeit des Owners widerspiegeln (Sprache: **Deutsch**).  
+- **Vertraulichkeit:** Aktuell einheitlich, aber mit **Stufen** (public/internal/sensitive) erweiterbar.  
+- **Zeitliche Priorisierung:** Standard: jüngere Inhalte leichter gewichten; Ausnahmen konfigurierbar.  
+- **Lokal zuerst**, später skalierbar.
+
+---
+
+## 2. Fachliches Datenmodell
+### 2.1 Kernobjekte
+- **Note**: Eintrag im Wissensnetz (z. B. Konzept, Projekt, Erfahrung, Ereignis, Aufgabe).  
+- **Chunk**: semantischer Abschnitt einer Note (Antwortbaustein).  
+- **Edge**: gerichtete Beziehung zwischen Notes/Chunks (mit Typ, Gewicht, Quelle).  
+- **Run**: Importlauf (Audit).  
+- **Config**: aktive Regel‑ und Typkonfigurationen.
+
+### 2.2 Typen & Semantik (Auszug)
+- `concept`: Begriff/These/Prinzip.  
+- `experience`: Erlebnis/Beobachtung (zeitlich verankert).  
+- `project`: Vorhaben mit Zielen/Abhängigkeiten.  
+- `task`: Arbeitseinheit.  
+- (erweiterbar: `event`, `decision`, `person`, `place`, `quote` …)
+
+### 2.3 Relationen (fachlich)
+- `references`: verweist inhaltlich auf …  
+- `related_to`: thematische Nähe/Assoziation.  
+- `depends_on`: fachliche/kausale Abhängigkeit.  
+- `belongs_to`: Zugehörigkeit (Teil‑von, Kapitel‑zu).  
+- `derived_from`: abgeleitet (z. B. Schluss aus Erfahrung).  
+- `inspired_by`: Impuls/Idee aus Quelle.  
+- `supports` / `contradicts`: argumentative Beziehung.
+
+---
+
+## 3. Funktionsräume
+1. **Kurativer Raum**  
+   - Schreiben/Überarbeiten von Notizen (Obsidian Templates, Frontmatter‑Guides).  
+   - Plausibilisierung: Pflichtfelder, Dublettencheck, Warnungen (z. B. fehlende Relationen).
+
+2. **Graphischer Raum**  
+   - Relationen setzen (declared), Vorschläge prüfen (inferred).  
+   - Subgraph‑Explorer je Frage/Entscheidung.
+
+3. **Antwort‑Raum**  
+   - Query‑Typen: *Faktenabruf*, *Erlebnisbasiert erklären*, *Planung/Entscheidung begründen*.  
+   - Erklärpfad: Chunks → Kanten → Zeitfaktoren → Typgewichte.
+
+4. **Governance‑Raum**  
+   - Sichtbarkeit/ACL, Qualitätsflags, Review‑Queues.  
+   - Versionsjournal, Import‑Runs, Config‑Historie.
+
+---
+
+## 4. Fachliche Regeln
+### 4.1 Frontmatter‑Schema (Mindeststandard)
+```yaml
+id: "{deterministic}"
+title: "…"
+type: "concept|experience|project|task|…"
+created: "YYYY-MM-DD"
+modified: "YYYY-MM-DD"
+visibility: "internal"        # default
+retriever_weight: null        # optional override
+chunk_profile: null           # optional override
+tags: ["…"]
+edge_hints:
+  - relation: references
+    target: "note-id-or-path"
+  - relation: depends_on
+    target: "…"
+```
+
+### 4.2 Typregeln (aus types.yaml)
+- `chunk_profile`, `retriever_weight`, `edge_defaults` werden je Typ **automatisch** angewandt.  
+- Aus `edge_defaults` abgeleitete Kanten werden **persistiert** (`source='rule'`).
+
+### 4.3 Zeitgewichtung
+- Default: **Exponential Decay** mit globalem λ; Override per `time_weight_override` möglich.  
+- Erlebnisse (`experience`) erhalten standardmäßig leicht höheren **Base‑Impact** im Score, um Persönlichkeit abzubilden.
+
+### 4.4 Qualitätsregeln
+- Jede Note soll **mind. eine Relation** besitzen.  
+- **Konflikte** (contradicts) werden nicht gefiltert, sondern sichtbar gemacht (mit Hinweis).  
+- **Sichtbarkeit**: Antworten aus `sensitive` nur bei expliziter Freigabe.
+
+---
+
+## 5. Use Cases (repräsentativ)
+1. **„Warum habe ich 2019 X entschieden?“**  
+   - Abfrage auf `decision` + temporale Nachbarschaft zu `experience`/`principle`.  
+   - Ausgabe mit Erklärpfad: *Erlebnis → Prinzip → Projekt → Entscheidung*.
+
+2. **„Plane ein Trainingsprogramm“**  
+   - Query kombiniert Konzepte/Erfahrungen/Projekte → Graph‑Walk + Typgewichtung, priorisiert jüngere Erkenntnisse.
+
+3. **„Welche Ereignisse haben mein Leitbild geprägt?“**  
+   - Subgraph über `derived_from`/`inspired_by` Ketten + Zeitachsen‑Visualisierung.
+
+---
+
+## 6. Anti‑Patterns (vermeiden)
+- **Edges ohne Relation** („Dot‑Kanten“) – verhindern jede sinnvolle Auswertung.  
+- **Nur Vektor‑Suche** ohne Graph / Zeitfaktor – verfälscht Persönlichkeit.  
+- **Freies Tag‑Chaos** ohne Typregeln – mindert Reproduzierbarkeit.  
+- **Heimliche Workarounds** (z. B. Felder mit Mehrdeutigkeit) – erschweren spätere Automatisierung.
+
+---
+
+## 7. Umsetzungsstrategie & Roadmap
+### Phase 1 (Jetzt)
+- Pflicht‑Frontmatter, deterministische IDs, Ingestion v2 (Chunks/Edges **persistiert**).  
+- types.yaml + retrieval.yaml live‑fähig; Import‑Run‑Audit.  
+- Tests (Parser/Chunker/Edge‑Rules), Regression auf Chunk‑Mengen.
+
+### Phase 2
+- Hybrid‑Retrieval mit Graph‑Boosts, Explain‑Traces in API.  
+- Subgraph‑Explorer, Governance‑Views (Review‑Queues).
+
+### Phase 3
+- ML‑gestützte Edge‑Vorschläge, temporale Graphanalysen, Reasoning‑Chains.  
+- ACL/Sharing‑Modelle, Export/Archiv‑Pipelines.
+
+---
+
+## 8. Beispiel‑Konfigurationen
+### 8.1 types.yaml (Beispiel – wie technisch)
+```yaml
+version: 1.0
+types:
+  concept:
+    chunk_profile: medium
+    edge_defaults: ["references", "related_to"]
+    retriever_weight: 0.33
+  task:
+    chunk_profile: short
+    edge_defaults: ["depends_on", "belongs_to"]
+    retriever_weight: 0.8
+  experience:
+    chunk_profile: medium
+    edge_defaults: ["derived_from", "inspired_by"]
+    retriever_weight: 0.9
+  project:
+    chunk_profile: long
+    edge_defaults: ["references", "depends_on"]
+    retriever_weight: 0.95
+```
+
+### 8.2 retrieval.yaml
+```yaml
+relation_weights:
+  references: 1.0
+  related_to: 0.6
+  depends_on: 1.2
+  belongs_to: 0.8
+  derived_from: 1.1
+  inspired_by: 0.8
+  supports: 1.0
+  contradicts: -0.9
+mixing:
+  alpha: 0.45
+  beta:  0.25
+  gamma: 0.20
+  delta: 0.07
+  epsilon: 0.03
+time_decay:
+  lambda: 0.0025
+```
+
+---
+
+## 9. Governance & Nachvollziehbarkeit
+- **Decision Log** (ADR‑ähnlich): jedes Regel‑/Schema‑Update mit Begründung.  
+- **Import‑Protokolle** versioniert, inkl. geänderter Dateien, Chunk‑/Edge‑Zahlen.  
+- **Explainability Standard** in jeder Antwort.
+
+---
+
+## Anhang A: Glossar
+- **Chunk‑Profil**: Regelset zur Textteilung.  
+- **Rule‑Edge**: automatisch erzeugte Kante auf Basis von Typregeln.  
+- **Declared Edge**: explizit gesetzte Kante aus der Quelle.

docs/mindnet_technical_architecture.md

@@ -0,0 +1,474 @@
+# Mindnet – Technische Architektur
+**Version:** 2.0 • **Datum:** 2025-11-09 • **Autor:** Systemarchitektur (gemeinsam mit Owner)
+
+---
+
+## 0. Zweck dieses Dokuments
+Dieses Dokument beschreibt die **technische Architektur** von *mindnet* so präzise, dass ein erfahrener Engineer sie 1:1 implementieren kann. Es konsolidiert die bisherigen Überlegungen, eliminiert redundante/unklare Passagen und ergänzt fehlende Details (Datenmodell, Indizes, Import‑Pipelines, Scoring, Erklärbarkeit, Skalierung, Betrieb). Gültige Inhalte aus früheren Fassungen bleiben erhalten (siehe **Anhang A: Originalinhalt**).
+
+> **Kernziele:**  
+> - Persönliches Wissensnetz mit langlebiger Semantik (Notizen, Erlebnisse, Entscheidungen).  
+> - Antworten, die **erklärbar** auf Erfahrungen, Konditionierung und Persönlichkeit beruhen.  
+> - **Konfigurierbare Regeln** (Zeitgewichtung, Relationstypen, Typ‑Profile).  
+> - **Lokal** betreibbar, später **skalierbar** (on‑prem → Rechenzentrum/Cloud).  
+> - **Deterministisch**, idempotent, auditierbar.
+
+---
+
+## 1. Systemkontext (High Level)
+- **Quellen:** Obsidian‑Vault (Markdown + Frontmatter), künftig MediaWiki/HTML/PDF/E-Mail/Images.  
+- **Ingestion:** Validator → Parser → Chunker (Profile) → Embedding → Graph‑& Payload‑Indexierung.  
+- **Speicher:** Qdrant als Vektorstore + Payload (JSON), ergänzt um Dateimetadaten.  
+- **APIs:** FastAPI (Read/Write), Tools (mindnet_query, mindnet_subgraph), n8n‑Glue.  
+- **Retrieval/Reasoning:** Hybrid (Vektor + Keyword + Graph‑Walk) mit konfigurierbaren Scoring‑Regeln und **Erklärpfad**.  
+- **Ops:** Deterministische IDs, Versions/Provenance‑Felder, Observability, Tests.
+
+---
+
+## 2. Zielarchitektur (Komponenten)
+### 2.1 Ingestion Layer
+1. **Frontmatter‑Validator**  
+   - Erzwingt Pflichtfelder: `id`, `title`, `type`, `created`, `modified`  
+   - Optionale Felder: `tags`, `visibility`, `relevance`, `time_weight_override`, `retriever_weight`, `chunk_profile`, `sources`, `aliases`, `edge_hints`.  
+   - Validiert `type` gegen **types.yaml** (Konfiguration).
+
+2. **Parser**  
+   - Extrahiert: reinen Text, Überschriften, Querverweise (`[[Note]]`, Markdown‑Links), Zitate/Quellen.  
+   - Normalisiert Unicode, trennt Codeblöcke, Zitate, Aufzählungen.
+
+3. **Chunker** (profilgesteuert)  
+   - Profile: `short` (~300–500 Token), `medium` (~700–1000), `long` (~1200–1600).  
+   - Regeln: Absatz‑, Überschriften‑, semantische Grenzen, Überschneidung ~10–15% für Kontextkohärenz.  
+   - Chunk‑Header speichert: `{note_id, path, type, idx, section_hierarchy, tokens, chunk_profile}`.
+
+4. **Embedding**  
+   - Standard: MiniLM‑384d (lokal über Ollama/TEI), konfigurierbar (`embedding.model`, `dim`).  
+   - Persistiert Vektor + **Payload**.
+
+5. **Edge‑Builder**  
+   - **Declared Edges**: aus expliziten Links/Referenzen in der Quelle.  
+   - **Inferred Edges (Rules)**: aus `types.yaml.edge_defaults` **und** Heuristiken (z. B. Abschnittstitel „Bezug“, „siehe auch“).  
+   - Beide Ebenen als **Edges** persistiert mit `source='declared' | 'rule'`, **kein bloßer Dot‑Marker**.
+
+### 2.2 Storage Layer (Qdrant)
+**Collections (empfohlen):**
+- `mindnet_notes` (1 Vektor je Note, optional)  
+- `mindnet_chunks` (**primärer Suchraum**)  
+- `mindnet_edges` (Graph als Payload‑Dokumente)  
+- `mindnet_runs` (Import‑Läufe, Audit/Provenance)  
+- `mindnet_configs` (aktive Konfigurationen, z. B. `types.yaml` Schnappschuss)
+
+**Beispiel‑Schemas:**
+
+```yaml
+# mindnet_chunks.payload
+id: string                 # deterministic (UUIDv5 über prefix+path+idx)
+note_id: string            # FK mindnet_notes.id
+type: string               # z. B. concept|task|experience|project|event …
+title: string
+path: string               # Pfad im Vault
+collection: string         # Präfix/Namespace
+created: string            # ISO‑Datum
+modified: string           # ISO‑Datum
+chunk_idx: int
+chunk_profile: string      # short|medium|long
+retriever_weight: float    # aus types.yaml oder Note‑Override
+time_weight: float         # berechnet (Decay) oder Override
+section: string            # Überschrift/Gliederung
+text: string               # Rohtext des Chunks
+tokens: int
+hash: string               # content_hash (idempotent)
+visibility: string         # public|internal|sensitive
+source: {                  # Provenance
+  repo: string|null,
+  path: string,
+  commit: string|null,
+  import_run_id: string
+}
+```
+
+```yaml
+# mindnet_edges.payload
+id: string                 # deterministic (UUIDv5 über src_id + dst_id + relation + source)
+src_id: string             # id (Note ODER Chunk)
+dst_id: string             # id (Note ODER Chunk)
+src_kind: string           # note|chunk
+dst_kind: string           # note|chunk
+relation: string           # references|related_to|depends_on|belongs_to|derived_from|inspired_by|mentions|contradicts|supports …
+weight: float              # Standard 1.0; typenspezifische Offsets möglich
+source: string             # declared|rule|ml
+evidence: string|null      # Textausschnitt/Link der Ableitung
+created: string
+import_run_id: string
+visibility: string
+```
+
+**Indizes (Qdrant):**
+- Vektorindex auf `mindnet_chunks` (HNSW)  
+- Payload‑Indizes:  
+  - `type` (keyword), `visibility` (keyword), `created/modified` (datetime), `note_id` (keyword)  
+  - optional: **Full‑Text** auf `text` (Qdrant payload text index) für Hybrid‑Suche
+
+### 2.3 Retrieval & Scoring
+**Hybrid‑Pipeline (empfohlen):**
+1. **Lexikalische Kandidaten** (FTS auf `text`, `title`, `aliases`) – k_l.  
+2. **Vektor‑Kandidaten** (ANN auf Embeddings) – k_v.  
+3. **Graph‑Expansion**: 1–2 Hops über `mindnet_edges` mit relation‑spezifischen Boosts.  
+4. **Re‑Ranking** (finale Score):  
+   - `S = α·sim + β·kw + γ·G + δ·time_decay + ε·type_weight + ζ·recency_boost_overrides`  
+   - `type_weight` = `retriever_weight` aus **types.yaml** oder Note‑Override.  
+   - `time_decay` = `exp(−λ·age_days)`; λ global/konfigurierbar; Override per Frontmatter möglich.  
+   - **Erklärbarkeit:** Speichere die Summanden + Top‑Edges als **evidence** im Query‑Log.
+
+**Relation‑Gewichte (Defaultvorschlag):**
+```yaml
+relation_weights:
+  references: 1.0
+  related_to: 0.6
+  depends_on: 1.2
+  belongs_to: 0.8
+  derived_from: 1.1
+  inspired_by: 0.8
+  supports: 1.0
+  contradicts: -0.9
+```
+
+### 2.4 Konfiguration (types.yaml + config.yaml)
+```yaml
+version: 1.0
+types:
+  concept:    { chunk_profile: medium, edge_defaults: [references, related_to],    retriever_weight: 0.33 }
+  task:       { chunk_profile: short,  edge_defaults: [depends_on, belongs_to],   retriever_weight: 0.80 }
+  experience: { chunk_profile: medium, edge_defaults: [derived_from, inspired_by],retriever_weight: 0.90 }
+  project:    { chunk_profile: long,   edge_defaults: [references, depends_on],   retriever_weight: 0.95 }
+retrieval:
+  alpha: 0.45   # sim
+  beta:  0.25   # keyword
+  gamma: 0.20   # graph
+  delta: 0.07   # time decay
+  epsilon: 0.03 # type weight
+time_decay:
+  lambda: 0.0025   # ~ Halbwertzeit ≈ 277 Tage
+visibility_defaults: public
+```
+
+### 2.5 Determinismus, Versionierung, Idempotenz
+- **IDs:** UUIDv5 über `{collection_prefix}:{path}:{chunk_idx}` (Chunks) bzw. `{collection_prefix}:{path}` (Notes).  
+- **content_hash:** SHA256 über normalisierte Inhalte (Unicode NFC, Whitespace‑Policy, Überschriften‑Normalisierung).  
+- **Import‑Lauf (`mindnet_runs`)**: `{run_id, started_at, finished_at, config_hash, files_seen, files_changed, errors}`.  
+- **Idempotenz:** nur `changed` bei `content_hash`‑Abweichung.
+
+### 2.6 Erklärbarkeit (Audit Trail)
+- Jede Antwort liefert: Top‑Chunks, Summanden des Scores, **angetretene Kanten** inkl. Relation & Gewicht, Zeitfaktor.  
+- Persistiere Query‑Logs (optional): `{query, filters, topk, decision_trace, timestamp}`.
+
+### 2.7 Sicherheit & Datenschutz
+- **visibility**: `public|internal|sensitive`, Query‑Filter standardmäßig `internal`.  
+- Optionale **ACL**‑Schicht: Nutzer/Gruppen, Freigabe je Note/Chunk/Edge.  
+- **Redaktions‑Flags**: `needs_review`, `draft`, `private_journal` (werden standardmäßig ausgeschlossen).
+
+### 2.8 Skalierung & Betrieb
+- **Shards/Replicas** (Qdrant): 1/1 lokal; 2/2 in DC/Cloud.  
+- **Snapshots/Backups**: Qdrant Snapshot + Vault‑Repo Snapshot (rsync/borg).  
+- **Observability**: Prometheus‑Exporter (API Latenz, Import‑Dauer, Chunks/Edges pro Lauf), strukturierte Logs (JSON).  
+- **Tests**: deterministische Golden‑Files für Parser/Chunker; Contract‑Tests für API; Offline‑Eval für Retrieval.
+
+---
+
+## 3. Implementierungsleitfaden (konkret)
+### 3.1 Collections anlegen (Qdrant)
+- `mindnet_chunks(dim=384, distance=cosine)`  
+- `mindnet_notes(dim=384, distance=cosine)` (optional, falls Note‑Level‑Suche gewünscht)  
+- `mindnet_edges(dim=0)` (reiner Payload‑Store; kein Vektor)  
+- Payload‑Indizes: siehe 2.2
+
+### 3.2 Import‑Pipeline (CLI)
+1. **Scan** Vault → valide Dateien.  
+2. **Make Note Payload** (inkl. Typ‑Regeln; `retriever_weight`/`chunk_profile` aus **types.yaml**, Override per Frontmatter).  
+3. **Chunken** gemäß Profil + `chunk_idx`.  
+4. **Edges bauen**: declared + rule‑inferred (duplizierte Kanten per ID‑Determinismus verhindern).  
+5. **Upsert**: Notes → Chunks → Edges (in dieser Reihenfolge).  
+6. **Run‑Record** und **Config‑Schnappschuss** persistieren.
+
+### 3.3 Query‑API (FastAPI)
+- `POST /query`: text, filters({visibility, types, date_range}), topk, graph_hops, `explain=true`.  
+- `GET /subgraph/{id}`: Nachbarschaft, Relation‑Filter, Depth.  
+- `POST /admin/reindex` / `POST /admin/import`.
+
+### 3.4 Konfigurierbarkeit
+- `types.yaml` heiß ladbar (mit Versionsstempel); bei Änderung → `config_hash` & reimport optional.  
+- `retrieval.yaml` für Gewichte, Relation‑Boosts, Zeitdecay.
+
+---
+
+## 4. Migrations‑ und Qualitätsregeln
+- **Keine Workarounds**, die Semantik zerstören (z. B. „Dot‑Edge“ ohne Relation).  
+- **Explizite Kantenpersistenz**: *jede* Regelkante wird als `source='rule'` gespeichert.  
+- **Chunk‑Zahl**: Profiltreue sicherstellen; Regressionstest (z. B. 171 ➝ 59 = **Fehler** oder Profiländerung dokumentieren).  
+- **Provenance Pflicht**: `import_run_id` in Chunks/Edges setzen.
+
+---
+
+## 5. Offene Erweiterungen (vordenken)
+- **ML‑Edge‑Inference** (NER, Coref, TEI‑Reranking).  
+- **Reasoning‑Graph** (Motivationsketten: Kindheitserlebnis → Prinzip → Entscheidung).  
+- **Citations‑Fabric** (autom. Quellenkonsolidierung).  
+- **Temporale Graphabfragen** (Edges mit Zeitintervallen).
+
+---
+
+## Anhang A: Originalinhalt (unverändert, falls vorhanden)
+Der vollständige Originaltext aus `knowledge_design.md` bleibt hier als Referenz erhalten, damit keine implizite Aussage verloren geht.
+
+
+---
+
+# 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  
+
+---