loletranga/Personal-Knowledge-Graph

Persönliches Wissensnetz × Knowledge Graph (dateibasiert, iterativ)

Verwandle eine Sammlung von Markdown-Dokumenten in ein „erinnerbares, nachvollziehbares" Wissensnetz: Jedes Dokument erhält eine Frontmatter-Metadatenebene, wird über drei Beziehungstypen mit anderen verknüpft, und ein Skript generiert die Destillationsschicht (Entscheidungsregister + Graph-Adjacenzliste). So kann der Agent vor Analysen und Entscheidungen auf frühere Gedankengänge und historische Zusammenhänge zurückgreifen.

Kernprinzipien (zuerst verstehen, dann handeln)

1. Das Dokument selbst ist die einzige Quelle der Wahrheit. Der Graph ist kein separates System; Frontmatter und doppelte Klammern [[...]] leben in den .md-Dateien des Benutzers. Das graph/-Verzeichnis ist reines Derivat – es kann gelöscht und jederzeit neu erzeugt werden. Änderungen erfolgen ausschließlich an den Quelldokumenten.
2. Schreiben erfordert Bestätigung. Der Agent entwirft das Frontmatter, muss dem Benutzer aber vor dem bulk-Schreiben eine Stichprobe zeigen und die Bestätigung einholen. Urteilsbeziehungen wie supersedes (wer hat wen widerlegt) müssen als Liste zur Bestätigung vorgelegt werden – keine stillen Schreibvorgänge.
3. Lieber herabstufen als erfinden. Wenn aus einem Dokument keine Schlussfolgerung ablesbar ist, setze status: reference und erfinde keine conclusion. Eine falsche „einzeilige Schlussfolgerung" kann den Benutzer bei Entscheidungen in die Irre führen – das ist schlimmer als eine fehlende.

Dieses Skill-Verzeichnis enthält zwei Begleitdateien (im selben Verzeichnis wie diese SKILL.md):

• scripts/gen_kb_graph.py – Das Skript zur Graph-Generierung (reine Standardbibliothek, offline nutzbar)
• references/schema.md – Vollständige Frontmatter-Spezifikation, Semantik der drei Kantentypen, Ausgabetemplate, Format der Erinnerungsausgabe. Lies dies zuerst, wenn du das erste Mal eine Wissensdatenbank aufbaust oder dir bei Feldern unsicher bist.

---

Ablauf

Schritt 0: Umfang festlegen und dem Benutzer erklären, was passieren wird

• Der Benutzer übergibt ein Verzeichnis → Dieses Verzeichnis wird das Wurzelverzeichnis der Wissensdatenbank.
• Der Benutzer übergibt eine oder mehrere Dateien → Frage: Soll das übergeordnete Verzeichnis dieser Dateien als Wurzelverzeichnis dienen (empfohlen, damit historische Dokumente sich gegenseitig verknüpfen können) oder soll ein neues, unabhängiges Wissensdatenbank-Verzeichnis für sie erstellt werden?
• Der Benutzer hat keine Dateien und möchte eine neue Datenbank anlegen → Gehe zu Schritt 2 „Leeres Grundgerüst".
• Bestätige vor dem Start in zwei bis drei Sätzen: Welches Verzeichnis die Wurzel ist, welche Dateien geändert werden (Frontmatter der Quelldokumente + neues graph/-Verzeichnis) und dass der Textkörper der Dokumente nicht angetastet wird.

Schritt 1: Status der Wissensdatenbank ermitteln

Lese das Wurzelverzeichnis:

• Wenn <Wurzel>/gen_kb_graph.py oder <Wurzel>/graph/INDEX.md existiert → Iterationsmodus (bestehende DB)
• Sonst → Aufbaumodus (neue DB)

Schritt 2 A: Aufbaumodus (inkl. leeres Grundgerüst)

1. Leeres Grundgerüst (wenn der Benutzer keine historischen Dateien hat): Erstelle die folgenden Dateien und springe dann zu Schritt 3, um es dem Benutzer mitzuteilen –
   • <Wurzel>/Wissensdatenbank-Spezifikation-Kurznavigation.md: Extrahiere aus references/schema.md die Frontmatter-Vorlage und die drei Kernregeln, damit der Benutzer sie beim täglichen Schreiben als Referenz nutzen kann (erhält status: reference)
   • <Wurzel>/Vorlage-Analysedokument.md: Eine leere Vorlage mit vollständigem Frontmatter (erhält ebenfalls status: reference)
2. Skript installieren: Kopiere scripts/gen_kb_graph.py aus dem Skill-Verzeichnis als <Wurzel>/gen_kb_graph.py (überspringe, wenn bereits vorhanden). Dies macht die Wissensdatenbank in sich geschlossen – der Benutzer oder andere Agents können den Graphen auch ohne dieses Skill neu erstellen.
3. Probelauf: python3 <Wurzel>/gen_kb_graph.py <Wurzel>. Lies die Übersicht in <Wurzel>/graph/report.md und berichte dem Benutzer die Größe (wie viele Dokumente, wie vielen fehlt das Frontmatter).
4. Metadaten entwerfen (Kernarbeit): Lies zuerst references/schema.md, dann verarbeite batchweise nach Unterverzeichnis oder Domäne:
   • Lies jedes Dokument, entwirf das Frontmatter: date (Datum der Schlussfolgerung), domain, status (active/superseded/reference), conclusion (einzeilige Schlussfolgerung – schreibe nur, „wofür sich dieses Dokument letztlich ausspricht", keine Inhaltszusammenfassung)
   • Zeige zuerst eine Stichprobe: Wähle 2-3 repräsentative Dokumente (ein Entscheidungsdokument, eine Informationsquelle) und zeige das Frontmatter, das du schreiben wirst; bestätige die Vorgehensweise mit dem Benutzer, bevor du im Bulk schreibst
   • Erkenne Ablösebeziehungen: Dateinamen mit v2/Neu/Kopie/Überarbeitung oder inhaltlich aufeinanderfolgende Dokumente, die sich gegenseitig widerlegen; schlage supersedes-Verweise vor und lege sie dem Benutzer als Liste zur Bestätigung vor, bevor du sie schreibst
   • Berichte nach jedem Batch den Fortschritt; verändere kein Wort im Textkörper, füge nur Frontmatter hinzu
5. Neu erstellen und übergeben: Führe das Skript erneut aus (erzeugt automatisch die interaktive HTML-Visualisierung in graph/kb-graph.html), zeige dem Benutzer die ersten Zeilen von INDEX.md und die verbleibenden Lücken in report.md, und informiere ihn, dass er kb-graph.html im Browser öffnen kann, um den interaktiven Graphen zu sehen.

Schritt 2 B: Iterationsmodus (bestehende DB)

1. Führe das vorhandene <Wurzel>/gen_kb_graph.py aus (falls nicht vorhanden, kopiere es erneut aus dem Skill-Verzeichnis)
2. Lese graph/report.md und verarbeite nur das Inkrement: Neue Dokumente ohne Frontmatter, Dokumente ohne Datum oder Schlussfolgerung, unterbrochene Verknüpfungen. Entwurf → Bestätigung → Zurückschreiben
3. Semantische Kanten ergänzen: Lies die neuen Dokumente und schlage ihnen Verknüpfungen zu bestehenden Dokumenten vor – related („zwei Seiten derselben Sache") und supersedes („dieses Dokument korrigiert jenes") – mit einer Begründung pro Beziehung; nach Bestätigung zurückschreiben
4. Neu erstellen (inkl. Aktualisierung der HTML-Visualisierung kb-graph.html), berichte dem Benutzer die Änderungen (Anzahl neuer Knoten/Kanten, verbleibende Lücken)

Schritt 3: Dem Benutzer mitteilen, wie er es nutzen kann

Informiere den Benutzer am Ende jedes Aufbaus/Iteration über die zukünftige Nutzung (Du kannst die folgende Vorlage als Orientierung nehmen):

Sage mir in Zukunft einfach: „Erinnere mich an meine Gedanken und Schlussfolgerungen zu Thema XX", bevor du eine Analyse oder Entscheidung triffst. Ich durchsuche dann den Graphen, prüfe die zeitliche Abfolge der Entwicklungen und lege dir einen Referenzbericht vor. Wenn du den Graphen visuell erkunden möchtest, öffne graph/kb-graph.html in deinem Browser (durchsuchbar, filterbar, Knoten anklickbar für Details). Schreib einfach weiter wie gewohnt deine Dokumente; wenn du fertig bist, sag „Aktualisiere die Wissensdatenbank", und ich füge automatisch die Metadaten hinzu und verknüpfe die neuen Dokumente.

---

Erinnerungsmodus (vor einer Entscheidung abrufen)

Wenn der Benutzer dich bittet, sich an frühere Gedankengänge zu erinnern, und das Zielverzeichnis bereits graph/-Derivate enthält, führe diesen rein lesenden Ablauf aus:

1. Lese graph/INDEX.md und gleiche die thematischen Schlüsselwörter mit den Dokumenttiteln und Schlussfolgerungen ab; filtere die relevanten Elemente heraus (lieber zu viele als zu wenige)
2. Lese bei Bedarf graph/GRAPH.md: Folge den supersedes-Entwicklungsketten und related-Nachbarn der vorselektierten Dokumente, um den Kontext zu vervollständigen
3. Lese die Frontmatter- und Schlussfolgerungsabschnitte der relevanten Dokumente im Detail (nicht unbedingt den gesamten Text)
4. Gib das Ergebnis in einem festgelegten Format aus (vollständiges Beispiel siehe references/schema.md):
   • Liste relevanter Gedankengänge: Jeder Eintrag = Datum | Einzeilige Schlussfolgerung | Status | Dokumentenlink
   • Entwicklungskette: Die Veränderung der Gedankengänge zu diesem Thema, mit Angabe, wann was widerlegt oder korrigiert wurde
   • Referenzpunkte für die aktuelle Frage: Welche Schlussfolgerungen können direkt übernommen werden, welche sind veraltet und erfordern Vorsicht
   • Kein Präzedenzfall: Wenn im Graphen keine historische Entscheidung zu diesem Thema gefunden wird, sage klar: „Dies ist eine völlig neue Entscheidung, es gibt keinen Präzedenzfall" – auch das ist ein wertvolles Ergebnis

---

Bestätigungspunkte mit dem Benutzer (müssen angehalten werden)

1. Vor dem Aufbau der DB: Wurzelverzeichnis, Ignorierregeln (kann <Wurzel>/.kbignore verwenden, um Verzeichnisse auszuschließen; ein Platzhalter pro Zeile)
2. Vor dem bulk-Schreiben von Frontmatter: 2-3 Dokumente als Stichprobe bestätigen lassen
3. Vor dem Schreiben von supersedes-Beziehungen: Liste der Paare bestätigen lassen
4. Jede Änderung am Textkörper: Standardmäßig verboten, nur auf ausdrücklichen Wunsch des Benutzers zulässig

Skript-Verwendung

python3 gen_kb_graph.py <Wurzelverzeichnis> [--output graph] [--ignore "bücher,alt,*_alt"] [--no-html]

Standardmäßig ignoriert: Versteckte Verzeichnisse, .venv, venv, node_modules, pycache, .git, das Ausgabeverzeichnis selbst. Idempotent, jederzeit erneut ausführbar; erzeugt 5 Dateien (INDEX.md / GRAPH.md / kb-graph.json / report.md / kb-graph.html), Format siehe references/schema.md. kb-graph.html ist eine einzeldatei-basierte, zero-dependency Visualisierungsseite (Force-Directed-Graph + Entscheidungslistentabelle, durchsuchbar, filterbar, Knoten anklickbar für Details, Doppelklick öffnet Quelldatei). Kann bei entsprechender Umgebung direkt im Browser geöffnet und dem Benutzer gezeigt werden.

Upgrade-Grenze

Wenn die Dokumentenanzahl etwa 500 überschreitet, GRAPH.md nicht mehr auf einmal gelesen werden kann, oder häufige Multi-Hop-Abfragen erforderlich sind, ist die dateibasierte Graphenlösung an ihrer Grenze. Empfehle dem Benutzer dann die Migration zu LightRAG (Graph + Vektor-Hybrid-Suche) – das Frontmatter und die [[Bidirectional Links]] sind das beste Migrationskorpus, die Migration ist verlustfrei. Führe vorher keine Datenbanken oder externen Dienste ein.