diff --git a/docs/knowledge_design.md b/docs/knowledge_design.md index 47dffa1..d0b58d6 100644 --- a/docs/knowledge_design.md +++ b/docs/knowledge_design.md @@ -1,504 +1,249 @@ ---- -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 +**Version:** 1.4.0 (aktualisiert 2025-10-06) -# mindnet – Knowledge Design +## 1. Gesamtziel und Systemverständnis -## 1. Gesamtziel, Anspruch & Nutzen +**mindnet** ist ein lokales Wissensnetzwerk, das alle meine Notizen, Projekte, Gedanken, Erfahrungen und Pläne als Markdown-Dateien speichert, automatisch importiert, semantisch in **Chunks** zerlegt und als **Graph-Struktur in Qdrant** ablegt. +Es ist die Grundlage für ein agentenfähiges, lokal betriebenes LLM-System, das meine Daten verknüpft, abfragt und erweitert. -**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. +**Zentrale Ziele** +- Vollständige Repräsentation persönlichen Wissens in strukturierter, maschinenlesbarer Form +- Reproduzierbare Verarbeitung: Import → Chunking → Embedding → Edges → Graph +- Verlustfreie Roundtrip-Fähigkeit (Import ⇄ Export) +- Erweiterbarkeit für Agenten, RAG-Retriever und semantische Suche -**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 +**Prinzipien** +- **Deterministisch:** IDs, Hashes und Edges wiederholbar +- **Portabel:** Markdown + YAML +- **Robust:** fehlertoleranter Parser +- **Idempotent:** keine Duplikate bei Re-Import +- **Erweiterbar:** neue Typen und Edge-Arten ohne Migration --- ## 2. YAML-Frontmatter-Schema -> **Pflichtfelder:** `title`, `id`, `type`, `status`, `created`, `tags` -> **Empfohlen:** `updated`, `area`, `project`, `priority`, `aliases`, `lang`, `people`, `depends_on`, `source` u. a. +| Feld | Typ | Beschreibung | +|-------|-----|--------------| +| `title` | string | Menschlich lesbarer Titel | +| `id` | string | Eindeutige Note-ID (Slug) | +| `type` | enum | `concept`, `thought`, `experience`, `task`, `project`, `journal`, `person`, `meeting`, `milestone` | +| `status` | enum | `draft`, `active`, `done`, `archived` | +| `created` | date | ISO-Datum | +| `updated` | date | Letzte Änderung | +| `area` | string | Themen- oder Lebensbereich | +| `project` | string | Zugehöriges Projekt | +| `tags` | list | Strukturierte Tags (`area/…`, `topic/…`) | +| `depends_on` | list | IDs anderer Notizen | +| `assigned_to` | list | Beteiligte Personen | +| `embedding_exclude` | bool | Falls `true`, keine Embeddings | +| `hash_mode` | enum | Hash-Modus beim Import (`body`, `frontmatter`, `full`) | +| `priority` | enum/int | 1–5 oder `low` / `med` / `high` | +| `effort_min`, `due` | int/date | Aufwand / Termin | +| `aliases` | list | Alternative IDs | +| `lang` | string | ISO-Sprachcode | +| `source` | string | Herkunft / Referenzquelle | -### 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 +**Pflichtfelder:** `title`, `id`, `type`, `status`, `created` +**Optionale Felder:** alle übrigen --- -## 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/`, … +## 3. Dateinamen und Ordner + +- Format: `YYYY-MM-DD_title.md` oder `slug.md` +- Strukturierte Ordner: + - `10_thoughts/`, `20_concepts/`, `30_projects/`, `40_experiences/`, … +- Alle Pfade relativ; Unterstriche statt Leerzeichen --- -## 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`). +## 4. Link- und Edge-Design + +**Verlinkungen** +- Wikilinks: `[[note-id]]` oder `[[Titel|note-id]]` +- Automatische Edges aus Text und Frontmatter + +**Edge-Typen in Qdrant** + +| Typ | Bedeutung | Quelle | Scope | +|------|------------|--------|--------| +| `belongs_to` | Chunk → Note | intern | chunk | +| `prev` / `next` | Reihenfolge | intern | chunk | +| `references` | explizite Wikilinks | Text | chunk | +| `backlink` | Gegenkante zu `references` | abgeleitet | note | +| `depends_on` | YAML-Abhängigkeiten | YAML | note | +| `assigned_to` | YAML-Zuweisung | YAML | note | +| `unresolved` | Ziel fehlt (Stub) | abgeleitet | chunk | + +**Edge-Schlüssel** +- `source_id`, `target_id`, `kind`, `scope`, `note_id` +- Dedup-Schlüssel: Kombination aus `(kind, source_id, target_id, scope)` --- -## 5. Backlink- & Link-Regeln +## 5. Chunking-Modell -- **Wikilinks**: `[[stabile-id]]` oder `[[Titel|stabile-id]]` -- Im **Fließtext** verlinken (Forwardlinks); am **Ende** optional **„Mögliche Verbindungen“** redaktionell pflegen: +**Chunk-Datenstruktur** +| Feld | Beschreibung | +|-------|---------------| +| `note_id` | Zugehörige Note | +| `chunk_index` | Laufende Nummer | +| `text` | Originalabschnitt | +| `window` | Text + Overlap links/rechts | +| `overlap_left` | Länge des linken Overlaps | +| `overlap_right` | Länge des rechten Overlaps | +| `embedding` | 384-dimensionaler Vektor | +| `tokens` | Tokenanzahl (optional) | - ## 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). +**Chunking-Regeln (aus `chunking_strategy.md`)** +- Trennung nach Absätzen, Überschriften, Listen, Tabellen +- Token-Zielgröße 350–500 (max 600) +- Overlap: 30–40 % für semantische Kohärenz +- Overlap wird in `window` integriert, sodass `text ≠ window` --- -## 5.1 Edge-Typen & Semantik (Graph) +## 6. Hash-Strategie und Änderungsverfolgung -Beziehungen werden als **Edges** mit neuem Payload-Schema gespeichert: +**Zweck:** Nur bei realer Inhaltsänderung re-indexieren - 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" +| Umgebungsvariable | Beschreibung | +|--------------------|--------------| +| `MINDNET_HASH_COMPARE` | Vergleichsquelle (`Body`, `Full`, `Frontmatter`) | +| `MINDNET_HASH_SOURCE` | Rohtext vs. geparst (`raw` / `parsed`) | +| `MINDNET_HASH_NORMALIZE` | Normalisierung (`canonical` / `none`) | -**Kantenarten** -- **belongs_to** — *Chunk → Note* - Jeder Chunk gehört zu **genau einer** Note. *Scope:* `chunk`. +**Basismodi** +- `body` → Nur Textkörper +- `frontmatter` → Nur Metadaten +- `full` → Kombination +- Hash = SHA-256(canonicalized_input) -- **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) +Bei Änderung: Re-Import, neue Embeddings, Edges werden aktualisiert. --- -## 6. Abschnitts-Konventionen im Body +## 7. Qdrant-Speicherstruktur -Einheitliche Überschriften erleichtern Parser, Chunking und Abfragen. Typ-spezifische Empfehlungen: +| Collection | Inhalt | Primärfelder | Embedding | +|-------------|---------|---------------|------------| +| `mindnet_notes` | Notes mit Fulltext & Hash | `note_id` | optional | +| `mindnet_chunks` | Chunks mit Text, Window, Embedding | `chunk_id`, `note_id` | 384 d | +| `mindnet_edges` | Graphkanten | `edge_id`, `source_id`, `target_id` | — | -- **Gedanke (`thought`)** - `## Zusammenfassung` · `## Begründung / Details` · `## Belege / Quellen` · `## Nächste Schritte` · `## Mögliche Verbindungen` +**Upsert-Strategie** +- Idempotente UUIDv5-IDs +- Keine Duplikate durch deterministische Signaturen +- `purge-before-upsert` zur Bereinigung -- **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` +**Indizes** +- notes: `note_id`, `hash_signature` +- chunks: `note_id`, `chunk_index` +- edges: `(kind, source_id, target_id, scope)` --- -## 7. Abbildung persönlicher Inhalte auf Typen +## 8. Fehler-Toleranz und Parser-Robustheit -**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. +- UTF-8 mit Fallback: ersetzt ungültige Bytes (`errors="replace"`) +- Ignoriert Nullbytes, BOM, exotische Zeilenenden +- Erkennt defekte oder leere YAML-Header und überspringt sie +- Logt Problemfälle (`read_markdown failed`, `make_note_payload returned non-dict`) +- Bei Fehlern: Import → warn → continue --- -## 8. Beispiel-Notizen +## 9. Tests & Validierung -### 8.1 Gedanke (`thought`) – Beispiel +**Integrationstests** +- Roundtrip: Import → Export → Compare (`compare_vaults.py`) +- Chunk-Integrität: `verify_chunks_integrity.py` +- Hash-Audit: `hash_reporter.py` +- Window-Vergleich: `check_chunks_window_vs_text.py` -**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]] +**Erwartete Ergebnisse** +- Alle Notes werden erkannt +- `window ≠ text` bei > 60 % der Chunks +- Roundtrip-Vergleich liefert „OK“ +- Edge-Anzahl entspricht Modell (belongs_to = #Chunks, next/prev ≈ #Chunks – 1) --- -## 9. Schrittweise Migration bestehender freier Notizen +## 10. Export & Roundtrip-Verhalten -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. +- `export_markdown.py` erzeugt identische Markdown-Dateien +- Schreibt YAML + Body in korrekter Reihenfolge +- Roundtrip-Prüfung (`compare_vaults.py`) validiert: + - vollständigen Body + - unveränderte Hash-Signatur + - gleiche Chunkzahl --- -## 10. Dataview-Beispiele (direkt nutzbar) +## 11. Graph-Schicht und WP-04-Integration -**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“)* +- Qdrant fungiert als Graph-Backend +- `graph/service.py` (WP-04): stellt API für Mehrhop-Abfragen bereit +- Unterstützt: + - `expand(note_id, hops=2)` + - `resolve_unresolved()` + - `neighbors(kind=…)` +- Grundlage für spätere **Retriever-Funktionen** (LLM / Agenten) --- -## 11. Validierung & Pflege +## 12. Agenten- und LLM-Integration -- **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. +**Retriever-Pipeline** +1. Suche top-k Chunks (cosine distance) +2. Erweiterung um Edges (`references`, `backlinks`) +3. Kontext-Assembling via `window`-Text +4. Prompt-Generierung + +**Agent-Use-Cases** +- Automatisches Tagging (`type`, `status`) +- Vorschläge für neue Edges +- Auflösen von `unresolved`-Referenzen +- Auto-Import externer Quellen (MediaWiki, PDFs, Webseiten) --- -## 12. Qdrant-Ablage & Indizes +## 13. Erweiterbarkeit -**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). +- Neue Edge-Typen: `inspired_by`, `relates_to`, `contradicts` +- Neue Note-Typen: `decision`, `resource`, `recommendation` +- Embedding-Engines austauschbar (MiniLM → LaBSE → E5) +- Versionierte Chunking-Strategien (`chunk_config.py`) --- -## 13. LLM/RAG & Agenten – Arbeitsweise (Überblick) +## 14. Qualitätssicherung und Best Practices -**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. +- Validierung vor Upsert +- Keine Leer-Chunks +- Vollständige Metadaten in Notes +- Tests in `tests/` automatisch ausführbar (`run_e2e_roundtrip.sh`) +- Ergebnis: „Roundtrip OK“ und `verify_chunks_integrity` = OK --- -## 14. Versions- & Änderungsrichtlinien +## 15. Änderungsverlauf -- **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): …` +**v1.4.0 (2025-10-06)** +- Neu: `window` vs `text` Feld in `mindnet_chunks` +- Neu: Hash-Modi (`body`, `frontmatter`, `full`) mit Env-Steuerung +- Neu: Baseline-Modus für Vergleich +- Parser → fehlertolerant (UTF-8 replace) +- Roundtrip-Test vollständig integriert +- Graph-Service und Mehrhop-Abfragen (WP-04-Vorbereitung) +- `purge-before-upsert` und `--note-scope-refs` Parameter ergänzt + +**v1.3.0 (2025-09-09)** +- Hash-Normalisierung und Edge-Scope +- Roundtrip-Tests, Agenten-Integration + +**v1.2.0 (2025-09-02)** +- Grundstruktur des Knowledge-Designs --- - -## 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.