--- doc_type: technical_reference audience: developer, admin scope: configuration, env, registry, scoring, resilience, modularization, agentic_rag status: active version: 2.9.3 context: "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. ```yaml 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:** `/_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:** ```markdown | 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:** ```yaml 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 ```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 ```