2025-12-10 10:26:44 +01:00

12 KiB

Raw Blame History

mindnet v2.2 – Knowledge Design Manual

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

⚡ Die 5 Goldenen Regeln (TL;DR)

Damit Mindnet als dein Digitaler Zwilling funktioniert, beachte beim Schreiben diese Grundsätze:

Atomare Gedanken: Eine Notiz = Ein Thema. Wenn du über zwei Projekte schreibst, mach zwei Notizen draus.
Explizite Typen: Setze immer den type im Frontmatter. Mindnet behandelt eine decision ("Wir machen X") völlig anders als ein concept ("Was ist X").
Semantische Links: Schreibe nicht nur [[Link]], sondern [[rel:depends_on Link]]. Sag dem System wie Dinge zusammenhängen.
Werte & Ziele definieren: Damit die Decision Engine dich beraten kann, musst du deine Kriterien (type: value, type: goal) explizit als Notizen anlegen.
Emotionales Bridging: Damit die Empathie funktioniert, nutze in Erfahrungsberichten (type: experience) emotionale Schlüsselwörter ("Krise", "Freude", "Angst"), damit der Vektor-Retriever sie bei Gefühls-Anfragen findet.

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.3.1 verfügt Mindnet über:

Hybrid Router: Das System erkennt, ob du Fakten, Entscheidungen oder Empathie brauchst.
Context Intelligence: Das System lädt je nach Situation unterschiedliche Notiz-Typen (z.B. Werte bei Entscheidungen).
Web UI (WP10): Du kannst direkt sehen, welche Quellen genutzt wurden.

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 (YYYYMMDD-slug)
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 steuert nicht nur das Gewicht bei der Suche, sondern seit WP-06 auch, wann eine Notiz aktiv in den Chat geholt wird ("Strategic Retrieval").

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	Rolle im Chat (Intent)
`concept`	Fachbegriffe, Theorien. Zeitloses Wissen.	FACT (Basiswissen)
`project`	Ein Vorhaben mit Ziel, Dauer und Aufgaben.	FACT / DECISION (Kontext)
`experience`	Persönliche Erfahrung, Lektion oder Erkenntnis.	EMPATHY (Spiegelung)
`decision`	Eine bewusst getroffene Entscheidung (ADR).	DECISION (Begründung "Warum")
`value`	Ein persönlicher Wert oder ein Prinzip.	DECISION (Moralischer Kompass)
`goal`	Ein strategisches Ziel (kurz- oder langfristig).	DECISION (Abgleich)
`person`	Eine reale Person (Netzwerk, Autor).	FACT
`journal`	Zeitbezogener Log-Eintrag, Daily Note.	FACT (Historie)
`source`	Externe Quelle (Buch, PDF, Artikel).	FACT (Faktenbasis)

3.2 Zusammenspiel mit `types.yaml`

Der type steuert im Hintergrund drei technische Mechanismen:

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.
chunk_profile (Textzerlegung):
- journal (short): Wird fein zerlegt.
- project (long): Längere Kontext-Fenster.
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. Schreiben für den KI-Zwilling (New in v2.3)

Damit der RAG-Chat (WP05/06) nicht nur dumm Fakten wiedergibt, sondern dich berät, musst du "Futter" für die Decision Engine und das Empathie-Modul liefern.

5.1 Futter für die Decision Engine (`DECISION`)

Das System soll abwägen: "Passt Tool X zu mir?". Dazu muss es wissen, was "Du" bist.

Best Practice: Werte definieren Erstelle Notizen mit type: value.

---
type: value
title: Prinzip: Datensparsamkeit
---
# Prinzip: Datensparsamkeit
Wir speichern nur das Minimum an Daten. Cloud-Uploads persönlicher Daten sind verboten, es sei denn, sie sind E2E-verschlüsselt.

Best Practice: Ziele definieren Erstelle Notizen mit type: goal.

---
type: goal
title: Ziel: Unabhängigkeit 2026
---
# Ziel: Unabhängigkeit 2026
Bis Ende 2026 wollen wir alle SaaS-Abos durch Self-Hosted Lösungen ersetzt haben.

Effekt: Wenn du fragst "Soll ich Notion nutzen?", lädt die Engine diese beiden Notizen und antwortet: "Nein, Notion ist SaaS und nicht E2E-verschlüsselt. Das verletzt dein Prinzip der Datensparsamkeit und dein Ziel der Unabhängigkeit."

5.2 Futter für den Empathie-Modus (`EMPATHY`)

Das System soll dich verstehen, wenn du sagst: "Alles ist grau." Dazu braucht es deine Resonanzerfahrungen.

Best Practice: Erfahrungen & Bridging Erstelle Notizen mit type: experience. Nutze im Text emotionale Brückenwörter, damit der Retriever auch bei abstrakten Gefühlen ("grau") einen Treffer landet.

---
type: experience
title: Erfahrung: Der Durchbruch nach der Krise
tags: [krise, hoffnung, grau, angst]
---
# Erfahrung: Der Durchbruch nach der Krise
Es gibt Projektphasen, da wirkt alles **sinnlos** und **grau**.
Ich habe gelernt: Das ist oft das Zeichen kurz vor dem Durchbruch.
Mein Mantra in solchen Zeiten: "Einfach weitermachen, der Nebel lichtet sich."

Effekt: Wenn du im Chat jammerst ("Alles ist sinnlos"), findet das System diese Notiz und spiegelt dir deine eigene Erfahrung zurück.

5.3 Schreiben für den Chat (UI Optimization)

Da deine Notizen im Web-Interface (WP10) angezeigt werden:

Kurze Absätze: Das LLM liest besser, und der Mensch scannt schneller.
Klare Headings: Nutze H1/H2, um dem Chunker logische Trennlinien zu geben.

6. Best Practices & Beispiele (Klassik)

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

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

7. Langfristige Stabilität & Virtual Schema Layer

Mindnet ist auf Langlebigkeit ausgelegt.

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

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

12 KiB Raw Blame History Unescape Escape