Lars/mindnet
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 21 Wiki Activity
a4873b3d45
mindnet/docs/knowledge_design.md
Lars be090a43f2
All checks were successful
Deploy mindnet to llm-node / deploy (push) Successful in 3s
Details
Dateien nach "docs" hochladen
2025-11-09 19:45:53 +01:00

11 KiB
Raw Blame History

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): 
    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).