Lars/mindnet
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 21 Wiki Activity
4f2296b9b0
mindnet/docs/01_User_Manual/01_knowledge_design.md
Lars 4f2296b9b0
All checks were successful
Deploy mindnet to llm-node / deploy (push) Successful in 3s
Details
update um status
2025-12-19 20:09:59 +01:00

13 KiB
Raw Blame History

doc_type audience scope status version context
user_manual user, author vault, markdown, schema active 2.8.0 Regelwerk für das Erstellen von Notizen im Vault. Die 'Source of Truth' für Autoren.

Knowledge Design Manual

Quellen: knowledge_design.md, types.yaml

⚡ Die 5 Goldenen Regeln (TL;DR)

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

  1. Atomare Gedanken: Eine Notiz = Ein Thema. Wenn du über zwei Projekte schreibst, mach zwei Notizen draus.
  2. Explizite Typen: Setze immer den type im Frontmatter. Mindnet behandelt eine decision ("Wir machen X") völlig anders als ein concept ("Was ist X").
  3. Semantische Links: Schreibe nicht nur [[Link]], sondern [[rel:depends_on Link]]. Sag dem System wie Dinge zusammenhängen.
  4. Werte & Ziele definieren: Damit die Decision Engine dich beraten kann, musst du deine Kriterien (type: value, type: goal) explizit als Notizen anlegen.
  5. Emotionales Bridging: Damit die Empathie funktioniert, nutze in Erfahrungsberichten (type: experience) emotionale Schlüsselwörter ("Krise", "Freude", "Angst").
  6. Narrative Tiefe (Fleisch am Knochen): Fakten allein reichen für Sessions und Biografien nicht aus. Erhalte die "Warum"-Ebene und Coach-Interpretationen. Die Erzählebene sichert, dass die KI die Intention versteht und der Mensch die Bedeutung nachvollziehen kann.

1. Zweck & Scope

Mindnet ist mehr als eine Dokumentablage. Es ist ein vernetztes System, das deine Persönlichkeit abbildet. Die Markdown-Dateien in deinem Vault sind die einzige Quelle der Wahrheit ("Source of Truth"). Was nicht im Markdown steht, existiert für das System nicht.

2. Note-Struktur & Frontmatter

Jede Notiz benötigt einen YAML-Header (Frontmatter).

Pflichtfelder:

---
id: 20251212-projekt-alpha     # Eindeutige Kennung (YYYYMMDD-slug empfohlen)
title: Projekt Alpha           # Sprechender Titel
type: project                  # Steuert Chunking & Wichtigkeit
status: active                 # active, archived, draft
created: 2025-12-12            # ISO 8601
tags: [ki, entwicklung]        # Taxonomie
aliases: [KI Projekt, Codename Quickhack]
---

2.1 [NEU] Naming Convention: Intuitiv vs. Technisch

Für die Benutzerfreundlichkeit und die intuitive Navigation in Obsidian wird die Nutzung von menschenlesbaren Titeln bevorzugt (z. B. Mein Persönliches Leitbild 2025 statt leitbild_identity).

  • Die technische Eindeutigkeit wird primär über die id im Frontmatter sichergestellt.
  • Die KI nutzt die Semantik des Dateinamens als zusätzlichen Kontext-Vektor.

2.3 Advanced Overrides: Die KI-Steuerung übernehmen

In 95% der Fälle setzt der type (z.B. "concept") automatisch die richtigen Einstellungen. In Spezialfällen kannst du diese manuell im Frontmatter überschreiben, um das Verhalten der KI zu erzwingen.

A. retriever_weight: Die Sichtbarkeit steuern

Dieser Faktor (Default: 1.0) ist ein Multiplikator für das Ranking in der Vektorsuche. Er entscheidet, welche Notiz "gewinnt", wenn zwei Texte inhaltlich ähnlich sind.

  • Standard (1.0): Normale Wichtigkeit.
  • Boost (1.2 - 2.0): "Das hier ist die Wahrheit."
    • Einsatz: Finale Entscheidungen, Kernprinzipien, die "Single Source of Truth".
    • Effekt: Verdrängt weniger wichtige Notizen (z.B. Meeting-Protokolle) aus dem Kontext-Fenster der KI.
  • Deboost (0.5 - 0.8): "Nur Kontext, keine Fakten."
    • Einsatz: Glossare, externe Quellen (source), reine Datensammlungen.
    • Effekt: Die Notiz wird nur gefunden, wenn man sehr spezifisch danach sucht.

B. chunking_profile: Die Zerstückelung steuern

Das Profil bestimmt, wie der Text für die Datenbank zerschnitten wird. Falsches Chunking zerreißt den Kontext. Wähle das Profil basierend auf der Struktur deines Textes.

Profil-Name Strategie Einsatzzweck & Wirkung
sliding_standard Sliding Window Der Allrounder. Für Fließtexte (Tagebuch, Artikel). Der Text wird in überlappende Fenster geschnitten. Gut, wenn der Inhalt von oben nach unten fließt.
sliding_short Sliding Window (Klein) Für Dichte. Für Texte mit sehr hoher Informationsdichte (Glossare, Task-Listen), wo jeder Satz wichtig ist. Erzeugt viele kleine Chunks.
sliding_smart_edges Sliding + AI Der Intelligente. Wie Standard, aber das LLM analysiert jeden Chunk zusätzlich auf implizite Querverweise. Standard für concept und project.
structured_smart_edges Heading Split (Soft) Für Strukturierte Texte. Trennt an Überschriften (H2). Besonderheit: Wenn ein Abschnitt sehr kurz ist, wird er mit dem nächsten verschmolzen ("Soft Mode"), um den Kontext zu wahren.
structured_smart_edges_strict Heading Split (Hard) Für Listen & Kataloge. Trennt zwingend an jeder H2-Überschrift. Verhindert das Verschmelzen.
Wichtig für: decision (Option A darf nicht mit Option B verschmelzen), value, profile.

Beispiel für ein Override:

---
title: Sammlung meiner Passwörter-Regeln
type: list
# Wir erzwingen eine strikte Trennung, damit Regel 1 nicht mit Regel 2 vermischt wird.
chunking_profile: structured_smart_edges_strict
# Extrem wichtig, soll immer beachtet werden.
retriever_weight: 1.5
---

3. Frontmatter Felder und ihre Bedeutung

3.1 Typ-Referenz & Verhalten

Wähle den Typ, der die Rolle der Notiz am besten beschreibt. Der Typ setzt die Defaults für die oben genannten Parameter.

Typ Default Profil Default Gewicht Einsatzzweck
concept sliding_smart_edges 0.60 Fachbegriffe, Theorien. Zeitloses Wissen.
project sliding_smart_edges 0.97 Aktive Vorhaben mit Ziel und Status.
experience sliding_smart_edges 1.10 [NEU] Biografische Lektionen & Prägungen.
insight [NEU] sliding_smart_edges 1.20 Konkrete Beobachtungen/Erkenntnisse (z.B. Erziehung).
trait [NEU] structured_..._strict 1.10 Persönliche Eigenschaften & Potenziale.
obstacle [NEU] structured_..._strict 1.00 Ängste, Blockaden & Hindernisse.
decision structured_..._strict 1.00 Entscheidungen. Muss atomar getrennt sein (Optionen vs. Ergebnis).
value structured_..._strict 1.00 Werte/Prinzipien.
principle structured_..._strict_L3 0.95 Handlungsleitlinien (Trennt bis Ebene H3).
goal sliding_smart_edges 0.95 Strategische Ziele (Nordsterne).
risk sliding_short 0.85 Risiken (kurz und prägnant).
journal sliding_standard 0.80 Zeitbezogene Logs.
source sliding_standard 0.50 Externe Quellen (niedrig gewichtet).

3.2 Status und Bedeutung

Status Bedeutung Auswirkung auf die KI
stable Geprüftes Wissen. Die Notiz ist inhaltlich korrekt, finalisiert und verlässlich (Gold-Standard). 🚀 Bevorzugt (Bonus): Die KI vertraut diesen Inhalten mehr (+20% Relevanz-Score). Bei widersprüchlichen Infos gewinnt stable.
active Standard. Aktuelle Arbeitsnotizen, Projekte oder Dokumentationen (Default, wenn leer). 🔵 Neutral: Standard-Gewichtung (Faktor 1.0).
draft Entwurf. Brainstorming, unstrukturierte Mitschriften oder rohe Ideen. 🔻 Gedämpft (Malus): Die KI nutzt diese Infos nur, wenn es keine besseren Treffer gibt (Relevanz auf 50% reduziert). Reduziert "Rauschen" in den Antworten.
system Intern. Konfigurationsdateien, technische Logs oder Admin-Skripte. ❌ Ignoriert (Hard Skip): Die Datei wird nicht in den Suchindex aufgenommen und ist für den Chat unsichtbar.
template Vorlage. Leere Gerüste für neue Notizen (z.B. für Obsidian). ❌ Ignoriert (Hard Skip): Verhindert, dass leere Vorlagen als Suchergebnisse auftauchen.

Wann nutze ich welchen Status?

  1. Ideenfindung: Setzen Sie neue Ideen immer auf draft. So können Sie frei schreiben, ohne dass die KI sofort "Halbwissen" als Fakten verkauft.
  2. Finalisierung: Sobald eine Entscheidung getroffen oder ein Konzept fertig ist, ändern Sie den Status auf stable.
  3. Konfiguration: Nutzen Sie system für Dateien wie die 01_edge_vocabulary.md, damit die KI nicht die Definition der Kanten zitiert, wenn Sie eigentlich nach Inhalten suchen.

4. Edges & Verlinkung

Mindnet versteht Zusammenhänge durch Kanten.

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

Gültige Relationen:

  • depends_on: Hängt ab von / Benötigt.
  • blocks: Blockiert oder gefährdet (z.B. Risiko -> Projekt).
  • caused_by: Wurde verursacht durch (Kausalität).
  • similar_to: Ähnelt / Ist vergleichbar mit.
  • solves: Löst (Problem).
  • based_on: Basiert auf (Fundament).
  • prev / next [NEU]: Markiert chronologische oder evolutionäre Abfolgen (z.B. Leitbild-Evolution).

4.2 Callout-Edges

Für Zusammenfassungen am Ende einer Notiz:

> [!edge] related_to: [[Vector Embeddings]] [[AI Agents]]

4.3 Implizite Bidirektionalität (Edger-Logik) [NEU] [PRÜFEN!]

In Mindnet musst du Kanten nicht manuell in beide Richtungen pflegen. Der Edger übernimmt die Paarbildung automatisch im Hintergrund.

Deine Aufgabe: Setze die Kante in der Datei, die du gerade bearbeitest, so wie es der logische Fluss vorgibt.

  • Blick zurück (Rückwärtslink): Wenn du ein Ergebnis dokumentierst, nutze derived_from, based_on oder prev.
  • Blick nach vorn (Vorwärtslink): Wenn du einen Plan oder ein Protokoll schreibst, nutze resulted_in, supports oder next.

System-Logik (Beispiele):

  • Schreibst du in Note A: next: [[B]], weiß das System automatisch: B prev A.
  • Schreibst du in Note B: derived_from: [[A]], weiß das System automatisch: A resulted_in B.

Vorteil: Keine redundante Datenpflege, kein "Link-Nightmare", volle Konsistenz im Graphen.

5. Schreiben für den KI-Zwilling (Szenarien)

Damit der RAG-Chat dich berät, musst du "Futter" für die Decision Engine liefern.

Szenario A: Decision Engine (DECISION)

  • Ziel: Das System soll abwägen: "Passt Tool X zu mir?"

  • Vorgehen: Erstelle Notizen mit type: value oder type: goal.

  • Effekt: Wenn du fragst "Soll ich Notion nutzen?", lädt die Engine diese Notiz und antwortet: "Nein, Notion ist SaaS ohne E2E. Das verletzt dein Prinzip der Datensparsamkeit."

Szenario B: Empathie (EMPATHY)

  • Ziel: Das System soll dich verstehen.
  • Vorgehen: Erstelle type: experience mit emotionalen Brückenwörtern.

Beispiel Notiz:

---
type: experience
title: Erfahrung: Der Durchbruch nach der Krise
tags: [krise, hoffnung, grau, angst]
---
Es gibt Projektphasen, da wirkt alles **sinnlos** und **grau**.
Ich habe gelernt: Das ist oft das Zeichen kurz vor dem Durchbruch.
  • Effekt: Bei "Alles ist grau" findet das System diese Notiz und spiegelt die Lektion zurück.

Szenario C: Forward-Mapping (Lücken-Analyse) [NEU]

  • Ziel: Strategische Wissenslücken füllen.
  • Vorgehen: Erstelle Hub-Notizen mit Forward-Links auf noch nicht existierende Dateien (z. B. [[Besten Version meiner Selbst]]).
  • Effekt: Das System erkennt die semantische Bedeutung des geplanten Wissens und kann proaktiv Fragen stellen, um diese Lücken zu schließen.

Szenario D: Narratives Gedächtnis (Intention) [NEU]

  • Ziel: Das System soll verstehen, warum eine Entscheidung getroffen wurde, um in ähnlichen künftigen Situationen konsistent zu beraten.
  • Vorgehen: Nutze in journal- oder experience-Notizen Abschnitte für "Hintergrund" und "Interpretation".
  • Beispiel: Statt "Wert: Disziplin" schreibe "Ich wähle Disziplin, weil ich in meiner Kindheit erlebt habe, wie Willkür schadet."
  • Effekt: Die KI spiegelt nicht nur die Regel, sondern die Überzeugung dahinter.

6. Best Practices & Beispiele

6.1 Beispiel: Projekt-Notiz (Standard)

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

6.2 Beispiel: Advanced Tuning (Manuelles Override)

Hier zwingen wir das System, eine Entscheidung extrem kleinteilig (strict) zu zerlegen und in der Suche maximal zu priorisieren.

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

# Entscheidung: Qdrant

Wir haben uns für Qdrant entschieden.

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

7. Virtual Schema Layer

Grundsätzlich gilt das Prinzip des Virtual Schema Layers. Die Logik (wie chunk_size) wird zentral in der types.yaml verwaltet. Aber: Als Power-User hast du über die Overrides jederzeit die Möglichkeit, aus diesem Standard auszubrechen.