mindnet/docs/knowledge_design.md

# knowledge_design.md

## 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.  

## YAML-Frontmatter-Schema
**Pflichtfelder**
- `id`: eindeutige Note-ID  
- `title`: kurzer Titel  
- `type`: z. B. `concept`, `plan`, `journal`  
- `created`: ISO-Datum  
- `updated`: ISO-Datum  

**Optionale Felder**
- `status`, `area`, `project`, `tags`, `lang`, `slug`, `aliases`, `priority`, `effort_min`, `due`, `people`, `depends_on`, `assigned_to`  

## 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.  

## 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.  

## 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.  

**Optional:** `references:note` (Note-Scope-References), standardmäßig deaktiviert; aktivierbar via ENV/Flag.  

## 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.