mindnet/docs/knowledge_design.md

# mindnet – Knowledge Design  
**Version:** 1.5.0 (aktualisiert 2025-11-09)

> Dieses Dokument beschreibt das Ziel, die Architektur, die Datenmodelle sowie die Regeln und Prozesse für den Aufbau von **mindnet** – einem persönlichen, lokal betriebenen Wissensnetz, das auf Markdown-Quellen, Graph-Beziehungen und Vektor-Suche basiert. Es soll die Persönlichkeit, Werte und Erfahrungen des Besitzers widerspiegeln und künftig Antworten generieren, die diese Perspektive authentisch berücksichtigen.

---

## 1. Ziel von mindnet

**1.1 Zweck**  
- mindnet dient als persönliches Wissensnetz, das Erfahrungen, Werte, Prinzipien, Ziele und prägenden Ereignisse langfristig strukturiert.  
- Es ermöglicht spätere Einsichten in Entscheidungen und Entwicklungen und kann in Zukunft für die Familie (z. B. Kinder) eine nachvollziehbare Quelle sein.

**1.2 Leitidee**  
- Statt einer reinen Dokumentablage wird Wissen durch **Knoten (Notes/Chunks)** und **Kanten (Edges)** vernetzt.  
- Antworten sollen **persönlich** kontextualisiert werden (Perspektive, Konditionierung, Persönlichkeit).

**1.3 Langfristigkeit**  
- Stabiler, zukunftsfähiger Entwurf; spätere Massenmigrationen sollen vermieden werden.  
- Architektur unterstützt schrittweise Erweiterung (neue Quellen, neue Agenten, neue Regeln).

---

## 2. Zielarchitektur (High Level)

- **Datenquellen:** Markdown-Vault (Obsidian-kompatibel), perspektivisch weitere Quellen (MediaWiki, PDFs, Web-Exporte, E-Mail-Auszüge).  
- **Import-Pipeline:** Parser → Frontmatter/Body → Chunking → Embedding → Qdrant (Notes/Chunks/Edges).  
- **Speicher:** Qdrant (Vektoren + Payload + Textindex), Dateien bleiben im Filesystem (Quelle ist Referenz).  
- **Graph-Schicht:** Edges explizit modelliert (Typ, Richtung, Evidenz, Confidence); optionale abgeleitete Edges per Batch-Job.  
- **Retriever/Composer:** Hybrid-Retrieval (Vektor + Filter + optional Volltext), Komposition zu Antwortkandidaten.  
- **Erklärbarkeit:** Begründungspfade (Top-Chunks, Graph-Kette, Provenienz).  
- **Schnittstellen:** REST/CLI, n8n-Glue, lokale LLM-Anbindung (Ollama).

---

## 3. Collections in Qdrant

- `mindnet_notes` – Note-Metadaten (id, title, type, path, timestamps, tags, …).  
- `mindnet_chunks` – inhaltstragende Segmente inkl. Vektoren und Textindex.  
- `mindnet_edges` – Beziehungen (src/dst, relation, direction, evidence, confidence, …).  
- (optional) `mindnet_people` – strukturierte Personenobjekte (Eigen-/Fremdbezug).

---

## 4. Identitäten & IDs

- **Deterministische IDs** für Notes (z. B. Namespace-basierte UUIDv5) und stabile, ableitbare IDs für Chunks/Edges.  
- ID-Stabilität ist Voraussetzung für Idempotenz (Re-Imports ohne Duplikate).

---

## 5. Frontmatter & Typen

- Pflichtfelder: `id`, `title`, `type`, `created`, `updated`, `tags`, `source_path`.  
- Note-Typen (Auszug): `experience`, `principle`, `value`, `goal`, `role`, `persona`, `plan`, `project`, `journal`, `reference`, `translation`.  
- **types.yaml** definiert Regeln/Defaults je Typ und für Relationstypen (siehe Abschnitt 10).

---

## 6. Chunking-Strategie

- Satz- bis Absatz-Chunks, moderate Überlappung; Meta-Felder verweisen auf Note/Quelle.  
- Named Vectors (z. B. `content`, optional `title`, `tags`) ermöglichen hybride Scores.

---

## 7. Embeddings & Vektoren

- Einheitliche Metrik (cosine), reproduzierbares Embedding-Setup.  
- Konsistenz über Zeit durch Versionsfeld (`embedding_model`, `embedding_version`).

---

## 8. Volltext & Filter

- Textindex auf `mindnet_chunks.body` für exakte Term/Operator-Queries.  
- Payload-Filter zur schnellen Einschränkung (tags, types, time-buckets, visibility u. a.).

---

## 9. Edges – Beziehungen

- **Explizit**: Jede tatsächliche Beziehung wird als Kante gespeichert (kein Workaround).  
- Felder u. a.: `src_id`, `dst_id`, `relation`, `direction`, `confidence (0–1)`, `evidence` (Chunk-IDs), `created_at`, `updated_at`.  
- **edge_defaults** liefern **Interpretations-Hints** (Gewichte, Symmetrie, Transitivität) und parametrisieren abgeleitete Edges; sie **ersetzen** keine Originalkanten.

---

## 10. Regeln & Policies (types.yaml)

- Per Typ/Relation:  
  - Default-Eigenschaften (Gewicht, Directedness, Symmetrie, Transitivität).  
  - Scoring-Hooks für Graph-Kontext im Retriever.  
  - (später) Privacy-Hooks je Relation (Mindest-Visibility).

---

## 11. Retrieval & Ranking (Komposition)

- Hybrid: Vektor-Score + Filter + optional BM25/Volltext.  
- Zeitgewicht (Decays) und Graph-Kontext werden komponiert (Formel siehe 16.3).  
- Konfiguration über `.env`/`config.yaml` (gewichts- und halbwertszeit-basiert).

---

## 12. Erklärbarkeit

- „Warum-Pfad“: Top-Chunks mit Score-Zerlegung (Vektor/Time/Graph), Graph-Kette, Provenienz.  
- Mehrschichtige Narrative (Kindheit/Erlebnisse, Werte/Prinzipien, Ziele/Leitbild, Gegenwart).

---

## 13. Betrieb & Sicherheit

- Lokal auf Single-Node starten (Backups via Snapshots).  
- Zugriff nur intern/Reverse-Proxy; Festplattenverschlüsselung OS-seitig.  
- Migrationspfad zu Qdrant-Distributed (Shards, Replikation) einplanen.

---

## 14. Qualität & Monitoring

- Offline-Eval-Sets, Telemetrie (lokal), Drift-Checks, manuelle Reviews.  
- Kennzahlen: Hit-Rate, Overlap, Quellen-Alter, Erklärungspfad-Nutzung.

---

## 15. Offene Punkte

- Ausdetaillierung `types.yaml` (Relationen, Hooks).  
- UI-Oberfläche für Erklärpfade und Provenienz.  
- Batch-Jobs für abgeleitete Edges.

---

## 16. Ergänzungen 2025-11-09 (v1.5.0)

**Kontext:** Basierend auf den neuen Rahmenbedingungen (nur Deutsch; perspektivische externe Abfragen; einheitliche Vertraulichkeit mit Option auf feinere Stufen; Recency-Priorisierung als Default; Regeln später konfigurierbar; zunächst lokale Speicherung mit optionaler Migration; heutige Hardware, später skalierbar; hohe Erklärbarkeit mit mehreren Erklärungsebenen) werden folgende Entscheidungen und Erweiterungen getroffen. Alle bisherigen Inhalte bleiben gültig und werden **nicht** verändert.

### 16.1 Sprach- und Inhaltsrichtlinie (nur Deutsch)
- `lang: "de"` als verpflichtendes Feld in allen Note-, Chunk- und Edge-Payloads.
- Für spätere Mehrsprachigkeit **nicht** die Collection splitten, sondern ein Feld `lang` + optional `lang_original` behalten; Translation-Artefakte als eigener `type: translation` (verweisend auf `source_id`).

### 16.2 Vertraulichkeit & Sichtbarkeit
- Heute: einheitliche Stufe `visibility: "internal"`.
- Vorausschauend: reservierte Felder in allen Payloads
  - `visibility`: `"public" | "internal" | "restricted"`
  - `sensitivity`: Integer 0–3 (0 = unkritisch, 3 = hochsensibel)
  - `acl`: Liste erlaubter Rollen/Personen-IDs (App-Layer erzwingt Filter vor Query).
- Access-Control erfolgt **im Applikations-Layer** mittels Qdrant-Payload-Filtern (`must: [ { key: "visibility", match: { any: [...] }}, ... ]`); Qdrant bleibt „dumm“ in Bezug auf ACL.

### 16.3 Recency-Modell & Ranking (konfigurierbar)
- Default: **Zeitnähe** priorisieren (sanfte Abwertung älterer Inhalte).
- Im Retrieval kombinieren wir:
  1) Vektor-Score (cosine) aus Qdrant
  2) Zeitgewicht `time_decay = exp( - ln(2) * age_days / half_life_days )`
  3) Graph-Kontext aus Edges (z. B. Degree, Path-Hops zum Anker „Ich/Persona“)
- Konfigurierbare Gewichte (per `.env` oder `config.yaml`):
  ```text
  FINAL_SCORE = w_vec * norm(vec_score) 
              + w_time * time_decay
              + w_graph * graph_context_score
  # Vorschlag: w_vec=0.70, w_time=0.20, w_graph=0.10; half_life_days=365
  ```
- Für Fragen, die „zeitlos“ sind, kann `half_life_days = inf` gesetzt werden (kein Decay).

### 16.4 Erklärbarkeit („Warum diese Antwort?“)
- Jeder Antwort wird ein **Erklärpfad** mitgegeben (optional im UI):
  - Top-Chunks (mit Score-Zerlegung w_vec/w_time/w_graph)
  - **Kausalpfad** im Graphen: `Note → Edge(relation, confidence) → Note …`
  - **Provenienz** (Quelle, Erstellungszeit, letzte Änderung).
- Ein **Multi-Layer-Explanations**-Modul ordnet Beiträge zu: Kindheit/Erlebnisse, Werte & Prinzipien, aktuelle Ziele/Leitbild, Gegenwartskontext.

### 16.5 Qdrant-Schemata (Ergänzungen, rückwärtskompatibel)
- **Collections** bleiben: `mindnet_notes`, `mindnet_chunks`, `mindnet_edges` (+ `mindnet_people` falls noch nicht vorhanden).
- Gemeinsame Zusatzfelder (alle Payloads):
  - `lang: "de"`
  - `visibility`/`sensitivity`/`acl` (s. 16.2)
  - `created_at` (ISO-8601), `updated_at` (ISO-8601), `age_days` (App-seitig berechnet)
- **Chunks**:
  - Named-Vectors (z. B. `"content"`, optional `"title"`, `"tags"` für Hybrid-Scores).
  - `text_index` auf `body` für BM25-ähnliche Volltextsuche (Qdrant-Textindex).
  - `recency_group`: Jahr-Monat `YYYY-MM` (ermöglicht Pre-Filter für „letzte N Monate“).
- **Edges** (explizit, keine Workarounds):
  - Felder: `src_id`, `dst_id`, `relation`, `direction`, `confidence` (0–1), `evidence` (Chunk-IDs), `created_at`, `updated_at`.
  - **edge_defaults** bleiben als **Interpretations-Hints**: z. B. `default_weight`, `symmetry`, `transitivity`. Sie ersetzen **nicht** echte Kanten, sondern parametrisieren abgeleitete/zusätzliche Kantenbildung.
  - Abgeleitete Edges: optionaler Batch-Job erzeugt *ergänzende* Kanten entlang `types.yaml`-Regeln (z. B. Backlinks, „inspired_by“ aus Zitaten), niemals statt der Originalkanten.

### 16.6 Regeln & Typen (konfigurierbar)
- `types.yaml` erweitert um:
  - Relationstypen mit Default-Eigenschaften (`weight`, `directed`, `symmetric`, `transitive`).
  - **Scoring-Hooks**: pro Relation optionaler Einfluss auf `graph_context_score`.
  - **Privacy-Hooks**: pro Relation Minimal-Visibility (z. B. Beziehungen zu Personen sind mindestens `internal`).

### 16.7 Speicher- & Betriebsstrategie (heute lokal, später skalierbar)
- **Heute**: Single-Node Qdrant mit HNSW-Index, Text-Index und Payload-Filtern; regelmäßiges Backup (Snapshots).
- **Morgen**: Migrationspfad in **Qdrant-Distributed** (Shards, ggf. Replikation) bei Bedarf; Parameter-Gleichheit sichern (named-vectors, Metrik, HNSW-Param).
- **Sicherheit**: Zugriff nur über internes Netz/Reverse-Proxy, Auth vor Qdrant; Festplatten-Verschlüsselung auf OS-Ebene (z. B. LUKS).

### 16.8 Persona-Layer („meine Essenz“)
- Eigenständiger **Persona-Knoten** (z. B. Note `person/lars`), verbunden mit:
  - Werten/Prinzipien, Leitbild, prägenden Erlebnissen, Zielen, Rollen.
  - Jede Antwort kann gegen diesen Knoten **kontextualisiert** werden (Graph-Pfadnähe).
- Feld `persona_weight` in Chunks/Notes zur Priorisierung persönlicher Relevanz.

### 16.9 Evaluierung & Qualitätssicherung
- **Offline-Sets** aus echten Fragen (inkl. gewünschter Perspektiven) mit erwarteten Top-Quellen.
- **Telemetrie** (lokal): Query-Arten, Treffer-Overlaps, Zeitgewicht-Effekte, „Warum-Pfad“ genutzt/ignoriert.
- **Drift-Checks**: Anteil sehr alter vs. neuer Quellen in Antworten; manuelle Reviews.

### 16.10 Offene Punkte / Nächste Schritte
1) `types.yaml` um Relationseigenschaften erweitern (s. 16.6).  
2) Retriever-Komposition inkl. Zeitgewicht (s. 16.3) implementieren.  
3) Explanations-Pfad inkl. Provenienzoberfläche (s. 16.4) im UI.  
4) Feld-Erweiterungen in Import-Pipelines (`lang`, `visibility`, Zeitfelder).  
5) Optional: Batch-Job für abgeleitete Edges nach Regeln (ergänzend, nicht ersetzend).