Lars/mindnet
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 21 Wiki Activity
603bba533b
mindnet/docs/Knowledge_Design_Manual.md
Lars c56a31c6bc
All checks were successful
Deploy mindnet to llm-node / deploy (push) Successful in 3s
Details
docs/Knowledge_Design_Manual.md hinzugefügt
2025-12-07 11:52:09 +01:00

9.3 KiB
Raw Blame History

mindnet v2.2 – Knowledge Design Manual

Datei: docs/mindnet_knowledge_design_manual_v2.2.md Stand: 2025-12-07 Status: FINAL (Konsolidiert aus WP01–WP04a) Quellen: knowledge_design.md, TYPE_REGISTRY_MANUAL.md, chunking_strategy.md, mindnet_functional_architecture.md, WP03/WP04 Hinweise.

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. Damit der Retriever (die Suchmaschine) und spätere KI-Agenten dieses Wissen nutzen können, müssen Notizen einer klaren Struktur folgen.

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

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
concept Fachbegriffe, Theorien, Modelle. Zeitloses Wissen. (z. B. "Vektordatenbank")
project Ein Vorhaben mit Ziel, Dauer und Aufgaben. (z. B. "Aufbau Homelab")
experience Persönliche Erfahrung, Lektion oder Erkenntnis. (z. B. "Learning: Docker Networking")
decision Eine bewusst getroffene Entscheidung inkl. Alternativen und Begründung. (z. B. "ADR-001: Nutzung von Qdrant")
value Ein persönlicher Wert oder ein Prinzip. (z. B. "Datensparsamkeit")
person Eine reale Person (Netzwerk, Autor).
event Ein Ereignis (Konferenz, Meeting).
journal Zeitbezogener Log-Eintrag, Daily Note.
source Externe Quelle (Buch, PDF, Artikel), die exzerpiert wird.

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).
    • Ziel: Mindnet soll bei Fragen eher deine Entscheidungen und Projekte finden als reine Definitionen.
  2. chunk_profile (Textzerlegung):
    • journal (short): Wird fein zerlegt, da sich Themen schnell ändern.
    • concept (medium): Standard-Absätze.
    • project (long): Längere Kontext-Fenster, um Zusammenhänge zu wahren.
  3. edge_defaults (Automatische Vernetzung):
    • Mindnet ergänzt automatisch Kanten.
    • Beispiel: Ein Link in einem project wird automatisch als depends_on (Abhängigkeit) interpretiert, sofern nicht anders angegeben.

4. Edges & Referenzen in Notes

Um aus isolierten Dateien ein Netzwerk zu machen, nutzen wir Verlinkungen. Mindnet v2.2 (WP03) bietet hierfür präzise Werkzeuge.

4.1 Wikilinks (Die Basis-Referenz)

Der klassische Obsidian-Link.

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

4.2 Inline-Relationen (Semantische Verknüpfung)

Wenn du ausdrücken willst, wie Dinge zusammenhängen. Dies ist essenziell für die Erklärbarkeit ("Warum ist das relevant?").

Daher [[rel:depends_on Qdrant]].
Dieses Konzept ist [[rel:similar_to Pinecone]].
  • Syntax: [[rel:RELATION ZIEL]]. (Wichtig: Das rel: Präfix steht innerhalb der Klammer).
  • Gültige Relationen:
    • depends_on: Hängt ab von / Benötigt.
    • similar_to: Ähnelt / Ist vergleichbar mit.
    • related_to: Hat zu tun mit (allgemein).
    • caused_by: Wurde verursacht durch.
    • solves: Löst (Problem).
    • implements: Setzt um (Konzept).
  • Nicht unterstützt: rel: depends_on [[Ziel]] (alte Syntax, funktioniert nicht mehr!).

4.3 Callout-Edges (Kuratierte Listen)

Für Zusammenfassungen oder "Siehe auch"-Blöcke am Ende einer Notiz, die nicht im Fließtext stehen sollen.

> [!edge] related_to: [[Vector Embeddings]] [[AI Agents]]
  • Funktion: Erzeugt related_to-Kanten zu allen genannten Zielen in dieser Zeile.
  • Nutzen: Erlaubt schnelle Listenpflege ohne den Textfluss zu stören.

4.4 Strukturkanten (Automatisch)

Diese musst du nicht schreiben, sie entstehen automatisch:

  • belongs_to: Verknüpft jeden Textabschnitt (Chunk) mit seiner Ursprungsnotiz.
  • next / prev: Verknüpft Absätze in Lesereihenfolge (ermöglicht Agenten das "Weiterlesen").
  • has_part / part_of: (Zukünftig) Basierend auf Ordnerstrukturen.

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]].

5.3 Typische Anti-Patterns (Bitte vermeiden!)

  1. Der "Alles"-Zettel: Eine Notiz "Ideen 2025", die 50 verschiedene Themen enthält.
    • Besser: Atomare Notizen ("Idee A", "Idee B") erstellen und verlinken.
  2. Manuelle Gewichtung: retriever_weight: 0.9 im Frontmatter setzen.
    • Problem: Wenn du das System tunen willst, musst du hunderte Dateien ändern.
    • Besser: Den type korrekt setzen und das Gewicht zentral in types.yaml steuern.
  3. Link-Wüsten: Eine Notiz, die nur aus einer Liste von 100 Links besteht ohne Text.
    • Problem: Der Vektor-Sucher findet keinen kontextuellen "Anker" (Text).
    • Besser: Kurze Beschreibung zu jedem Link hinzufügen.

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 entscheiden, dass "Projekte" stärker gewichtet werden sollen, ändern wir eine Zeile in der Konfiguration, und das gesamte System passt sich beim nächsten Import an.
  • Deine Notizen bleiben sauber und zukunftssicher.