mindnet/docs/01_User_Manual/NOTE_SCOPE_ZONEN.md

Note-Scope Extraktions-Zonen (v4.2.0)

Version: v4.2.0
Status: Aktiv

Übersicht

Das Mindnet-System unterstützt nun Note-Scope Extraktions-Zonen, die es ermöglichen, Links zu definieren, die der gesamten Note zugeordnet werden (nicht nur einem spezifischen Chunk).

Unterschied: Chunk-Scope vs. Note-Scope

• Chunk-Scope Links (scope: "chunk"):

  • Werden aus dem Text-Inhalt extrahiert
  • Sind lokalem Kontext zugeordnet
  • source_id = chunk_id

• Note-Scope Links (scope: "note"):

  • Werden aus speziellen Markdown-Sektionen extrahiert
  • Sind der gesamten Note zugeordnet
  • source_id = note_id
  • Haben höchste Priorität bei Duplikaten

Verwendung

Format

Erstellen Sie eine Sektion mit einem der folgenden Header:

• ## Smart Edges
• ## Relationen
• ## Global Links
• ## Note-Level Relations
• ## Globale Verbindungen

Wichtig: Die Header müssen exakt (case-insensitive) übereinstimmen.

Beispiel

---
type: decision
title: Technologie-Entscheidung
---

# Entscheidung über Technologie-Stack

Wir haben uns für React entschieden...

## Begründung

React bietet bessere Performance...

## Smart Edges

[[rel:depends_on|Performance-Analyse]]
[[rel:uses|TypeScript]]
[[React-Dokumentation]]

## Weitere Überlegungen

Hier ist weiterer Inhalt...

Unterstützte Link-Formate

In Note-Scope Zonen werden folgende Formate unterstützt:

1. Typed Relations:

   ## Smart Edges
   [[rel:depends_on|Ziel-Notiz]]
   [[rel:uses|Andere Notiz]]
   

2. Standard Wikilinks:

   ## Smart Edges
   [[Ziel-Notiz]]
   [[Andere Notiz]]
   

   (Werden als related_to interpretiert)

3. Callouts:

   ## Smart Edges
   > [!edge] depends_on:[[Ziel-Notiz]]
   > [!edge] uses:[[Andere Notiz]]
   

Technische Details

ID-Generierung

Note-Scope Links verwenden die exakt gleiche ID-Generierung wie Symmetrie-Kanten in Phase 2:

_mk_edge_id(kind, note_id, target_id, "note", target_section=sec)

Dies stellt sicher, dass:

• ✅ Authority-Check in Phase 2 korrekt funktioniert
• ✅ Keine Duplikate entstehen
• ✅ Symmetrie-Schutz greift

Provenance

Note-Scope Links erhalten:

• provenance: "explicit:note_zone"
• confidence: 1.0 (höchste Priorität)
• scope: "note"
• source_id: note_id (nicht chunk_id)

Priorisierung

Bei Duplikaten (gleiche ID):

1. Note-Scope Links haben höchste Priorität
2. Dann Confidence-Wert
3. Dann Provenance-Priority

Beispiel:

• Chunk-Link: related_to:Note-A (aus Text)
• Note-Scope Link: related_to:Note-A (aus Zone)
• Ergebnis: Note-Scope Link wird beibehalten

Best Practices

✅ Empfohlen

1. Note-Scope für globale Verbindungen:

   ## Smart Edges
   [[rel:depends_on|Projekt-Übersicht]]
   [[rel:part_of|Größeres System]]
   

2. Chunk-Scope für lokale Referenzen:

   In diesem Abschnitt verweisen wir auf [[rel:uses|Spezifische Technologie]].
   

3. Kombination:

   # Hauptinhalt
   
   Lokale Referenz: [[rel:uses|Lokale Notiz]]
   
   ## Smart Edges
   
   Globale Verbindung: [[rel:depends_on|Globale Notiz]]
   

❌ Vermeiden

1. Nicht für lokale Kontext-Links:

   • Nutzen Sie Chunk-Scope Links für lokale Referenzen
   • Note-Scope ist für Note-weite Verbindungen gedacht

2. Nicht zu viele Note-Scope Links:

   • Beschränken Sie sich auf wirklich Note-weite Verbindungen
   • Zu viele Note-Scope Links können die Graph-Struktur verwässern

Integration mit LLM-Validierung

Note-Scope Links können auch LLM-validiert werden, wenn sie in der Sektion ### Unzugeordnete Kanten stehen:

### Unzugeordnete Kanten

related_to:Mögliche Verbindung

Wichtig: Links in ### Unzugeordnete Kanten werden als global_pool markiert und validiert. Links in ## Smart Edges werden als explicit:note_zone markiert und nicht validiert (direkt übernommen).

Beispiel: Vollständige Notiz

---
type: decision
title: Architektur-Entscheidung
---

# Architektur-Entscheidung

Wir haben uns für Microservices entschieden...

## Begründung

### Performance

Microservices bieten bessere Skalierbarkeit. Siehe auch [[rel:uses|Kubernetes]] für Orchestrierung.

### Sicherheit

Wir nutzen [[rel:enforced_by|OAuth2]] für Authentifizierung.

## Smart Edges

[[rel:depends_on|System-Architektur]]
[[rel:part_of|Gesamt-System]]
[[rel:uses|Cloud-Infrastruktur]]

## Weitere Details

Hier ist weiterer Inhalt...

Ergebnis:

• uses:Kubernetes → Chunk-Scope (aus Text)
• enforced_by:OAuth2 → Chunk-Scope (aus Text)
• depends_on:System-Architektur → Note-Scope (aus Zone)
• part_of:Gesamt-System → Note-Scope (aus Zone)
• uses:Cloud-Infrastruktur → Note-Scope (aus Zone)

Code-Referenzen

• Extraktion: app/core/graph/graph_derive_edges.py → extract_note_scope_zones()
• Integration: app/core/graph/graph_derive_edges.py → build_edges_for_note()
• Header-Liste: NOTE_SCOPE_ZONE_HEADERS in graph_derive_edges.py

FAQ

Q: Können Note-Scope Links auch Section-Links sein?
A: Ja, [[rel:kind|Target#Section]] wird unterstützt. target_section fließt in die ID ein.

Q: Was passiert, wenn ein Link sowohl in Chunk als auch in Note-Scope Zone steht?
A: Der Note-Scope Link hat Vorrang und wird beibehalten.

Q: Werden Note-Scope Links validiert?
A: Nein, sie werden direkt übernommen (wie explizite Links). Für Validierung nutzen Sie ### Unzugeordnete Kanten.

Q: Kann ich eigene Header-Namen verwenden?
A: Aktuell nur die vordefinierten Header. Erweiterung möglich durch Anpassung von NOTE_SCOPE_ZONE_HEADERS.

Zusammenfassung

• ✅ Note-Scope Zonen: ## Smart Edges oder ähnliche Header
• ✅ Format: [[rel:kind|target]] oder [[target]]
• ✅ Scope: scope: "note", source_id: note_id
• ✅ Priorität: Höchste Priorität bei Duplikaten
• ✅ ID-Konsistenz: Exakt wie Symmetrie-Kanten (Phase 2)