Lars/mindnet
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 21 Wiki Activity

docs/knowledge_design.md aktualisiert
Some checks failed
Deploy mindnet to llm-node / deploy (push) Failing after 2s
Details

Browse Source
This commit is contained in:
Lars 2025-09-09 11:56:54 +02:00
parent 6a293e842e
commit 93739935b7
1 changed files with 72 additions and 433 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

505
docs/knowledge_design.md
View File

@ -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-<type>-<slug>.md`
Beispiel: `20250902-1710-thought-obsidian-struktur.md`
- **Zeitunabhängige Wissensknoten (Konzepte, Personen, Projekte, Leitbild):**
`<type>-<slug>.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/<name>`.
- **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.