mindnet/docs/chunking_strategy.md

# Chunking-Strategie für mindnet

## Ziel
Die Chunking-Strategie sorgt dafür, dass Inhalte aus Markdown-Dateien verlustfrei, sinnvoll segmentiert und mit stabilen IDs in Qdrant abgelegt werden. Jeder Chunk soll semantisch sinnvoll abgegrenzt sein und eine optimale Balance aus Kontexttiefe und Abrufbarkeit für LLM-Abfragen bieten.

## Grundprinzipien
- **Chunkgrößen**: Zielbereich 250–400 Tokens; Overlap 40–60 Tokens.  
- **Semantische Schnitte**: Chunks enden an Absätzen, Überschriften, Listenpunkten, Codeblöcken oder Zitaten.  
- **Frontmatter**: YAML-Frontmatter wird **nicht** eingebettet, sondern vollständig im Note-Payload gespeichert.  
- **Verlustfreiheit**: Originaltext bleibt durch `note.payload.fulltext` erhalten; Chunks enthalten zusätzlich `chunk.payload.text`.  

## Typ-Spezifische Regeln
- **Notes (Konzepttexte, Pläne, Tagebücher)**: Chunk an Überschriften + Absätzen.  
- **Checklisten / Listen**: jeder Abschnitt wird zu eigenem Chunk.  
- **Codeblöcke**: immer geschlossen innerhalb eines Chunks.  
- **Zitate**: als eigener Chunk, wenn mehr als 2 Zeilen.  

## Overlaps
- Overlap von 40–60 Tokens verhindert semantische Brüche zwischen Chunks.  
- Overlap gilt **nur für den Body**, nicht für die YAML-Frontmatter.  

## Edge-Modell (Graph)
- **Chunk → Note**: `belongs_to(note_id)` (immer; Owner-Note im Payload)  
- **Chunk → Chunk**: `prev`, `next` (symmetrisch, für lineare Navigation)  
- **Chunk → Note**: `references(target_id)` aus `[[Wikilinks]]` oder Links im Text  
- **Note → Note**: `backlink(target_id)` automatisch generiert, dedupliziert  
- **Optional**: `references:note` (nur wenn per Flag/ENV aktiviert, Default = aus)  
- **Unresolved**: Kanten mit `status=unresolved`, wenn Ziel noch nicht existiert  

## Payload-Erweiterungen
- Jeder Chunk speichert:
  - `text` (Originalchunk)  
  - `note_id` (Owner)  
  - Metadaten (`chunk_index`, `section_title`, `neighbors.prev/next`)  
- Jede Note speichert:
  - `fulltext` (verlustfreier Body)  
  - `path` (relativ zum Vault)  
  - `references` (Liste von Slugs, als Fallback für Kantenbildung)  

## Performance
- Qdrant-Payload-Indizes für `note_id`, `kind`, `scope`, `source_id`, `target_id`.  
- Materialisierte Nachbarschaften optional in `note.payload.neighbors` für direkte 1-Hop-Abfragen.  

## Beispiel (Chunk-Payload)
```yaml
id: concept-alpha#1
note_id: concept-alpha
note_title: "Concept Alpha"
chunk_index: 1
section_title: "Einleitung"
text: "Dies ist der Text des Chunks …"
wikilinks: ["concept-beta"]
references:
  - kind: wikilink
    target_id: concept-beta
neighbors:
  prev: null
  next: concept-alpha#2
path: area/concepts/concept-alpha.md