Lars/mindnet
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 21 Wiki Activity
32128c06c1
mindnet/docs/Knowledge_Design_Manual.md
Lars d48b671314 Dokumentation aktualisiert
2025-12-08 16:14:52 +01:00

9.0 KiB
Raw Blame History

mindnet v2.2 – Knowledge Design Manual

Datei: docs/mindnet_knowledge_design_manual_v2.2.md Stand: 2025-12-08 Status: FINAL (Integrierter Stand WP01–WP05) Quellen: knowledge_design.md, TYPE_REGISTRY_MANUAL.md, chunking_strategy.md, mindnet_functional_architecture.md.

1. Zweck & Scope

Dieses Handbuch ist die primäre Arbeitsanweisung für dich als Mindmaster (Owner) und alle Autoren, die Inhalte im mindnet-Vault erstellen.

1.1 Zielsetzung

Mindnet ist mehr als eine Dokumentablage. Es ist ein vernetztes System, das deine Persönlichkeit, Entscheidungen und Erfahrungen abbildet. Seit Version 2.2 verfügt Mindnet über:

  • Explanation Engine: Das System erklärt, warum es Notizen findet (über Edges).
  • RAG-Chat (KI-Zwilling): Das System antwortet in natürlicher Sprache. Wie du schreibst, bestimmt, wie schlau die KI antwortet.

1.2 Der Vault als „Source of Truth“

Die Markdown-Dateien in deinem Vault sind die einzige Quelle der Wahrheit.

  • Mindnet importiert diesen Zustand deterministisch in die Datenbank (Qdrant).
  • Änderungen an IDs, Typen oder Inhalten müssen immer im Markdown erfolgen, niemals direkt in der Datenbank.
  • Was nicht im Markdown steht (z. B. implizites Wissen im Kopf), existiert für das System nicht.

2. Note-Struktur & Frontmatter

Jede Notiz benötigt einen YAML-Header (Frontmatter) am Dateianfang. Dieser Block macht die Notiz maschinenlesbar.

2.1 Pflichtfelder

Jede Datei muss mindestens folgende Felder enthalten, um korrekt verarbeitet zu werden:

---
id: 20251110-projekt-alpha-8a9b2c   # Eindeutige Kennung
title: Projekt Alpha                 # Sprechender Titel (wird in Suchergebnissen angezeigt)
type: project                        # Steuert Verarbeitung & Vernetzung (siehe Kap. 3)
status: active                       # Status (z.B. draft, active, archived)
created: 2025-11-10                  # Erstellungsdatum (ISO 8601 oder YYYY-MM-DD)
updated: 2025-12-07                  # Letzte Änderung
tags: [ki, entwicklung]              # Taxonomie für Filterung
---

2.2 Optionale Felder

Diese Felder sind technisch nicht zwingend, aber für bestimmte Typen sinnvoll:

lang: de                             # Sprache (Default: de)
aliases: [Alpha Projekt, Project A]  # Synonyme für die Suche
visibility: internal                 # internal (default), public, private

Hinweis: Felder wie retriever_weight oder chunk_profile sollten nicht mehr manuell im Frontmatter gesetzt werden. Diese werden zentral über den type gesteuert (siehe Kap. 3), um die Wartbarkeit zu sichern.

2.3 Empfehlungen für IDs und Pfade

Die ID (Identifikator):

  • Muss global eindeutig und stabil sein.
  • Darf sich nicht ändern, wenn die Datei umbenannt oder verschoben wird.
  • Empfehlung: YYYYMMDD-slug-hash (z. B. 20231027-vektor-db-a1b2). Dies garantiert Eindeutigkeit und Chronologie.

Dateinamen & Pfade:

  • Pfade dienen der menschlichen Ordnung (Ordnerstruktur), sind für Mindnet aber sekundär.
  • Dateinamen sollten dem Titel entsprechen (Projekt Alpha.md) oder dem Slug (projekt-alpha.md).
  • Sonderzeichen vermeiden (außer Bindestrich und Unterstrich).

3. Note-Typen & Typ-Registry

Der type ist der wichtigste Hebel im Knowledge Design. Er verknüpft die Notiz mit der Konfiguration in config/types.yaml.

3.1 Übersicht der Kern-Typen

Mindnet unterscheidet verschiedene Wissensarten. Wähle den Typ, der die Rolle der Notiz am besten beschreibt:

Typ Beschreibung & Einsatzzweck Wichtigkeit für Chat
concept Fachbegriffe, Theorien. Zeitloses Wissen. Mittel (Basiswissen)
project Ein Vorhaben mit Ziel, Dauer und Aufgaben. Hoch (Kontext)
experience Persönliche Erfahrung, Lektion oder Erkenntnis. Sehr Hoch (Persönlichkeit)
decision Eine bewusst getroffene Entscheidung (ADR). Kritisch (Begründung "Warum")
value Ein persönlicher Wert oder ein Prinzip. Kritisch (Moralischer Kompass)
person Eine reale Person (Netzwerk, Autor). Niedrig
journal Zeitbezogener Log-Eintrag, Daily Note. Mittel (Historie)
source Externe Quelle (Buch, PDF, Artikel). Niedrig (Faktenbasis)

3.2 Zusammenspiel mit types.yaml

Der type steuert im Hintergrund drei technische Mechanismen:

  1. retriever_weight (Wichtigkeit):
    • Ein concept (0.6) wiegt weniger als ein project (0.97) oder eine decision (1.0).
    • Warum? Bei einer Suche nach "Datenbank" soll Mindnet bevorzugt deine Entscheidung ("Warum wir X nutzen") anzeigen.
  2. chunk_profile (Textzerlegung):
    • journal (short): Wird fein zerlegt.
    • project (long): Längere Kontext-Fenster.
  3. edge_defaults (Automatische Vernetzung):
    • Mindnet ergänzt automatisch Kanten.
    • Beispiel: Ein Link in einem project wird automatisch als depends_on (Abhängigkeit) interpretiert.

4. Edges & Referenzen in Notes

Um aus isolierten Dateien ein Netzwerk zu machen, nutzen wir Verlinkungen. In Version 2.2 sind diese Verlinkungen die Basis für den Hybrid Retriever (Suche über Nachbarn).

4.1 Wikilinks (Die Basis-Referenz)

Der klassische Obsidian-Link.

Wir nutzen [[Qdrant]] als Vektordatenbank.
  • Bedeutung: "Diese Notiz erwähnt Qdrant."
  • Edge-Typ: references

4.2 Inline-Relationen (Semantische Verknüpfung)

Dies ist die mächtigste Methode. Du sagst dem System explizit, wie Dinge zusammenhängen.

Daher [[rel:depends_on Qdrant]].
Dieses Konzept ist [[rel:similar_to Pinecone]].
  • Syntax: [[rel:RELATION ZIEL]].
  • Gültige Relationen:
    • depends_on: Hängt ab von / Benötigt. (Trigger für hohe Graph-Relevanz).
    • similar_to: Ähnelt / Ist vergleichbar mit.
    • related_to: Hat zu tun mit (allgemein).
    • caused_by: Wurde verursacht durch.
    • solves: Löst (Problem).

4.3 Callout-Edges (Kuratierte Listen)

Für Zusammenfassungen oder "Siehe auch"-Blöcke am Ende einer Notiz.

> [!edge] related_to: [[Vector Embeddings]] [[AI Agents]]
  • Funktion: Erzeugt related_to-Kanten zu allen genannten Zielen in dieser Zeile.

5. Best Practices & Beispiele

5.1 Beispiel: Projekt-Notiz

Projekte profitieren von depends_on, um Abhängigkeiten zu klären.

---
id: 20251115-proj-mindnet
title: Mindnet Implementierung
type: project
status: active
---

# Mindnet Implementierung

Wir bauen ein persönliches Wissensnetz.

## Tech Stack
Wir nutzen [[rel:depends_on Qdrant]] für die Vektorsuche und [[rel:depends_on FastAPI]] für das Backend.

## Architektur
Das Konzept basiert auf [[RAG Architecture]]. (Automatisch 'depends_on' durch Typ-Default).

5.2 Beispiel: Entscheidung (Decision Record)

Entscheidungen sind hoch gewichtet (retriever_weight: 1.0).

---
id: 20251120-adr-vektordb
title: ADR: Wahl von Qdrant
type: decision
status: final
tags: [architektur, db]
---

# Entscheidung: Qdrant

Wir haben uns für Qdrant entschieden.

## Alternativen
Wir haben auch [[rel:similar_to Pinecone]] und [[rel:similar_to Weaviate]] betrachtet.

## Begründung
Qdrant erlaubt lokalen Betrieb und [[rel:solves Payload Filtering Requirements]].

6. Langfristige Stabilität & Virtual Schema Layer

Mindnet ist auf Langlebigkeit ausgelegt.

6.1 Das "Virtual Schema" Prinzip

Wir vermeiden es, Logik in den Markdown-Dateien hart zu kodieren.

  • Statt in jeder Notiz zu schreiben chunk_size: 500, schreiben wir nur type: essay.
  • Wie groß ein Chunk für ein Essay ist, definieren wir in der Konfiguration (types.yaml).

6.2 Was bedeutet das für dich?

  • Du kannst dich auf den Inhalt konzentrieren.
  • Wenn wir in Zukunft (WP08) basierend auf Feedback lernen, dass "Projekte" noch wichtiger sind, ändern wir eine Zeile in der Konfiguration, und das gesamte System passt sich beim nächsten Import an.

7. Schreiben für den KI-Zwilling (New in v2.2)

Damit der RAG-Chat (WP05) gute Antworten liefert, beachte diese Regeln:

  1. Atomare Konzepte:
    • Der Chatbot baut seine Antwort aus mehreren kleinen Text-Stücken ("Chunks") zusammen.
    • Schreibe so, dass ein Absatz auch für sich allein verständlich ist.
  2. Explizite Entscheidungen:
    • Wenn du eine Meinung hast ("Tool X ist schlecht"), schreibe sie nicht in einen Nebensatz.
    • Erstelle eine Notiz type: experience oder decision ("Warum Tool X nicht geeignet ist").
    • Die KI sucht gezielt nach [DECISION]-Typen, um "Warum"-Fragen zu beantworten.
  3. Werte definieren:
    • Erstelle Notizen mit type: value (z.B. "Datenschutz First").
    • Die KI nutzt diese, um bei Konflikten ("Soll ich Cloud oder Lokal nutzen?") in deinem Sinne zu argumentieren.
  4. Verlinken ist Pflicht:
    • Der Chatbot nutzt Hybrid Search. Er findet Notizen nur, wenn sie über Kanten verbunden sind.
    • Eine isolierte Notiz (ohne Links) ist für die KI fast unsichtbar.