mindnet/docs/knowledge_design.md

title	id	type	status	version	created	updated	tags	owner
mindnet – Knowledge Design	design-knowledge-architecture	guide	active	1.3.0	2025-09-02	2025-09-09	type/guide area/mindnet topic/obsidian topic/knowledge-architecture	Ich

mindnet – Knowledge Design

1. Gesamtziel, Anspruch & Nutzen

Ziel:
mindnet ist ein persönliches Wissensnetzwerk, das alle relevanten Informationen über mein Leben, meine Werte, Projekte, Erfahrungen, Pläne und Erkenntnisse strukturiert erfasst. Es bleibt portabel (Markdown + YAML), ist parser-freundlich, und so gestaltet, dass Tools (Obsidian + Dataview, Embeddings/Vektorsuche via Qdrant, Agenten) es maschinenlesbar nutzen können.

Anspruch an die Struktur:

• Stabil: robuste IDs, deterministische Dateinamen, konsistente Feldnamen
• Atomar: eine Kernaussage/ein zentrales Thema pro Datei (keine Sammelcontainer)
• Erweiterbar: neue Typen jederzeit möglich (ohne Migrationsschmerz)
• Portabel: pures Markdown + YAML → funktioniert in Obsidian, Git, Parsern
• Vernetzbar: systematische Links/Backlinks bilden ein navigierbares Wissensnetz
• Parser-freundlich: wiederkehrende Abschnittsüberschriften, klare Enums

Nutzen / Einsatzzwecke:

• Schnelles Wiederfinden: Dataview-Abfragen, Filter, Dashboards
• LLM-gestütztes Arbeiten: Q&A mit Kontext-Zitaten aus Chunks (RAG)
• Agenten: Vorschläge für Verbindungen/Struktur; Auflösen von „unresolved links“
• Projektnavigation: Aufgabenbeziehungen, Abhängigkeiten
• Langfristiges Gedächtnis: Lebens-/Projektchronik (rückblickend und planend)
• Automatisierung: Vektor-Index (Qdrant), Embeddings, LLM-Q&A, Agenten-Workflows

---

2. YAML-Frontmatter-Schema

Pflichtfelder: title, id, type, status, created, tags
Empfohlen: updated, area, project, priority, aliases, lang, people, depends_on, source u. a.

2.1 Feldübersicht

Feld	Typ	Bedeutung
title	string	Menschlich lesbarer Titel
id	string (slug/identifier)	Stabile ID; referenzierbar über Wikilinks
type	enum	concept, thought, experience, task, project, journal, person, meeting, milestone, …
status	enum	draft | active | done | archived
created	date	Erstellungsdatum (ISO)
updated	date	Letzte Änderung (ISO)
area	string	Themen-/Lebensbereich (z. B. „mindnet“, „gesundheit“, „familie“)
project	string	Projekt-/Arbeitskontext
tags	list	Taxonomische Tags (präfixiert, s. Abschnitt 4)
aliases	list	Alternative IDs/Titel (Slug-Resolver)
lang	string	Sprache, optional (z. B. de, en)
priority	enum/int	Priorität, optional (low/med/high oder 1–5)
due, effort_min	date/int	Für Aufgaben/Projekte (Fälligkeit, Aufwand in Minuten)
people	list	Beteiligte Personen/IDs
depends_on	list	Abhängigkeiten auf andere IDs
source	string	Quelle (Artikel, Buch, Video, …)
slug	string	Stabiler Pfad-/Dateiname, falls abweichend

2.2 Konventionen

• id ist menschenlesbar (Slug), eindeutig im Vault; aliases dienen als Fallback-IDs.
• Datumsformat: ISO YYYY-MM-DD.
• Keine duplizierten Tags; Präfixe nutzen (area/…, type/…, topic/…).
• Frontmatter nur Fakten/Metadaten, keine ausufernden Inhalte (die stehen in den Body-Abschnitten).

2.3 Minimalbeispiel Frontmatter

title: "Gedanke: YAML-Standards"
id: thought-yaml-standards
type: thought
status: draft
created: 2025-09-02
updated: 2025-09-09
area: mindnet
project: project-mindnet
tags: [area/mindnet, type/thought, topic/yaml]
aliases: [yaml-gedanken]
lang: de

2.4 Enum-Werte (Beispiele)

• type: concept, thought, experience, task, project, journal, person, meeting, milestone, manifesto
• status: draft, active, done, archived
• priority: low, med, high oder 1–5

---

3. Dateinamen-Konventionen

• YYYY-MM-DD_title.md oder slug.md.
• Pfade relativ zum Vault; keine absoluten Pfade (einheitliche Slashes /).
• Verzeichnisse nach eigener Ordnung, empfohlen: 10_thoughts/, 20_concepts/, 30_projects/, 40_journal/, …

---

4. Tagging-Regeln & Taxonomie

• Präfixe verwenden: area/…, type/…, topic/…, status/….
• Möglichst keine losen Ein-Wort-Tags ohne Präfix (verhindert Wildwuchs).
• Für Dataview konsistente Namespaces beibehalten (z. B. topic/llm, topic/lernen).

---

5. Backlink- & Link-Regeln

• Wikilinks: [[stabile-id]] oder [[Titel|stabile-id]]

• Im Fließtext verlinken (Forwardlinks); am Ende optional „Mögliche Verbindungen“ redaktionell pflegen:

  Mögliche Verbindungen

  • concept-persoenliches-leitbild
  • project-mindnet

• Linkrichtung: „aufwärts“ (Detail → Konzept/Leitbild) und „seitwärts“ (verwandte Knoten).

• Optional zusätzliche ID-Relationen im YAML (related_ids) für Parser.

• Unresolved Links: Links auf noch nicht existierende Ziele sind zulässig; der Importer schreibt status: unresolved-Edges (später durch Resolver/Agent heilbar).

---

5.1 Edge-Typen & Semantik (Graph)

Beziehungen werden als Edges mit neuem Payload-Schema gespeichert:

kind        : "belongs_to" | "next" | "prev" | "references" | "backlink" | "unresolved"
source_id   : ID des Quellknotens (Chunk- oder Note-ID)
target_id   : ID des Zielknotens  (Note- oder Chunk-ID)
scope       : "chunk" | "note"
note_id     : Owner-Note des Edges (für schnelles Filtern/Purge)
status      : optional, z. B. "unresolved"

Kantenarten

• belongs_to — Chunk → Note
  Jeder Chunk gehört zu genau einer Note. Scope: chunk.

• prev / next — Chunk → Chunk
  Lineare Reihenfolge innerhalb derselben Note; symmetrisch angelegt (d. h. prev und next konsistent). Scope: chunk.

• references — Chunk → Note
  Aus [[Wikilinks]] oder Markdown-Links im Chunk-Text (präzise Herkunft). Scope: chunk.

• backlink — Note → Note
  Automatisch generierte Gegenkante zu references (pro Note dedupliziert). Scope: note.

• unresolved
  Edge mit status: "unresolved", wenn target_id (noch) nicht existiert. Wird später vom Resolver/Agent ersetzt.

• Optional: references:note — Note → Note
  Zusätzliche Forwardlinks auf Note-Ebene; standardmäßig deaktiviert, um Doppelzählungen mit references (Chunk-Scope) zu vermeiden. Aktivierung per ENV/Flag möglich.

Performanzhinweise (Qdrant)

• Edges werden dedupliziert über (kind, source_id, target_id, scope).

• note_id ist Pflichtfeld im Edge-Payload (Owner-Note).

• Payload-Indizes für Qdrant anlegen:

  edges  : kind (KEYWORD), scope (KEYWORD), source_id (KEYWORD), target_id (KEYWORD), note_id (KEYWORD)
  chunks : note_id (KEYWORD), chunk_index (INTEGER)
  notes  : note_id (KEYWORD)
  

---

6. Abschnitts-Konventionen im Body

Einheitliche Überschriften erleichtern Parser, Chunking und Abfragen. Typ-spezifische Empfehlungen:

• Gedanke (thought)
  ## Zusammenfassung · ## Begründung / Details · ## Belege / Quellen · ## Nächste Schritte · ## Mögliche Verbindungen

• Erfahrung (experience)
  ## Kontext · ## Beobachtung · ## Interpretation · ## Implikationen · ## Mögliche Verbindungen

• Aufgabe (task)
  ## Checkliste · ## Notizen · ## Nächste Schritte · ## Mögliche Verbindungen

• Projekt (project)
  ## Scope · ## Arbeitspakete · ## Risiken & Gegenmaßnahmen · ## Status / Fortschritt · ## Mögliche Verbindungen

• Journal (journal)
  ## Tageszusammenfassung · ## Highlights · ## Learnings · ## Mögliche Verbindungen

• Meeting (meeting)
  ## Agenda · ## Notizen · ## Entscheidungen · ## Aufgaben · ## Mögliche Verbindungen

---

7. Abbildung persönlicher Inhalte auf Typen

Richtlinien:

• Wähle den Typ nach Hauptintention (Definition, Gedanke, Beobachtung, Aufgabe, Projekt, …).
• Konzepte (concept): langlebige Definitionen, Prinzipien, Leitbilder.
• Gedanken (thought): explorative Ideen, noch nicht stabil (können später bei Reife in concept überführt werden).
• Erfahrungen (experience): Beobachtungen & Learnings aus der Praxis.
• Aufgaben (task): konkrete, umsetzbare To-dos mit due/effort_min.
• Projekte (project): Ziele, Deliverables, Arbeitspakete, Abhängigkeiten.
• Journal (journal): tagesbasierte Notizen, Reflexionen, Reiseberichte.
• Personen (person): Kontakte, Profile, Bezüge, Gespräche.
• Meetings (meeting): Agenda, Notizen, Entscheidungen, Folgeaufgaben.
• Meilensteine (milestone): wichtige Wendepunkte im Lebens-/Projektverlauf.

---

8. Beispiel-Notizen

8.1 Gedanke (thought) – Beispiel

Frontmatter

title: "Gedanke: Übungen für tiefe Arbeit"
id: thought-deep-work-uebungen
type: thought
status: active
created: 2025-08-21
updated: 2025-09-05
area: lernen
project: project-self-improvement
tags: [area/lernen, type/thought, topic/fokus]
aliases: [deep-work-ideen]
lang: de

Body (Ausschnitt)

## Zusammenfassung
Kurze tägliche Routinen (z. B. Timer-Blöcke, Ablenkungslog) erhöhen meinen Fokus.

## Begründung / Details
- 25–45 Min Timerblöcke mit 5 Min Pause
- Ablenkungen sofort notieren
- Abschluss-Log am Ende des Tages

## Mögliche Verbindungen
- [[concept-deep-work]]
- [[project-productivity-week]]

8.2 Konzept (concept) – Beispiel

Frontmatter

title: "Konzept: Deep Work"
id: concept-deep-work
type: concept
status: active
created: 2024-05-14
updated: 2025-08-01
area: lernen
tags: [area/lernen, type/concept, topic/fokus]
aliases: [konzept-tiefe-arbeit]
lang: de

Body (Ausschnitt)

## Definition
Tiefe Arbeit = kognitiv anspruchsvolle Arbeit ohne Ablenkung.

## Belege / Quellen
- Buch: Cal Newport – Deep Work

## Mögliche Verbindungen
- [[thought-deep-work-uebungen]]

8.3 Aufgabe (task) – Beispiel

Frontmatter

title: "Task: Wochenplanung erstellen"
id: task-week-planning
type: task
status: active
created: 2025-09-07
updated: 2025-09-07
due: 2025-09-11
effort_min: 45
area: organisation
project: project-productivity-week
tags: [area/organisation, type/task, topic/planung]
lang: de

Body (Ausschnitt)

## Checkliste
- Ziele der Woche definieren
- 5 Fokusblöcke eintragen
- 2 Lerneinheiten terminieren

## Mögliche Verbindungen
- [[project-productivity-week]]
- [[thought-deep-work-uebungen]]

---

9. Schrittweise Migration bestehender freier Notizen

1. Frontmatter ergänzen (min. id, title, type, status, created, tags).
2. Abschnittsstruktur an Typ anpassen (Konventionen s. Abschnitt 6).
3. Wikilinks im Body setzen (statt bloßer Erwähnungen).
4. Tags normalisieren (Präfixe, Kleinschreibung, keine Dubletten).
5. Aliases angeben, falls Notiz zuvor unter anderem Namen existierte.
6. Testlauf: Import (Dry-Run), danach Apply, Audit/Validate prüfen.

---

10. Dataview-Beispiele (direkt nutzbar)

Aktive Gedanken der letzten 30 Tage

TABLE title, created, updated, area
FROM "10_thoughts"
WHERE type = "thought" AND status = "active" AND created >= date(today) - dur(30 days)
SORT updated DESC

Offene Tasks mit Fälligkeit

TABLE title, due, effort_min, project, area
FROM "30_tasks"
WHERE type = "task" AND status = "active" AND due
SORT due ASC

Konzepte je Topic

TABLE title, area, tags
FROM "20_concepts"
WHERE contains(tags, "type/concept")
GROUP BY choice(regexreplace(join(filter(tags, (t) => startswith(t, "topic/")), ", "), "^topic/", ""))

Verknüpfungskandidaten (redaktionell, nicht automatisch)
(Liste am Ende der jeweiligen Notiz in „Mögliche Verbindungen“)

---

11. Validierung & Pflege

• Linter/Validator prüfen Pflichtfelder und Wertebereiche (Enums, ISO-Datum).
• Resolver löst unresolved-Edges, wenn neue Notizen/Aliases entstehen.
• Idempotente Re-Imports: Hash-Steuerung konfigurierbar:
  • MINDNET_HASH_MODE: body | frontmatter | body+frontmatter (Default: body)
  • MINDNET_HASH_NORMALIZE: canonical | none (Default: canonical)
• Edge-Invarianten (Audit):
  • belongs_to == #Chunks
  • next == prev == Σ(max(chunks_in_note−1, 0))
  • references (chunk) == Σ(Chunk-Wikilinks)
  • backlink == Σ(eindeutige Wikilinks je Note)
• Roundtrip-Test: Import → Export → Diff muss Body verlustfrei rekonstruieren.

---

12. Qdrant-Ablage & Indizes

Collections

• {prefix}_notes – Vektor optional (Nullvektor oder Zentroid), Payload inkl. Frontmatter & fulltext
• {prefix}_chunks – 384d Embedding je Chunk, Payload inkl. text, chunk_index, note_id
• {prefix}_edges – 1d Dummy-Vektor, Payload im neuen Schema (s. 5.1)

IDs & Idempotenz

• Deterministisch/UUIDv5 über stabile Schlüssel (note_id, chunk_id = note_id#cNN, edge_id aus (kind, source_id, target_id, scope))
• Re-Imports erzeugen keine Duplikate (Upsert)

Payload-Indizes (Performance)

notes  : note_id (KEYWORD)
chunks : note_id (KEYWORD), chunk_index (INTEGER)
edges  : kind (KEYWORD), scope (KEYWORD), source_id (KEYWORD), target_id (KEYWORD), note_id (KEYWORD)

Delete/Purge

• Selektives Löschen in Edges/Chunks per note_id-Filter (schnell, sicher).
• --sync-deletes (geplant): Qdrant→Vault Diffs gezielt entfernen (mit Dry-Run).

---

13. LLM/RAG & Agenten – Arbeitsweise (Überblick)

Retriever (Hybrid)

1. kNN (Chunks) in Qdrant → Top-k Kandidaten (Semantik).
2. Nachbarschafts-Expand (1 Hop) über Edges (belongs_to, references, backlink) → zusätzliche Kontexte.
3. Rerank (optional BM25/LLM-score).
4. Prompt mit Zitaten/Belegen (Verweis auf path + Abschnittstitel).

Agentisches Einordnen (neue Inputs)

• Chunking + Embedding → kNN-Kandidaten
• Klassifikation (type, area, project) via Heuristik/LLM
• Edge-Vorschläge: references (Semantik + geteilte Tags/Area), belongs_to (beste Einordnung)
• Falls kein Ziel existiert → unresolved erzeugen oder Stub-Note anlegen
• Human-in-the-loop: Vorschläge bestätigen, dann Commit via Importer

Graph-Layer (optional, empfohlen)

• Zusätzliche SQLite/Postgres-Tabellen nodes/edges/aliases für 2–3-Hop-Queries, Pfadsuche, Zählungen.
• Importer pflegt Qdrant und SQL (UPSERT).
• Graph-Features (Degree, Communities, optional PageRank) regelmäßig berechnen und als Felder in notes.payload speichern.

---

14. Versions- & Änderungsrichtlinien

• Kleine Änderungen direkt in der bestehenden Notiz (Frontmatter updated anpassen).
• Große Strukturänderungen (z. B. neuer Typ) als neue Notiz mit Verweis; alte Note verlinken/archivieren (status: archived).
• IDs nie recyceln (Konstanz für Referenzen und Edges).
• Aliases nutzen, wenn sich Titel/Slug ändert (Resolver kann beides auflösen).
• Commit-Meldungen im Git prägnant strukturieren:
  • feat(note): … · fix(frontmatter): … · chore(tags): … · refactor(structure): …

---

15. Typen-Kurzreferenz

• concept — Definitionen, Leitbilder, Prinzipien
  Empfohlene Abschnitte: Definition, Beispiele, Belege, Mögliche Verbindungen

• thought — Ideen, Entwürfe, Skizzen
  Abschnitte: Zusammenfassung, Details, Nächste Schritte, Mögliche Verbindungen

• experience — Beobachtungen, Learnings
  Abschnitte: Kontext, Beobachtung, Interpretation, Implikationen, Mögliche Verbindungen

• task — konkrete To-dos
  Felder: due, effort_min; Abschnitte: Checkliste, Notizen, Mögliche Verbindungen

• project — Ziele, Deliverables, Arbeitspakete
  Abschnitte: Scope, Arbeitspakete, Risiken, Status, Mögliche Verbindungen

• journal — tagesbasierte Einträge
  Abschnitte: Tageszusammenfassung, Highlights, Learnings, Mögliche Verbindungen

• person — Kontakte, Profile
  Felder: people (Selbst-/Fremd-ID), Notizen, Mögliche Verbindungen

• meeting — Termine, Protokolle
  Abschnitte: Agenda, Notizen, Entscheidungen, Aufgaben, Mögliche Verbindungen

• milestone — Wendepunkte
  Abschnitte: Kontext, Bedeutung, Verknüpfungen

---

16. Erweiterungen

• Neue Typen (z. B. decision, recommendation, resource) können ohne Bruch ergänzt werden.
• Personalisierung durch zusätzliche Properties (values, goals) in Frontmatter.
• Internationale Inhalte: lang pflegen, optional mehrsprachige Embeddings (z. B. mE5).

---

17. Anhang – Beispiele & Snippets

Beispiel: YAML-Frontmatter für Projekt

title: "Projekt: Produktivität Woche 37"
id: project-productivity-week
type: project
status: active
created: 2025-09-08
updated: 2025-09-09
area: organisation
tags: [area/organisation, type/project, topic/planung]
people: [ich]
depends_on: [concept-deep-work]
lang: de

Beispiel: Redaktions-Sektion (keine Kanten-Erzeugung)

## Mögliche Verbindungen
- [[concept-wochenplanung]]
- [[thought-deep-work-uebungen]]
- [[journal-2025-09-08]]

CLI: Import & Audit

# Dry-Run Import
python3 -m scripts.import_markdown --vault ./vault

# Apply mit strenger Hash-Erkennung (jede Änderung zählt)
python3 -m scripts.import_markdown --vault ./vault --apply --hash-normalize none

# Audit Edges vs. Erwartungen
python3 -m scripts.audit_edges_vs_expectations --vault ./vault

---

18. Glossar

• Alias: alternativer Name/Slug, der auf dieselbe Note verweist
• Backlink: automatisch erzeugte Gegenkante zu references (Note-Scope)
• Chunk: semantisch sinnvoller Textabschnitt einer Note, inkl. Embedding
• Owner-Note: Note, zu der ein Edge gehört (note_id im Edge-Payload)
• Resolver: Prozess/Script, das unresolved-Edges bei späterer Ziel-Existenz heilt

---

19. Verweise

• chunking_strategy.md – Details zu Chunkgrößen, Overlaps, Abschnittsregeln
• schemas/note.schema.json – Validierung von Frontmatter‐Feldern
• Import/Export-Skripte: scripts/import_markdown.py, scripts/export_markdown.py
• Qdrant-Client/Setup: app/core/qdrant.py, app/core/qdrant_points.py

---

20. Änderungsverlauf

• 1.3.0 (2025-09-09)

  • Edge-Politik präzisiert: references (Chunk-Scope), backlink (Note-Scope), references:note optional.
  • note_id als Pflichtfeld im Edge-Payload (Owner).
  • Qdrant-Payload-Indizes ergänzt (Performanz).
  • Beispiele & Dataview-Snippets erweitert.

• 1.2.0 (2025-09-02)

  • Erstfassung des Knowledge-Designs.