--- title: "mindnet – Knowledge Design" id: "design-knowledge-architecture" type: "guide" status: "active" version: "1.3.0" created: 2025-09-02 updated: 2025-09-09 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 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.