Lars
0a891cfd95
All checks were successful
Deploy mindnet to llm-node / deploy (push) Successful in 3s
250 lines
8.2 KiB
Markdown
250 lines
8.2 KiB
Markdown
# mindnet – Knowledge Design
|
||
**Version:** 1.4.0 (aktualisiert 2025-10-06)
|
||
|
||
## 1. Gesamtziel und Systemverständnis
|
||
|
||
**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.
|
||
|
||
**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
|
||
|
||
**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
|
||
|
||
| 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 |
|
||
|
||
**Pflichtfelder:** `title`, `id`, `type`, `status`, `created`
|
||
**Optionale Felder:** alle übrigen
|
||
|
||
---
|
||
|
||
## 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. 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. Chunking-Modell
|
||
|
||
**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) |
|
||
|
||
**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`
|
||
|
||
---
|
||
|
||
## 6. Hash-Strategie und Änderungsverfolgung
|
||
|
||
**Zweck:** Nur bei realer Inhaltsänderung re-indexieren
|
||
|
||
| Umgebungsvariable | Beschreibung |
|
||
|--------------------|--------------|
|
||
| `MINDNET_HASH_COMPARE` | Vergleichsquelle (`Body`, `Full`, `Frontmatter`) |
|
||
| `MINDNET_HASH_SOURCE` | Rohtext vs. geparst (`raw` / `parsed`) |
|
||
| `MINDNET_HASH_NORMALIZE` | Normalisierung (`canonical` / `none`) |
|
||
|
||
**Basismodi**
|
||
- `body` → Nur Textkörper
|
||
- `frontmatter` → Nur Metadaten
|
||
- `full` → Kombination
|
||
- Hash = SHA-256(canonicalized_input)
|
||
|
||
Bei Änderung: Re-Import, neue Embeddings, Edges werden aktualisiert.
|
||
|
||
---
|
||
|
||
## 7. Qdrant-Speicherstruktur
|
||
|
||
| 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` | — |
|
||
|
||
**Upsert-Strategie**
|
||
- Idempotente UUIDv5-IDs
|
||
- Keine Duplikate durch deterministische Signaturen
|
||
- `purge-before-upsert` zur Bereinigung
|
||
|
||
**Indizes**
|
||
- notes: `note_id`, `hash_signature`
|
||
- chunks: `note_id`, `chunk_index`
|
||
- edges: `(kind, source_id, target_id, scope)`
|
||
|
||
---
|
||
|
||
## 8. Fehler-Toleranz und Parser-Robustheit
|
||
|
||
- 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
|
||
|
||
---
|
||
|
||
## 9. Tests & Validierung
|
||
|
||
**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`
|
||
|
||
**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)
|
||
|
||
---
|
||
|
||
## 10. Export & Roundtrip-Verhalten
|
||
|
||
- `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
|
||
|
||
---
|
||
|
||
## 11. Graph-Schicht und WP-04-Integration
|
||
|
||
- 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)
|
||
|
||
---
|
||
|
||
## 12. Agenten- und LLM-Integration
|
||
|
||
**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)
|
||
|
||
---
|
||
|
||
## 13. Erweiterbarkeit
|
||
|
||
- 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`)
|
||
|
||
---
|
||
|
||
## 14. Qualitätssicherung und Best Practices
|
||
|
||
- 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
|
||
|
||
---
|
||
|
||
## 15. Änderungsverlauf
|
||
|
||
**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
|
||
|
||
---
|