diff --git a/docs/knowledge_design.md b/docs/knowledge_design.md index b6dbc88..40af515 100644 --- a/docs/knowledge_design.md +++ b/docs/knowledge_design.md @@ -1,69 +1,67 @@ -# knowledge_design.md +# mindnet – Knowledge Design -## 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. +## 1. Gesamtziel, Anspruch & Nutzen +Ziel ist eine persönliche Wissensbasis, die langfristig tragfähig ist (eigene Gedanken, Erfahrungen, Pläne, Erlebnisse) und ist zugleich so strukturiert, dass Tools (Obsidian, Dataview, Parser, Vektorsuche/Qdrant, Agenten) es **maschinenlesbar** nutzen können. -## YAML-Frontmatter-Schema -**Pflichtfelder** -- `id`: eindeutige Note-ID -- `title`: kurzer Titel -- `type`: z. B. `concept`, `plan`, `journal` -- `created`: ISO-Datum -- `updated`: ISO-Datum +**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 -**Optionale Felder** -- `status`, `area`, `project`, `tags`, `lang`, `slug`, `aliases`, `priority`, `effort_min`, `due`, `people`, `depends_on`, `assigned_to` +**Späterer Nutzen / Einsatzzwecke:** +- **Schnelles Wiederfinden**: Dataview-Abfragen, Filter, Dashboards +- **LLM-gestütztes Arbeiten**: Frage-Antwort mit Kontext-Zitaten aus den Chunks +- **Agenten**: Vorschläge für neue Verbindungen/Strukturierung; Auflösen von „unresolved links“ +- **Projektnavigation**: Aufgabenbeziehungen, Abhängigkeiten (leichtes PM) +- **Lebenslaufende Struktur**: 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 -## 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. +## 2. YAML-Frontmatter-Schema -## 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. +> **Pflichtfelder:** `title`, `id`, `type`, `status`, `created`, `tags` +> **Empfohlen:** `updated`, `area`, `project`, `priority`, `aliases` (u. a.) -## 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. +### 2.1 Feldübersicht +| Feld | Typ | Bedeutung | +|--------------------|-------------------------------|---------------------------------------------------------------------------| +| `title` | string | Menschlich lesbarer Titel | +| `id` | string (slug/identifier) | **Stabile** ID; referenzierbar über Wikilinks | +| `type` | enum | Notiz-Typ (`concept`, `thought`, `experience`, `task`, `project`, `journal`, …) | +| `status` | enum | `draft` \| `active` \| `done` \| `archived` | +| `created` | date | Erstellungsdatum (ISO) | +| `updated` | date | Letzte Änderung (ISO) | +| `area` | string | Themen-/Lebensbereich | +| `project` | string | Projekt-/Arbeitskontext | +| `tags` | list | Taxonomische Tags (präfixiert, s. Abschnitt 4) | +| `aliases` | list | Alternative IDs/Titel (Slug-Resolver) | +| `lang` | string | Sprache, optional | +| `priority` | enum/int | Priorität, optional | +| `due`, `effort_min`| date/int | Für Aufgaben/Projekte | +| `people` | list | Beteiligte Personen/IDs | +| `depends_on` | list | Abhängigkeiten auf andere IDs | +| `source` | string | Quelle (Artikel, Buch, Video, …) | -**Optional:** `references:note` (Note-Scope-References), standardmäßig deaktiviert; aktivierbar via ENV/Flag. +### 2.2 Konventionen +- `id` ist **menschenlesbar** (Slug), eindeutig im Vault; `aliases` dienen als Fallback für Resolver. +- Datumsformat ISO `YYYY-MM-DD`. +- Keine duplizierten Tags; Präfixe nutzen (`area/…`, `type/…`, `topic/…`). -## 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. +### 2.3 Minimalbeispiel Frontmatter +```yaml +title: "Gedanke: YAML-Standards" +id: thought-yaml-standards +type: thought +status: draft +created: 2025-09-02 +updated: 2025-09-02 +area: mindnet +project: project-mindnet +tags: [area/mindnet, type/thought, topic/yaml] +aliases: [yaml-gedanken]