mindnet/docs/01_User_Manual/NOTE_SCOPE_ZONEN.md

Note-Scope Extraktions-Zonen (v4.5.8)

Version: v4.5.8
Status: Aktiv
Aktualisiert: WP-24c Phase 3 Agentic Edge Validation

Ü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 Phase 3 Validierung (WP-24c v4.5.8)

Note-Scope Links können zwei verschiedene Provenance haben:

Explizite Note-Scope Links (Keine Validierung)

Links in ## Smart Edges Zonen werden als explicit:note_zone markiert und direkt übernommen (keine Phase 3 Validierung):

## Smart Edges

[[rel:depends_on|System-Architektur]]
[[rel:part_of|Gesamt-System]]

Vorteil: Sofortige Übernahme, höchste Priorität, keine Validierungs-Kosten.

Validierte Note-Scope Links (Phase 3 Validierung)

Links in ### Unzugeordnete Kanten erhalten candidate: Präfix und werden in Phase 3 validiert:

### Unzugeordnete Kanten

related_to:Mögliche Verbindung
depends_on:Unsicherer Link

Validierungsprozess:

1. Links erhalten candidate: Präfix
2. Phase 3 Validierung: LLM prüft semantisch gegen Note-Summary oder Note-Text (Note-Scope Kontext-Optimierung)
3. Erfolg (VERIFIED): candidate: Präfix wird entfernt, Kante wird persistiert
4. Ablehnung (REJECTED): Kante wird nicht in die Datenbank geschrieben

Wichtig:

• Links in ### Unzugeordnete Kanten werden als candidate: markiert und durchlaufen Phase 3
• Links in ## Smart Edges werden als explicit:note_zone markiert und nicht validiert (direkt übernommen)
• Note-Scope Kontext-Optimierung: Bei Note-Scope Kanten nutzt Phase 3 note_summary (Top 5 Chunks) oder note_text (aggregierter Gesamttext) für bessere Validierungs-Genauigkeit

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: Das hängt von der Zone ab:

• ## Smart Edges: Nein, werden direkt übernommen (explizite Links, keine Validierung)
• ### Unzugeordnete Kanten: Ja, durchlaufen Phase 3 Validierung (candidate: Präfix)

Q: Was ist der Unterschied zwischen Note-Scope in Smart Edges vs. Unzugeordnete Kanten?
A:

• Smart Edges: Explizite Links, sofortige Übernahme, höchste Priorität
• Unzugeordnete Kanten: Validierte Links, Phase 3 Prüfung, candidate: Präfix

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)