mindnet/docs/appendix.md

Mindnet v2.2 – Appendices & Referenzen

Datei: docs/mindnet_appendices_v2.2.md Stand: 2025-12-07 Status: FINAL (Konsolidiert aus WP01–WP04a) Quellen: TYPE_REGISTRY_MANUAL.md, chunking_strategy.md, mindnet_technical_architecture.md, Handbuch.md.

Dieses Dokument bündelt Tabellen, Schemata und technische Referenzen, die in den Prozess-Dokumenten (Playbook, Guides) den Lesefluss stören würden.

---

Anhang A: Typ-Registry Referenz (Default-Werte)

Diese Tabelle zeigt die Standard-Konfiguration der types.yaml (Stand v2.2). Diese Werte werden beim Import angewendet, sofern im Frontmatter nichts anderes definiert ist.

Typ (type)	Chunk Profile	Retriever Weight	Edge Defaults (Auto-Kanten)	Beschreibung
concept	medium	0.60	references, related_to	Abstrakte Begriffe, Theorien.
project	long	0.97	references, depends_on	Aktive Vorhaben. Hohe Priorität.
decision	long	1.00	caused_by, references	Entscheidungen (ADRs). Höchste Prio.
experience	medium	0.90	derived_from, inspired_by	Persönliche Learnings.
journal	short	0.80	related_to	Zeitgebundene Logs. Fein granular.
person	short	0.50	related_to	Personen-Profile.
source	long	0.50	(keine)	Externe Quellen (Bücher, PDFs).
event	short	0.60	related_to	Meetings, Konferenzen.
default	medium	1.00	references	Fallback, wenn Typ unbekannt.

---

Anhang B: Edge-Typen & Semantik

Referenz aller implementierten Kantenarten (kind). Die Spalte "Herkunft" zeigt, durch welchen Mechanismus diese Kante primär entsteht.

Kind	Herkunft (Primär)	Symmetrisch?	Bedeutung & Nutzung
references	Wikilink [[...]]	Nein	Standard-Verweis. "Erwähnt X".
belongs_to	Struktur (Auto)	Nein	Verknüpft Chunk mit seiner Note.
next / prev	Struktur (Auto)	Ja (Logisch)	Definiert Lesereihenfolge der Chunks.
depends_on	Inline / Default	Nein	Harte Abhängigkeit. "Braucht X um zu funktionieren".
related_to	Callout / Default	Ja (Oft)	Thematische Nähe. "Siehe auch X".
similar_to	Inline	Ja	Inhaltliche Ähnlichkeit. "Ist wie X".
caused_by	Inline	Nein	Kausalität. "X ist der Grund für Y".
solves	Inline	Nein	Lösung. "Tool X löst Problem Y".
derived_from	Default (Exp)	Nein	Herkunft. "Erkenntnis stammt aus Quelle X".

---

Anhang C: Datenmodelle (JSON Payloads)

Dies sind die Felder, die effektiv in Qdrant gespeichert werden. Dient als Referenz für Entwickler und Debugging (payload_dryrun).

C.1 Note Payload (mindnet_notes)

{
  "note_id": "string (keyword)",       // UUIDv5 oder Slug
  "title": "string (text)",            // Titel aus Frontmatter
  "type": "string (keyword)",          // Typ (z.B. 'project')
  "retriever_weight": "float",         // Numerische Wichtigkeit (0.0-1.0)
  "chunk_profile": "string",           // Genutztes Profil (z.B. 'long')
  "edge_defaults": ["string"],         // Liste der aktiven Default-Kanten
  "tags": ["string"],                  // Liste von Tags
  "created": "string (iso-date)",      // Erstellungsdatum
  "updated": "integer",                // Timestamp
  "fulltext": "string (no-index)"      // Gesamter Text (für Recovery)
}

C.2 Chunk Payload (mindnet_chunks)

{
  "chunk_id": "string (keyword)",      // Format: {note_id}#c{index}
  "note_id": "string (keyword)",       // FK zur Note
  "text": "string (text)",             // Reintext für Anzeige (ohne Overlap)
  "window": "string (text)",           // Text + Overlap (für Embedding)
  "ord": "integer",                    // Laufende Nummer (1..N)
  "retriever_weight": "float",         // Kopie aus Note (für Query-Speed)
  "neighbors_prev": ["string"],        // ID des Vorgängers
  "neighbors_next": ["string"]         // ID des Nachfolgers
}

C.3 Edge Payload (mindnet_edges)

{
  "edge_id": "string (keyword)",       // Deterministischer Hash
  "source_id": "string (keyword)",     // Chunk-ID (Start)
  "target_id": "string (keyword)",     // Chunk-ID oder Note-Titel (Ziel)
  "kind": "string (keyword)",          // z.B. 'depends_on'
  "scope": "string (keyword)",         // Immer 'chunk' in v2.2
  "rule_id": "string (keyword)",       // Traceability: 'inline:rel', 'explicit:wikilink'
  "confidence": "float",               // 0.0 - 1.0
  "note_id": "string (keyword)"        // Owner Note ID (für Löschung)
}

---

Anhang D: Environment Variablen

Diese Variablen steuern das Verhalten der Skripte und Container.

Variable	Default	Beschreibung
QDRANT_URL	http://localhost:6333	URL zur Vektor-DB.
QDRANT_API_KEY	(leer)	API-Key für Absicherung (optional).
COLLECTION_PREFIX	mindnet	Namensraum für Collections ({prefix}_notes etc).
MINDNET_TYPES_FILE	config/types.yaml	Pfad zur Typ-Registry.
MINDNET_RETRIEVER_CONFIG	config/retriever.yaml	Pfad zur Scoring-Konfiguration.
MINDNET_HASH_COMPARE	Body	Vergleichsmodus für Import (Body, Frontmatter, Full).
MINDNET_HASH_SOURCE	parsed	Quelle für Hash (parsed, raw, file).
MINDNET_HASH_NORMALIZE	canonical	Normalisierung vor Hash (canonical, none).
VECTOR_DIM	384	Dimension der Embeddings (Modellabhängig).

---

Anhang E: Glossar

Zentrale Begriffe des Mindnet-Systems.

• Callout-Edge: Eine Kante, die durch einen Obsidian-Callout Block (> [!edge]) definiert wird. Dient für Listen.
• Chunking: Prozess des Zerlegens einer Notiz in kleinere, semantische Einheiten (Chunks).
• Confidence: Ein Wert (0.0-1.0), der angibt, wie sicher eine Kante ist. Explizite User-Eingaben haben 1.0, Defaults ~0.7.
• Idempotenz: Eigenschaft des Importers, bei mehrfacher Ausführung das exakt gleiche Ergebnis zu liefern (keine Duplikate).
• Inline-Edge: Eine Kante, die im Fließtext mittels [[rel:type Ziel]] definiert wird. Semantisch sehr stark.
• Provenance: Die Herkunft einer Information (z.B. "explicit" vs "rule" vs "inference").
• Retriever: Die Komponente (FastAPI), die Suchanfragen beantwortet und Scores berechnet.
• Rule ID: Ein String, der genau identifiziert, welche Code-Regel eine Kante erzeugt hat (z.B. edge_defaults:project:depends_on).
• Vault: Der lokale Ordner mit Markdown-Dateien. Die "Single Source of Truth".
• Vector Search: Suche basierend auf semantischer Ähnlichkeit (Embeddings) statt reiner Stichworte.

---

Anhang F: Workpackage Status (v2.2)

Status der Module gemäß Programmplan.

WP	Titel	Status	Anmerkung
WP01	Knowledge Design	🟢 Live	Typen, Frontmatter definiert.
WP02	Chunking Strategy	🟢 Live	Profilbasiertes Chunking aktiv.
WP03	Edge Logic / Import	🟢 Live	Neue Importer-Pipeline mit Provenance.
WP04a	Retriever Scoring	🟢 Live	Hybrider Score (Semantik + Graph).
WP04b	Explanation Layer	🟡 In Arbeit	API liefert Pfade, UI fehlt noch.
WP04c	Feedback Loop	🔴 Geplant	Logging von User-Feedback.
WP05	Virtual Schema	🟡 Teilw.	types.yaml aktiv, ACL fehlt.
WP06	Self-Healing	🔴 Geplant	Auto-Fixing von Broken Links.
WP08	Self-Tuning	🔴 Geplant	Auto-Adjustment der Gewichte.