mindnet/docs/knowledge_design.md

---
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<string>                  | Taxonomische Tags (präfixiert, s. Abschnitt 4)                            |
| `aliases`          | list<string>                  | 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<string>                  | Beteiligte Personen/IDs                                                   |
| `depends_on`       | list<string>                  | 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.