Lars
be090a43f2
All checks were successful
Deploy mindnet to llm-node / deploy (push) Successful in 3s
217 lines
11 KiB
Markdown
217 lines
11 KiB
Markdown
# 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).
|