mindnet/docs/03_Technical_References/03_tech_configuration.md

doc_type	audience	scope	status	version	context
technical_reference	developer, admin	configuration, env, registry, scoring, resilience, modularization, agentic_rag	active	2.9.3	Umfassende Referenztabellen für Umgebungsvariablen (inkl. Hybrid-Cloud & WP-76), YAML-Konfigurationen, Edge Registry Struktur und WP-25 Multi-Stream RAG unter Berücksichtigung von WP-14.

Konfigurations-Referenz

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

1. Environment Variablen (.env)

Diese Variablen steuern die Infrastruktur, Pfade und globale Timeouts. Seit der Modularisierung in WP-14 unterstützen sie zudem die explizite Benennung von Vektoren für verschiedene Collections.

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).
MINDNET_PREFIX	(leer)	Alternative zu COLLECTION_PREFIX. Falls gesetzt, wird dieser Wert verwendet.
VECTOR_DIM	768	Muss 768 sein (für Nomic Embeddings).
MINDNET_DISTANCE	Cosine	Metrik für Vektor-Ähnlichkeit (Cosine, Euclidean, Dot).
MINDNET_VECTOR_NAME	default	Neu (WP-14): Basis-Vektorname für Named Vectors Support.
NOTES_VECTOR_NAME	(leer)	Neu (WP-14): Spezifischer Vektorname für die Notes-Collection (Override).
CHUNKS_VECTOR_NAME	(leer)	Neu (WP-14): Spezifischer Vektorname für die Chunks-Collection (Override).
EDGES_VECTOR_NAME	(leer)	Neu (WP-14): Spezifischer Vektorname für die Edges-Collection (Override).
MINDNET_VOCAB_PATH	(Pfad)	Neu (WP-22): Absoluter Pfad zur 01_edge_vocabulary.md. Definiert den Ort des Dictionarys.
MINDNET_VAULT_ROOT	./vault_master	Achtung: Standard ist ./vault_master, nicht ./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-20): Wartezeit in Sekunden bei HTTP 429 (Rate Limit).
MINDNET_LLM_RATE_LIMIT_RETRIES	3	Neu (WP-20): 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.
MAX_OLLAMA_CHARS	10000	Maximale Länge des Kontext-Strings, der an das lokale Modell gesendet wird.
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).
MINDNET_DEFAULT_RETRIEVER_WEIGHT	1.0	Neu (WP-22): Systemweiter Standard für das Retriever-Gewicht einer Notiz.

---

2. Typ-Registry (types.yaml)

Steuert das Import-Verhalten, Chunking und die Kanten-Logik pro Typ. Die Auflösung erfolgt zentral über die modularisierte Registry in app.core.registry.

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. Ingestion Settings (Neu WP-14): Globale Konfiguration wie default_chunk_profile innerhalb des ingestion_settings Blocks.
4. 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. Seit WP-14 ist die mathematische Engine im Paket app.core.retrieval gekapselt.

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.
edge_types:
  # --- KATEGORIE 1: LOGIK-BOOSTS (Relevanz-Treiber) ---
  blocks: 1.6
  solves: 1.5
  depends_on: 1.4
  resulted_in: 1.4
  followed_by: 1.3
  caused_by: 1.2
  preceded_by: 1.1

  # --- KATEGORIE 2: QUALITATIVER KONTEXT (Stabilitäts-Stützen) ---
  guides: 1.1
  part_of: 1.1
  based_on: 0.8
  derived_from: 0.6
  uses: 0.6

  # --- KATEGORIE 3: THEMATISCHE NÄHE (Ähnlichkeits-Signal) ---
  similar_to: 0.4

  # --- KATEGORIE 4: SYSTEM-NUDGES (Technische Struktur) ---
  belongs_to: 0.2
  next: 0.1
  prev: 0.1

  # --- KATEGORIE 5: WEICHE ASSOZIATIONEN (Rausch-Unterdrückung) ---
  references: 0.1
  related_to: 0.05

---

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>/_system/dictionary/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. |

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 v3.1.6)

Die Decision Engine fungiert als zentraler Agentic Orchestrator für die Intent-Erkennung und das dynamische Multi-Stream Retrieval-Routing (WP-25). Sie bestimmt, wie das System auf eine Nutzeranfrage reagiert, welche Wissens-Streams aktiviert werden und wie die Ergebnisse synthetisiert werden.

5.1 Intent Recognition: Hybrid-Routing (WP-25)

Das System nutzt einen Hybrid-Modus mit Keyword Fast-Path und LLM Slow-Path:

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 (z.B. "Soll ich" → DECISION).
2. Type Keywords: Prüft detection_keywords aus types.yaml für Interview-Modus (z.B. "Projekt" + "neu" → INTERVIEW).
3. Slow Path (LLM Router): Wenn kein Keyword matcht und llm_fallback_enabled: true gesetzt ist, analysiert ein LLM die Nachricht mittels Few-Shot Prompting (intent_router_v1).

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 Multi-Stream Konfiguration (WP-25)

Seit WP-25 nutzt die Decision Engine eine Stream-Library mit spezialisierten Wissens-Streams:

Stream-Library (streams_library):

• values_stream: Identität, Ethik und Prinzipien (filter_types: value, principle, belief, trait, boundary, need, motivation)
• facts_stream: Operative Daten (filter_types: project, decision, task, goal, event, state)
• biography_stream: Persönliche Erfahrungen (filter_types: experience, journal, profile, person)
• risk_stream: Hindernisse und Gefahren (filter_types: risk, obstacle, bias)
• tech_stream: Technisches Wissen (filter_types: concept, source, glossary, idea, insight, skill, habit)

Stream-Parameter:

• query_template: Transformiert die ursprüngliche Anfrage für spezialisierte Suche (z.B. "Welche meiner Werte und Prinzipien betreffen: {query}")
• filter_types: Strikte Synchronisation mit types.yaml (v2.7.0)
• top_k: Anzahl der Treffer pro Stream (z.B. 5 für Values, 3 für Risk)
• edge_boosts: Individuelle Edge-Gewichtung pro Stream (z.B. guides: 3.0 für Values Stream)

Strategie-Komposition (strategies): Jede Strategie definiert, welche Streams aktiviert werden:

• use_streams: Liste der Stream-Keys, die parallel abgefragt werden (z.B. ["values_stream", "facts_stream", "risk_stream"] für DECISION)
• prompt_template: Template-Key aus prompts.yaml für die Wissens-Synthese (z.B. decision_synthesis_v1)
• prepend_instruction: Optional: Zusätzliche Anweisung für das LLM (z.B. "Analysiere die Fakten vor dem Hintergrund meiner Werte")
• preferred_provider: Optional: Provider-Präferenz für diese Strategie (z.B. gemini für DECISION)

5.3 Strategie-Mechaniken (Graph Shaping)

Jede Strategie definiert mehrere Hebel, um das Ergebnis zu beeinflussen:

• use_streams: Aktiviert parallele Wissens-Streams (WP-25).
• 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.4 Übersicht der Strategien (WP-25)

Strategie	Fokus	Aktive Streams	Bevorzugte Kanten (edge_boosts)
FACT_WHAT	Wissensabfrage & Listen	facts_stream, tech_stream, biography_stream	part_of (2.0), depends_on (1.5), implemented_in (1.5)
FACT_WHEN	Zeitpunkte & Termine	facts_stream, biography_stream, tech_stream	part_of (2.0), depends_on (1.5)
DECISION	Rat, Strategie & Abwägung	values_stream, facts_stream, risk_stream	blocks (2.5), impacts (2.0), risk_of (2.5)
EMPATHY	Emotionale Resonanz	biography_stream, values_stream	related_to (1.5), experienced_in (2.0)
CODING	Programmierung & Syntax	tech_stream, facts_stream	uses (2.5), implemented_in (3.0)
INTERVIEW	Erfassung neuer Daten	(Keine Streams)	(Keine)

---

5.5 Der Interview-Modus & Schemas

Die Strategie INTERVIEW dient der strukturierten Datenerfassung.

• Trigger: Aktiviert durch Phrasen wie "neue notiz", "festhalten" oder "dokumentieren" (Type Keywords aus types.yaml).
• 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.
• Streams: Keine Streams aktiviert (leere use_streams Liste).

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.

5.6 Prompts-Konfiguration (prompts.yaml v3.1.2)

Seit WP-25 nutzen die Synthese-Templates explizite Stream-Variablen:

Template-Struktur:

decision_synthesis_v1:
  ollama: |
    WERTE & PRINZIPIEN (Identität):
    {values_stream}
    
    OPERATIVE FAKTEN (Realität):
    {facts_stream}
    
    RISIKO-RADAR (Konsequenzen):
    {risk_stream}
    
    ENTSCHEIDUNGSFRAGE:
    {query}    

Pre-Initialization: Alle möglichen Stream-Variablen werden vorab initialisiert (verhindert KeyErrors bei unvollständigen Konfigurationen).

Provider-spezifische Templates: Separate Versionen für Ollama, Gemini und OpenRouter.

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