From 93739935b7c9e4a398922ae439ecea06410005bd Mon Sep 17 00:00:00 2001 From: Lars Date: Tue, 9 Sep 2025 11:56:54 +0200 Subject: [PATCH] docs/knowledge_design.md aktualisiert --- docs/knowledge_design.md | 505 ++++++--------------------------------- 1 file changed, 72 insertions(+), 433 deletions(-) diff --git a/docs/knowledge_design.md b/docs/knowledge_design.md index dde4d13..a356991 100644 --- a/docs/knowledge_design.md +++ b/docs/knowledge_design.md @@ -1,436 +1,75 @@ ---- -title: "mindnet – Knowledge Design" -id: "design-knowledge-architecture" -type: "guide" -status: "active" -version: "1.2.0" -created: 2025-09-02 -updated: 2025-09-02 -tags: ["type/guide","area/mindnet","topic/obsidian","topic/knowledge-architecture"] -owner: "Ich" ---- - -# mindnet – Knowledge Design - -## 1. Gesamtziel, Anspruch & Nutzen - -**Ziel:** -*mindnet* ist ein persönliches Wissensnetzwerk, das **alle** relevanten Inhalte – Gedanken, Erfahrungen, Aufgaben, Projekte, Quellen, Personen, Meetings, Tagebuch/Journal, Wendepunkte und Leitbilder – **einheitlich** in Markdown + YAML ablegt. Es bildet einen **Spiegel der Persönlichkeit** (Werte, Überzeugungen, Erlebnisse) und ist zugleich so strukturiert, dass Tools (Dataview, Embeddings, Vektorsuche/Qdrant, Agenten) es **maschinenlesbar** nutzen können. - -**Anspruch an die Struktur:** -- **Stabil**: robuste IDs, deterministische Dateinamen, konsistente Feldnamen -- **Atomar**: ein Kerninhalt pro Datei (keine Sammelcontainer) -- **Erweiterbar**: neue Typen (z. B. `milestone`, `manifesto`) jederzeit möglich -- **Portabel**: reines Markdown + YAML → funktioniert in Obsidian, Git und Parsern -- **Vernetzbar**: systematische Links/Backlinks erzeugen ein sinnvoll navigierbares Netz -- **Parser-freundlich**: wiederkehrende Abschnittsüberschriften; Felder/Enums klar definiert - -**Späterer Nutzen / Einsatzzwecke:** -- **Schnelles Wiederfinden**: Dataview-Abfragen, Filter, Dashboards -- **Selbstreflexion & Entwicklung**: persönliche Werte, Wendepunkte, Kinderentwicklung, Lernpfade -- **Automatisierung**: Vektor-Index (Qdrant), Embeddings, LLM-Q&A, Agenten-Workflows -- **Langfristiges Gedächtnis**: eigene Lebens-/Projektchronik reproduzierbar pflegen -- **Aufgaben-/Projektsteuerung**: im selben System, vernetzt mit Kontextwissen --- -## 2. YAML-Frontmatter-Schema - -> **Pflichtfelder:** `title`, `id`, `type`, `status`, `created`, `tags` -> **Empfohlen:** `updated`, `area`, `project`, `priority`, `aliases` (u. a.) - -### 2.1 Feldübersicht - -| Feld | Typ | Bedeutung | Beispiel(e) | -|---------------------|-------------------------------|---------------------------------------------------------------------------|------------------------------------------------------------------------------| -| `title` | string | Menschlich lesbarer Titel | `"Vektorsuche in Qdrant"` | -| `id` | string (slug/identifier) | **Stabile** technische ID (nie umbenennen) | `"20250902-1710-thought-obsidian-struktur"`, `"concept-persoenliches-leitbild"` | -| `type` | enum | Notiz-Typ | `thought`, `experience`, `task`, `project`, `source`, `concept`, `person`, `meeting`, `journal`, `milestone` | -| `status` | enum | Lebenszyklus | `idea`, `draft`, `active`, `paused`, `blocked`, `done`, `archived` | -| `created` | date/datetime | Erstellzeitpunkt | `2025-09-02` oder `2025-09-02T17:10:00+02:00` | -| `updated` | date/datetime | Letzte inhaltliche Änderung | `2025-09-02T18:05:00+02:00` | -| `tags` | string[] | Schlagwörter gemäß Taxonomie | `["area/mindnet","topic/obsidian","type/thought"]` | -| `area` | enum/string | Lebens-/Arbeitsbereich | `mindnet`, `family`, `karate`, `travel`, `health`, `home-automation`, … | -| `role` | string | Rolle/Hut (Filter) | `"father"`, `"researcher"`, `"project-owner"` | -| `project` | string | Zugehöriges Projekt (ID oder sprechend) | `"project-mindnet"` | -| `priority` | int (1–5) | 1 = hoch, 5 = niedrig | `2` | -| `effort_min` | int | Aufwand in Minuten (für `task`) | `90` | -| `due` | date | Fälligkeit (Task/Projekt) | `2025-09-10` | -| `start` | date | geplanter Start (Task/Projekt) | `2025-09-05` | -| `people` | string[] (Wikilinks erlaubt) | Beteiligte Personen | `["Ich","[[person-kathie]]"]` | -| `location` | string | Ort/Platz | `"Home Office"`, `"München"` | -| `source_url` | url | Kanonische URL (für `source`) | `"https://qdrant.tech/docs/"` | -| `authors` | string[] | Autoren (für `source`) | `["Jane Doe"]` | -| `published` | date | Veröffentlichungsdatum (für `source`) | `2024-11-20` | -| `accessed` | date | Zugriffsdatum (für `source`) | `2025-09-02` | -| `aliases` | string[] | Alternative Namen/Titel | `["Manifest","Leitbild"]` | -| `related_ids` | string[] | ID-basierte Verknüpfungen | `["concept-persoenliches-leitbild"]` | -| `embedding_exclude` | boolean | Von Embeddings/Index ausschließen | `false` | - -### 2.2 Konventionen -- **IDs:** entweder Zeitstempel-basiert (`YYYYMMDD-HHMM-type-slug`) **oder** stabile, sprechende (`concept-*`, `project-*`, `person-*`). -- **Datums-/Zeitformat:** ISO 8601, Zeiten möglichst mit TZ (z. B. `+02:00`). -- **Felder:** klein geschrieben; zusammengesetzte Felder in `snake_case`. - -### 2.3 Minimalbeispiel Frontmatter - --- - title: "Kurzer, klarer Gedanke" - id: "20250902-1715-thought-klarer-gedanke" - type: "thought" - status: "idea" - created: 2025-09-02T17:15:00+02:00 - updated: 2025-09-02T17:15:00+02:00 - tags: ["area/mindnet","type/thought","topic/obsidian"] - --- - -## 2.4 Enum-Werte - -Zur Sicherstellung der Konsistenz werden für bestimmte Felder feste Wertemengen (Enums) verwendet: - -- **type** - - `idea` – spontane Gedanken, Inspirationen - - `experience` – persönliche Erfahrungen, Reflexionen - - `task` – konkrete Aufgaben - - `project` – Projekte, bestehend aus mehreren Tasks - - `concept` – abstrakte Konzepte, Modelle, Methoden - - `milestone` – wichtige Ereignisse oder Wendepunkte - - `person` – Personen (z. B. Kontakte, Vorbilder) - - `meeting` – Besprechungen, Treffen, Gespräche - - `resource` – externe Quellen (Artikel, Bücher, Links) - - `journal` – Tagebuchnotizen - -- **status** - - `open` - - `in-progress` - - `done` - - `blocked` - - `canceled` - -- **priority** - - `low` - - `medium` - - `high` - -- **area** (Beispiele – erweiterbar) - - `personal` - - `work` - - `family` - - `karate` - - `health` - - `finance` - ---- - -## 3. Dateinamen-Konventionen - -> Keine Sonderzeichen wie `: / \` im Dateinamen. - -- **Zeitbasierte Notizen (Gedanken, Journal, tagesgebundene Einträge):** - `YYYYMMDD-HHMM--.md` - Beispiel: `20250902-1710-thought-obsidian-struktur.md` - -- **Zeitunabhängige Wissensknoten (Konzepte, Personen, Projekte, Leitbild):** - `-.md` - Beispiele: `concept-vektorsuche-qdrant.md`, `project-mindnet.md`, `person-kathie.md`, `concept-persoenliches-leitbild.md` - -- **Ordnerstruktur (Empfehlung):** -00_inbox/ -10_thoughts/ -20_experiences/ -30_projects/ -31_tasks/ -40_concepts/ -50_sources/ -60_people/ -70_meetings/ -80_journal/ -90_templates/ -_attachments/ -_meta/ - ---- - -## 4. Tagging-Regeln & Taxonomie - -- **Hierarchische Tags:** - - `area/*` – Lebens-/Arbeitsbereiche: `area/mindnet`, `area/family`, `area/karate`, `area/health`, … - - `type/*` – optionaler Spiegel von `type`: `type/thought`, `type/experience`, … - - `topic/*` – thematische Schwerpunkte: `topic/obsidian`, `topic/yaml`, `topic/qdrant`, `topic/werte`, … - - optional: `place/*`, `person/*`, `level/*` (z. B. `person/rouven`, `person/rohan`) -- **Regeln:** - - Jede Notiz hat **mindestens ein** `area/*`. - - `topic/*` sparsam, aber konsistent; ein Mapping in `_meta/tags.md` pflegen. - - Möglichst **keine** losen Ein-Wort-Tags ohne Präfix (verhindert Wildwuchs). - ---- - -## 5. Backlink- & Link-Regeln - -- **Wikilinks** verwenden: `[[stabile-id-oder-dateiname]]` -- Im **Fließtext** bei erster Nennung verlinken; am **Ende** die Sektion **„Mögliche Verbindungen“** pflegen: - - ## Mögliche Verbindungen - - [[concept-persoenliches-leitbild]] - - [[project-mindnet]] - -- **Linkrichtung:** „aufwärts“ (Detail → Konzept/Leitbild) und „seitwärts“ (verwandte Knoten). -- Optional zusätzlich **ID-Relationen** im YAML (`related_ids`) für Parser. - -## 5.1 Edge-Typen - -Beziehungen zwischen Notizen, Chunks und Objekten werden als **Edges** gespeichert. Jeder Edge erhält einen `type` und optionale `meta`-Informationen (z. B. Gewichtung, Richtung). - -- **belongs_to** - Chunk → Note (ein Chunk gehört zu genau einer Note) - -- **references** - Note → Note (eine Notiz verweist auf eine andere) - -- **backlink** - Automatisch generiert: Gegenkante von `references` - -- **depends_on** - Task → Task oder Task → Project (Aufgabe hängt von anderer ab) - -- **assigned_to** - Task → Person (eine Aufgabe ist einer Person zugeordnet) - -- **discussed_in** - Note/Concept → Meeting (ein Thema wurde in einem Meeting behandelt) - -- **authored_by** - Note → Person (z. B. externer Autor oder eigene Urheberschaft) - -- **related** - Generische Relation für schwache Assoziationen - ---- - -## 6. Abschnitts-Konventionen im Body - -Einheitliche Überschriften erleichtern spätere Parser und Abfragen. - -- **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` · `## Mögliche Verbindungen` -- **Projekt (`project`)** - `## Scope` · `## Arbeitspakete` · `## Risiken & Gegenmaßnahmen` · `## Status / Fortschritt` · `## Mögliche Verbindungen` -- **Journal (`journal`)** - `## Tageszusammenfassung` · `## Highlights` · `## Gelernt / Notizen` · `## Mögliche Verbindungen` - ---- - -## 7. Abbildung persönlicher Inhalte auf Typen - -- **Persönliches Leitbild** → `type: "concept"` (oder optional neuer Typ `manifesto`) - Datei: `concept-persoenliches-leitbild.md` (zeitunabhängig) - Verlinkt zu prägenden Erfahrungen und Wendepunkten. -- **Erfahrungen, die dich geprägt haben** → `type: "experience"` - Je **eine** prägende Erfahrung pro Datei; klarer Kontext + Interpretation. -- **Wendepunkte im Leben** → `type: "milestone"` - Je Wendepunkt ein Knoten; verlinkt zu den auslösenden Erfahrungen. -- **Aktuelle Erfahrungen** → `type: "experience"`, `status: "active"` - Bei Bedarf später in „prägende“ Erfahrungen überführen. -- **Entwicklungsschritte der Kinder** → `type: "journal"` (chronologisch) **oder** `experience` (wenn es prägend ist); Tags `person/`. -- **Tagebucheinträge** → `type: "journal"`; ein Eintrag pro Tag; tagesbasierte Dateinamen. - -Damit entsteht ein **netzartiges Persönlichkeitsprofil** mit klaren Pfaden zwischen Werten (Leitbild), Ereignissen (Erfahrungen), Wendepunkten und fortlaufenden Beobachtungen (Journal). - ---- - -## 8. Beispiel-Notizen - -### 8.1 Gedanke (`thought`) - --- - title: "Gedanke: Einheitliche YAML-Standards steigern Recall" - id: "20250902-1830-thought-yaml-recall" - type: "thought" - status: "idea" - created: 2025-09-02T18:30:00+02:00 - updated: 2025-09-02T18:30:00+02:00 - tags: ["area/mindnet","type/thought","topic/yaml","topic/recall"] - area: "mindnet" - project: "project-mindnet" - aliases: [] - --- - - ## Zusammenfassung - Konsistente YAML-Felder verbessern Filter, Dataview-Queries und Vektor-Retrieval. - - ## Begründung / Details - - Parser benötigen stabile Feldnamen (z. B. `type`, `status`). - - Einheitliche Werte erleichtern Dashboards und Automationen. - - ## Belege / Quellen - - [[source-obsidian-properties]] - - [[concept-vektorsuche-qdrant]] - - ## Nächste Schritte - - [ ] `tags`-Mapping in `_meta/tags.md` erstellen - - [ ] Beispiel-Queries für Dataview hinterlegen - - ## Mögliche Verbindungen - - [[project-mindnet]] - - [[20250902-1730-task-yaml-standard-migration]] - -### 8.2 Erfahrung (`experience`) - --- - title: "Erfahrung: Journal → Erfahrung extrahieren erhöht Klarheit" - id: "20250902-1840-experience-journal-extraktion" - type: "experience" - status: "active" - created: 2025-09-02T18:40:00+02:00 - updated: 2025-09-02T18:40:00+02:00 - tags: ["area/personal","type/experience","topic/journal","topic/reflexion"] - area: "personal" - project: "project-mindnet" - --- - - ## Kontext - Wiederkehrende Journaleinträge enthalten Rohmaterial für prägende Einsichten. - - ## Beobachtung - Wird Material regelmäßig zu `experience`-Knoten verdichtet, sind spätere Bezüge einfacher. - - ## Interpretation - Abstraktion + Verlinkung (z. B. auf [[concept-persoenliches-leitbild]]) erhöhen Nutzen und Wiederfindbarkeit. - - ## Implikationen - Pro Woche 15–30 Minuten „Verdichtungs-Review“ einplanen. - - ## Mögliche Verbindungen - - [[journal-20250902]] - - [[concept-persoenliches-leitbild]] - -### 8.3 Aufgabe (`task`) - --- - title: "Task: YAML-Standard in Altbeständen ergänzen" - id: "20250902-1850-task-yaml-migration" - type: "task" - status: "active" - created: 2025-09-02 - updated: 2025-09-02 - due: 2025-09-10 - start: 2025-09-03 - priority: 2 - effort_min: 120 - area: "mindnet" - project: "project-mindnet" - tags: ["area/mindnet","type/task","topic/migration"] - depends_on: [] - --- - - ## Checkliste - - [ ] Triage: Notiz-Typ bestimmen - - [ ] Minimal-YAML ergänzen (Pflichtfelder) - - [ ] Dateinamen vereinheitlichen - - [ ] „Mögliche Verbindungen“ pflegen - - ## Notizen - Beginne mit zuletzt genutzten Notizen (Pareto 20/80). - - ## Mögliche Verbindungen - - [[project-mindnet]] - - [[20250902-1830-thought-yaml-recall]] - ---- - -## 9. Schrittweise Migration bestehender freier Notizen - -**Phase A – Triage (schnell)** -1. Sichtung & **Typ** bestimmen (`type`). -2. **Minimal-YAML** einfügen (`title`, `id`, `type`, `status=draft`, `created≈Dateidatum`, `tags`). -3. **Dateiname** grob anpassen (Schema + Slug). - -**Phase B – Strukturieren (fokussiert)** -1. **Abschnitte** nach Typ-Template ergänzen. -2. **Zerlegen**: mehrere Gedanken/Ereignisse → je **eigene Datei**, ursprüngliche Datei wird zum **Index** mit Links. -3. **Verlinken**: relevante `[[Knoten]]` + **„Mögliche Verbindungen“** pflegen. - -**Phase C – Verfeinern (bei Bedarf)** -1. **Status & Felder** pflegen (`status`, `priority`, `due`, `effort_min`). -2. **Tag-Harmonisierung**: Mapping-Tabelle pflegen (`_meta/tags.md`). -3. **Aliases** ergänzen (Such-/Linkvarianten). - -**Priorisierung:** Starte mit **aktuellen & häufig genutzten** Notizen (Pareto-Prinzip), Altbestände nachziehen, wenn sie wieder gebraucht werden. - ---- - -## 10. Dataview-Beispiele (direkt nutzbar) - -**Offene Aufgaben dieser Woche (nach Priorität):** - - TABLE due, priority, effort_min - FROM "31_tasks" - WHERE type = "task" AND status != "done" - AND due >= date(today) - dur(1 week) - AND due <= date(today) + dur(1 week) - SORT priority ASC, due ASC - -**Aktive Projekte mit Meilensteinen:** - - LIST - FROM "30_projects" - WHERE type = "project" AND status = "active" - SORT priority ASC, file.ctime DESC - -**Gedanken im Bereich mindnet, jüngste zuerst:** - - TABLE created, status - FROM "10_thoughts" - WHERE type = "thought" AND area = "mindnet" - SORT created DESC - LIMIT 50 - -**Quellen ohne `source_url` (Pflegebedarf):** - - TABLE title, created - FROM "50_sources" - WHERE type = "source" AND (source_url = "" OR !source_url) - ---- - -## 11. Validierung & Pflege - -- **Wöchentlicher Review-Slot (15–30 Min.):** - - Neue Notizen triagieren (`type`, `status`, `area`) - - 5 Alt-Notizen migrieren (YAML + Dateiname + Verlinkung) -- **Dataview-Checks:** fehlende `source_url`, offene Tasks, aktive Projekte, veraltete `status`. -- **Optional (technisch):** - - **Pre-commit Hook**: prüft Pflichtfelder (`title`, `id`, `type`, `status`, `created`, `tags`) - - **ID-Generator**: `YYYYMMDD-HHMM-type-slug` bei Neuanlage - - **Link-Linter**: prüft tote `[[Links]]` - ---- - -## 12. Versions- & Änderungsrichtlinien - -- Dieses Dokument pflegt `version` & `updated`. -- **Breaking Changes** (z. B. Feldumbenennungen) in `_meta/changelog.md` dokumentieren. -- **Migrationen** (Tag-Refactorings, Typänderungen) als Skript oder Batch-Checkliste planen. - ---- - -## 13. Typen-Kurzreferenz - -- `thought` – Gedanke/These -- `experience` – Beobachtung/Erfahrung mit Interpretation & Implikationen -- `task` – umsetzbare Arbeitseinheit (mit `due`, `effort_min`, `priority`) -- `project` – Container für Ziele/Tasks/Meilensteine -- `source` – externe Quelle (Artikel, Buch, Video) -- `concept` – definierter Begriff / Prinzip / Leitbild -- `person` – Bezugsperson/Kontakt -- `meeting` – Termin mit Agenda, Notizen, erzeugten Aufgaben -- `journal` – Tagebuch-/Reiseeintrag (tagesbasiert) -- `milestone` – Wendepunkt / Meilenstein im Lebens-/Projektverlauf - ---- - -## 14 Erweiterungen - -Zukünftige Typen möglich (z. B. decision, recommendation). - -Personalisierung durch zusätzliche Properties (values, goals) +## `knowledge_design.md` + +```markdown +# knowledge_design.md + +## Ziel & Anspruch +Dieses Dokument definiert die Wissensarchitektur von **mindnet**. +Ziele: +- Persönliches Wissen, Erfahrungen, Pläne und Ideen konsistent speichern. +- Vernetzung durch Backlinks und Wikilinks, auch bei noch nicht vorhandenen Zielen. +- LLM-fähige Abfragen durch semantische Vektoren und strukturierte Graph-Kanten. +- Vollständiger Roundtrip: Markdown ↔ Qdrant ↔ Markdown. + +## YAML-Frontmatter-Schema +**Pflichtfelder** +- `id`: eindeutige Note-ID +- `title`: kurzer Titel +- `type`: z. B. `concept`, `plan`, `journal` +- `created`: ISO-Datum +- `updated`: ISO-Datum + +**Optionale Felder** +- `status`, `area`, `project`, `tags`, `lang`, `slug`, `aliases`, `priority`, `effort_min`, `due`, `people`, `depends_on`, `assigned_to` + +## Dateinamen-Konvention +- Format: `YYYY-MM-DD_title.md` oder `slug.md` +- Pfade relativ zum Vault, z. B. `area/project/note.md` + +## Tagging-Regeln +- Tags im Frontmatter als YAML-Liste (`tags: [#karate, #projektX]`). +- Im Text: `#Tag` erlaubt, aber nicht für die Kantenbildung verwendet. + +## Link-Regeln +- Wikilinks: `[[note-id]]` oder `[[Titel|note-id]]` → erzeugen Edges. +- Forwardlinks (references): Chunk-Scope. +- Backlinks: Note-Scope, automatisch generiert. +- Unresolved-Links: bleiben als Edge mit `status=unresolved` bestehen, bis Zielnote existiert. + +## Edge-Typen +- **belongs_to**: Chunk → Note +- **references**: Chunk → Note (aus Wikilinks im Text) +- **backlink**: Note → Note (automatisch, invers von references) +- **prev / next**: Chunk → Chunk (symmetrisch) +- **unresolved**: Edge mit `status=unresolved`, wenn Ziel fehlt +- **weitere (Tasks/Projekte)**: `depends_on`, `assigned_to`, `related`, etc. + +**Optional:** `references:note` (Note-Scope-References), standardmäßig deaktiviert; aktivierbar via ENV/Flag. + +## Qdrant-Ablage +- Collections: `{prefix}_notes`, `{prefix}_chunks`, `{prefix}_edges` +- Vektoren: + - Notes: Nullvektor oder Zentroid (optional) + - Chunks: 384-d Embeddings + - Edges: 1-d Dummy-Vektor +- IDs: deterministisch via UUIDv5 (idempotent) + +## Payload-Indizes (Performance) +- Notes: `note_id` +- Chunks: `note_id`, `chunk_index` +- Edges: `note_id`, `kind`, `scope`, `source_id`, `target_id` + +## Backlink-Sektion im Markdown +Jede Note kann am Ende eine Sektion **„Mögliche Verbindungen“** enthalten. Diese ist optional, wird chunked, erzeugt aber keine Kanten – dient nur als Inspirationsquelle. + +## Graph-Layer (optional) +Für Multi-Hop-Queries kann zusätzlich eine SQL-Tabelle `nodes/edges/aliases` gepflegt werden. Der Importer schreibt parallel in Qdrant und SQL (UPSERT). +→ Vorteil: effiziente Abfragen wie „2-Hop Pfade“, „Top-Hubs“, Community-Erkennung. + +## Nutzen +- Speicherung und Vernetzung persönlicher Wissensressourcen. +- LLM kann mit Hybrid-Retrieval (Vektor + Graph) antworten. +- Neue Inhalte können vom Agenten semantisch eingeordnet und durch vorgeschlagene Edges ergänzt werden.