mindnet/docs/knowledge_design.md

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

---