Lars/mindnet
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 21 Wiki Activity
27b404560c
mindnet/docs/03_Technical_References/03_tech_configuration.md
Lars 27b404560c Dokumentation WP20
2025-12-25 19:39:16 +01:00

18 KiB
Raw Blame History

doc_type audience scope status version context
technical_reference developer, admin configuration, env, registry, scoring, resilience active 2.8.0 Umfassende Referenztabellen für Umgebungsvariablen (inkl. Hybrid-Cloud & WP-76), YAML-Konfigurationen und die Edge Registry Struktur.

Konfigurations-Referenz

Dieses Dokument beschreibt alle Steuerungsdateien von Mindnet. In der Version 2.8 wurde die Konfiguration professionalisiert, um die Edge Registry, dynamische Scoring-Parameter (Lifecycle & Intent) sowie die neue Hybrid-Cloud-Resilienz zu unterstützen.

1. Environment Variablen (.env)

Diese Variablen steuern die Infrastruktur, Pfade und globale Timeouts.

Variable Default Beschreibung
QDRANT_URL http://localhost:6333 URL zur Vektor-DB API.
QDRANT_API_KEY (leer) Optionaler Key für Absicherung.
COLLECTION_PREFIX mindnet Namensraum für Collections (erzeugt {prefix}_notes etc).
VECTOR_DIM 768 Muss 768 sein (für Nomic Embeddings).
MINDNET_VOCAB_PATH (Pfad) Neu (WP-22): Absoluter Pfad zur 01_edge_vocabulary.md. Definiert den Ort des Dictionarys.
MINDNET_VAULT_ROOT ./vault Basis-Pfad für Datei-Operationen.
MINDNET_TYPES_FILE config/types.yaml Pfad zur Typ-Registry.
MINDNET_RETRIEVER_CONFIG config/retriever.yaml Pfad zur Scoring-Konfiguration.
MINDNET_DECISION_CONFIG config/decision_engine.yaml Pfad zur Router & Intent Config.
MINDNET_PROMPTS_PATH config/prompts.yaml Pfad zu LLM Prompts.
MINDNET_LLM_PROVIDER openrouter Neu (WP-20): Aktiver Provider (openrouter, gemini, ollama).
MINDNET_LLM_FALLBACK true Neu (WP-20): Aktiviert automatischen Ollama-Fallback bei Cloud-Fehlern.
MINDNET_LLM_RATE_LIMIT_WAIT 60.0 Neu (WP-76): Wartezeit in Sekunden bei HTTP 429 (Rate Limit).
MINDNET_LLM_RATE_LIMIT_RETRIES 3 Neu (WP-76): Anzahl Cloud-Retries vor lokalem Fallback.
GOOGLE_API_KEY (Key) API Key für Google AI Studio.
MINDNET_GEMINI_MODEL gemini-2.5-flash-lite Update 2025: Optimiertes Lite-Modell für hohe Quoten.
OPENROUTER_API_KEY (Key) API Key für OpenRouter Integration.
OPENROUTER_MODEL mistralai/mistral-7b-instruct:free Update 2025: Verifiziertes Free-Modell für strukturierte Extraktion.
MINDNET_LLM_MODEL phi3:mini Name des lokalen Chat-Modells (Ollama).
MINDNET_EMBEDDING_MODEL nomic-embed-text Name des Embedding-Modells (Ollama).
MINDNET_OLLAMA_URL http://127.0.0.1:11434 URL zum lokalen LLM-Server.
MINDNET_LLM_TIMEOUT 300.0 Timeout in Sekunden für LLM-Anfragen.
MINDNET_API_TIMEOUT 300.0 Globales API-Timeout für das Frontend.
MINDNET_LL_BACKGROUND_LIMIT 2 Traffic Control: Max. parallele Hintergrund-Tasks (Semaphore).
MINDNET_CHANGE_DETECTION_MODE full full (Text + Meta) oder body (nur Text).

2. Typ-Registry (types.yaml)

Steuert das Import-Verhalten, Chunking und die Kanten-Logik pro Typ.

2.1 Konfigurations-Hierarchie (Override-Logik)

Seit Version 2.7.0 gilt für chunking_profile und retriever_weight folgende Priorität:

  1. Frontmatter (Höchste Prio): Ein Wert direkt in der Markdown-Datei überschreibt alles.
  2. Type Config: Der Standardwert für den type aus types.yaml.
  3. Global Default: Fallback aus defaults in types.yaml.

2.2 Typ-Referenz & Stream-Logik (Vollständige Liste: 28 Typen)

Das System euriert Informationen in drei funktionalen Streams. Wähle den Typ danach aus, in welchem Bereich deines „Digitalen Zwillings“ die Information wirken soll.

2.2.1 Identity Stream (Der Kern / Das „Warum“)

Dieser Stream definiert deine stabilen Merkmale und inneren Kompasse.

Typ Gewicht Chunking Profil Zweck & Inhalt
value 1.00 structured_strict Fundamentale Werte und moralische Maßstäbe.
principle 0.95 structured_strict_L3 Handlungsleitlinien mit tiefer Hierarchie (H3-Split).
trait 1.10 structured_strict Charakterliche Stärken und Talente.
belief 0.90 sliding_short Tiefe Überzeugungen über dich und die Gesellschaft.
profile 0.70 structured_strict Rollenidentitäten (z. B. Vater, Mentor, Unternehmer).
need 1.05 sliding_smart_edges Psychologische Grundbedürfnisse (z. B. Autonomie, Bindung).
motivation 0.95 sliding_smart_edges Innere Antreiber und Quellen deiner Energie.
boundary 0.90 sliding_smart_edges Deine persönlichen Grenzen und Integritäts-Leitplanken.
bias 0.80 sliding_short Bekannte kognitive Verzerrungen und Denkfallen.

2.2.2 Action Stream (Die Dynamik / Das „Was“)

Dieser Stream umfasst alles, was auf Umsetzung, Planung und aktuelle Zustände zielt.

Typ Gewicht Chunking Profil Zweck & Inhalt
project 0.97 sliding_smart_edges Aktive Vorhaben mit Mission und Zielsetzung.
goal 0.95 sliding_smart_edges Strategische Nordsterne und Zielzustände.
decision 1.00 structured_strict Getroffene Entscheidungen (ADR-Logik).
risk 0.85 sliding_short Potenzielle Gefahren und Bedrohungsszenarien.
obstacle 1.00 structured_strict Aktuelle Hürden, Ängste und Blockaden.
task 0.80 sliding_short Operative Aufgaben und Definition of Done.
skill 0.90 sliding_smart_edges Fertigkeiten, Lernpfade und Meisterschaft.
habit 0.85 sliding_short Routinen, Automatismen und Verhaltensmuster.
idea 0.70 sliding_short Flüchtige Einfälle und Rohmaterial für Projekte.
state 0.60 sliding_short Momentane Verfassung, Stimmung und Energielevel.

2.2.3 History & Basis Stream (Die Evidenz / Das „Wann“)

Dieser Stream speichert deine Erlebnisse, Fakten und externes Wissen als Belege.

Typ Gewicht Chunking Profil Zweck & Inhalt
insight 1.20 sliding_smart_edges Hochrelevante Erkenntnisse und Verhaltensmuster.
experience 1.10 sliding_smart_edges Biografische Lektionen und prägende Erlebnisse.
event 0.60 sliding_standard Chronologische Protokolle und Ereignisse.
journal 0.80 sliding_standard Tägliche Logs und ungefilterte Gedanken.
person 0.50 sliding_standard Kontaktprofile und soziale Vernetzung.
source 0.50 sliding_standard Externe Quellen wie Bücher, Videos oder Artikel.
concept 0.60 sliding_smart_edges Fachbegriffe, Theorien und zeitloses Wissen.
glossary 0.40 sliding_short Kurze Begriffsdefinitionen.
default 1.00 sliding_standard Fallback für alle nicht klassifizierten Notizen.

Richtwert für W_{type}: 0.1 (minimale Relevanz/Filter) bis 1.0 (maximale Relevanz).

3. Retriever Config (retriever.yaml)

Steuert die Gewichtung der Scoring-Formel und die neuen Lifecycle-Modifier.

version: 1.2

scoring:
  # W_sem: skaliert den Term (semantic_score * retriever_weight)
  # Empfehlung Startwert: 1.0  → Semantik bleibt Hauptsignal
  semantic_weight: 1.0

  # W_edge: skaliert edge_bonus aus dem Subgraph
  # Empfehlung: 0.8  → Graph ist deutlich spürbar, aber überstimmt Semantik nicht komplett
  edge_weight: 0.8

  # W_cent: skaliert centrality_bonus (Knoten-Zentralität im Subgraph)
  # Empfehlung: 0.5  → zentrale Knoten werden bevorzugt, aber moderat
  centrality_weight: 0.5

# WP-22 Stellschraube: Lifecycle (Status-basiertes Scoring)
# Bonus für verifiziertes Wissen, Malus für Entwürfe
lifecycle_weights:
  stable: 1.2   # +20% Bonus
  active: 1.0   # Standardwert
  draft: 0.5    # -50% Malus
  system: 0.0   # Hard Skip via Ingestion

# Die nachfolgenden Werte überschreiben die Defaults aus app/core/retriever_config.
# Wenn neue Kantentypen, z.B. durch Referenzierung innerhalb einer md-Datei im vault anders gewichtet werden sollen, dann muss hier die Konfiguration erfolgen
edge_types:
  # --- KATEGORIE 1: LOGIK-BOOSTS (Relevanz-Treiber) ---
  # Diese Kanten haben die Kraft, das semantische Ranking aktiv umzugestalten.
  blocks: 1.6        # Kritisch: Risiken/Blocker müssen sofort sichtbar sein.
  solves: 1.5        # Zielführend: Lösungen sind primäre Suchziele.
  depends_on: 1.4    # Logisch: Harte fachliche Abhängigkeit.
  resulted_in: 1.4   # Kausal: Ergebnisse und unmittelbare Konsequenzen.
  followed_by: 1.3   # Sequenziell (User): Bewusst gesteuerte Wissenspfade.
  caused_by: 1.2     # Kausal: Ursachen-Bezug (Basis für Intent-Boost).
  preceded_by: 1.1   # Sequenziell (User): Rückwärts-Bezug in Logik-Ketten.

  # --- KATEGORIE 2: QUALITATIVER KONTEXT (Stabilitäts-Stützen) ---
  # Diese Kanten liefern wichtigen Kontext, ohne das Ergebnis zu verfälschen.
  guides: 1.1        # Qualitativ: Prinzipien oder Werte leiten das Thema.
  part_of: 1.1       # Strukturell: Zieht übergeordnete Kontexte (Parents) mit hoch.
  based_on: 0.8      # Fundament: Bezug auf Basis-Werte (kalibriert auf Safe-Retrieval).
  derived_from: 0.6  # Historisch: Dokumentiert die Herkunft von Wissen.
  uses: 0.6          # Instrumentell: Genutzte Werkzeuge, Methoden oder Ressourcen.

  # --- KATEGORIE 3: THEMATISCHE NÄHE (Ähnlichkeits-Signal) ---
  # Diese Werte verhindern den "Drift" in fachfremde Bereiche.
  similar_to: 0.4    # Analytisch: Thematische Nähe (oft KI-generiert).

  # --- KATEGORIE 4: SYSTEM-NUDGES (Technische Struktur) ---
  # Reine Orientierungshilfen für das System; fast kein Einfluss auf das Ranking.
  belongs_to: 0.2    # System: Verknüpft Chunks mit der Note (Metadaten-Träger).
  next: 0.1          # System: Technische Lesereihenfolge der Absätze.
  prev: 0.1          # System: Technische Lesereihenfolge der Absätze.

  # --- KATEGORIE 5: WEICHE ASSOZIATIONEN (Rausch-Unterdrückung) ---
  # Verhindert, dass lose Verknüpfungen das Ergebnis "verwässern".
  references: 0.1    # Assoziativ: Einfacher Querverweis oder Erwähnung.
  related_to: 0.05   # Minimal: Schwächste thematische Verbindung.

4. Edge Typen & Registry Referenz

Die EdgeRegistry ist die Single Source of Truth für das Vokabular.

4.1 Dateistruktur & Speicherort

Die Registry erwartet eine Markdown-Datei an folgendem Ort:

  • Standard-Pfad: <MINDNET_VAULT_ROOT>/01_User_Manual/01_edge_vocabulary.md.
  • Custom-Pfad: Kann via .env Variable MINDNET_VOCAB_PATH überschrieben werden.

4.2 Aufbau des Dictionaries (Markdown-Schema)

Die Datei muss eine Markdown-Tabelle enthalten, die vom Regex-Parser gelesen wird.

Erwartetes Format:

| System-Typ (Canonical) | Erlaubte Aliasse (User) | Beschreibung |
| :--- | :--- | :--- |
| **`based_on`** | `basiert_auf`, `fundament` | Fundament: B baut auf A auf. |
| **`caused_by`** | `ausgelöst_durch`, `wegen` | Kausalität: A löst B aus. |

Regeln für die Spalten:

  1. Canonical: Muss fett gedruckt sein (**type** oder **type**). Dies ist der Wert, der in der DB landet.
  2. Aliasse: Kommagetrennte Liste von Synonymen. Diese werden beim Import automatisch zum Canonical aufgelöst.
  3. Beschreibung: Rein informativ für den Nutzer.

4.3 Verfügbare Kanten-Typen (System-Standard)

System-Typ (Canonical) Erlaubte Aliasse (User) Beschreibung
caused_by ausgelöst_durch, wegen, ursache_ist Kausalität: A löst B aus.
derived_from abgeleitet_von, quelle, inspiriert_durch Herkunft: A stammt von B.
based_on basiert_auf, fundament, grundlage Fundament: B baut auf A auf.
solves löst, beantwortet, fix_für Lösung: A ist Lösung für Problem B.
part_of teil_von, gehört_zu, cluster Hierarchie: Kind -> Eltern.
depends_on hängt_ab_von, braucht, requires, enforced_by Abhängigkeit: A braucht B.
blocks blockiert, verhindert, risiko_für Blocker: A verhindert B.
uses nutzt, verwendet, tool Werkzeug: A nutzt B.
guides steuert, leitet, orientierung Soft-Dependency: A gibt Richtung für B.
followed_by danach, folgt, nachfolger, followed_by Prozess: A -> B.
preceeded_by davor, vorgänger, preceded_by Prozess: B <- A.
related_to siehe_auch, kontext, thematisch Lose Assoziation.
similar_to ähnlich_wie, vergleichbar Synonym / Ähnlichkeit.
references (Kein Alias) Standard-Verweis (Fallback).
resulted_in ergebnis, resultat, erzeugt Herkunft: A erzeugt Ergebnis B

ACHTUNG! Die Kantentypen belongs_to, next und prev dürfen nicht vom Nutzer gesetzt werden

5. Decision Engine (decision_engine.yaml)

Die Decision Engine fungiert als zentraler Orchestrator für die Intent-Erkennung und das dynamische Retrieval-Routing. Sie bestimmt, wie das System auf eine Nutzeranfrage reagiert, welche Informationstypen bevorzugt werden und wie der Wissensgraph für die spezifische Situation verformt wird.

5.1 Intent Recognition: Dual-Path Routing

Das System nutzt ein zweistufiges Verfahren, um die Absicht des Nutzers zu identifizieren:

  1. Fast Path (Keyword Trigger): Das System scannt die Anfrage nach definierten trigger_keywords. Wird ein Treffer gefunden, wird die entsprechende Strategie sofort ohne LLM-Einsatz gewählt.
  2. Slow Path (LLM Router): Wenn kein Keyword matcht und llm_fallback_enabled: true gesetzt ist, analysiert ein LLM die Nachricht mittels Few-Shot Prompting.

LLM Router Konfiguration

Der Router nutzt den llm_router_prompt, um Anfragen in eine der fünf Kern-Strategien (FACT, DECISION, EMPATHY, CODING, INTERVIEW) zu klassifizieren.

Einstellung Wert Beschreibung
llm_fallback_enabled true Aktiviert die KI-basierte Klassifizierung, falls Keywords fehlen.
llm_router_prompt (Template) Enthält die Strategie-Definitionen und Few-Shot Beispiele für den LLM-Entscheidungsweg.

5.2 Strategie-Mechaniken (Graph Shaping)

Jede Strategie definiert drei Hebel, um das Ergebnis des Retrievers zu beeinflussen:

  • inject_types: Erzwingt die Einbindung bestimmter Notiz-Typen (z. B. value bei Entscheidungen), auch wenn diese semantisch eine geringere Ähnlichkeit aufweisen.
  • edge_boosts: Erhöht die Gewichtung spezifischer Kanten-Typen in der Scoring-Formel. Dies ermöglicht es dem Graphen, die Textsuche situativ zu "überstimmen".
  • prepend_instruction: Injiziert eine spezifische Systemanweisung in das LLM-Prompt, um den Antwortstil anzupassen (z. B. "Wäge Fakten gegen Werte ab").

5.3 Übersicht der Strategien

Strategie Fokus Bevorzugte Kanten (edge_boosts) Injektionstypen
FACT Wissensabfrage & Definitionen part_of (2.0), composed_of (2.0), similar_to (1.5) (Keine)
DECISION Rat, Strategie & Abwägung blocks (2.5), solves (2.0), risk_of (2.5) value, principle, goal, risk
EMPATHY Emotionale Resonanz based_on (2.0), experienced_in (2.5), related_to (2.0) experience, belief, profile
CODING Programmierung & Syntax implemented_in (3.0), uses (2.5), depends_on (2.0) snippet, reference, source
INTERVIEW Erfassung neuer Daten (Keine) (Keine)

5.4 Der Interview-Modus & Schemas

Die Strategie INTERVIEW dient der strukturierten Datenerfassung.

  • Trigger: Aktiviert durch Phrasen wie "neue notiz", "festhalten" oder "dokumentieren".
  • Schema-Logik: Nutzt das default-Schema mit den Feldern Titel, Thema/Inhalt und Tags, sofern kein spezifisches Typ-Schema aus der types.yaml greift.
  • Dynamik: In diesem Modus wird der Fokus vom Retrieval (Wissen finden) auf die Extraktion (Wissen speichern) verschoben.

Hinweis: Da spezifische Schemas für Projekte oder Erfahrungen direkt in der types.yaml definiert werden, dient die decision_engine.yaml hier primär als Fallback für generische Datenaufnahmen.

Auszug aus der decision_engine.yaml

strategies:
  # 1. Fakten-Abfrage (Fallback & Default)
  FACT:
    description: "Reine Wissensabfrage."
    trigger_keywords: [] 
    inject_types: []
    # WP-22: Definitionen & Hierarchien bevorzugen
    edge_boosts:
      part_of: 2.0
      composed_of: 2.0
      similar_to: 1.5
      caused_by: 0.5
    prompt_template: "rag_template"
    prepend_instruction: null

  # 2. Entscheidungs-Frage
  DECISION:
    description: "Der User sucht Rat, Strategie oder Abwägung."
    trigger_keywords: 
      - "soll ich"
      - "meinung"
      - "besser"
      - "empfehlung"
      - "strategie"
      - "entscheidung"
      - "abwägung"
      - "vergleich"
    inject_types: ["value", "principle", "goal", "risk"]
    # WP-22: Risiken und Konsequenzen hervorheben
    edge_boosts:
      blocks: 2.5
      solves: 2.0
      depends_on: 1.5
      risk_of: 2.5
    prompt_template: "decision_template"
    prepend_instruction: |
      !!! ENTSCHEIDUNGS-MODUS !!!
      BITTE WÄGE FAKTEN GEGEN FOLGENDE WERTE, PRINZIPIEN UND ZIELE AB:      

  # 3. Empathie / "Ich"-Modus

Richtwert für Kanten-Boosts: 0.1 (Abwertung) bis 3.0+ (Dominanz gegenüber Text-Match).