loletranga/Personal-Knowledge-Graph

Knowledge Graph Personnel × Graphe de Connaissances (Fichier, Itératif)

Transformez un ensemble de documents Markdown en un réseau de connaissances « rémémorable et traçable » : chaque document reçoit une couche de métadonnées frontmatter, trois types de relations le relient en un graphe, et des scripts régénèrent une couche de distillation (registre de décisions + matrice d'adjacence du graphe), que l'agent peut consulter avant analyse et décision pour retrouver les réflexions passées et le contexte historique.

Concept fondamental (à comprendre avant d'agir)

1. Le document source est la seule source de vérité. Le graphe n'est pas un système indépendant ; le frontmatter et les doubles crochets résident dans les fichiers .md de l'utilisateur. Le répertoire graph/ est purement une sortie générée, supprimable et régénérable à tout moment. Toute modification se fait uniquement sur les documents source.
2. Écrire doit d'abord être confirmé. Le frontmatter est rédigé par l'agent, mais avant toute écriture en masse, un échantillon doit être montré à l'utilisateur et approuvé. Les relations de jugement comme supersedes (qui remplace qui) doivent être listées et confirmées avant écriture ; aucune écriture silencieuse n'est autorisée.
3. Mieux vaut rétrograder que forcer. Si la conclusion d'un document n'est pas lisible, marquez-le status: reference ; n'inventez pas de conclusion. Une « conclusion en une phrase » erronée peut induire l'utilisateur en erreur lors d'une décision – c'est plus nuisible que son absence.

Ce répertoire de compétence contient deux fichiers d'accompagnement (situés dans le même répertoire que ce SKILL.md) :

• scripts/gen_kb_graph.py — script de génération du graphe (bibliothèque standard pure, utilisable hors ligne)
• references/schema.md — spécification complète du frontmatter, sémantique des trois types d'arêtes, modèles de sortie, format de sortie des rappels. À lire lors de la première création de la base ou en cas de doute sur les champs.

---

Flux de travail

Étape 0 : Déterminer le périmètre, expliquer à l'utilisateur ce qui va se passer

• L'utilisateur donne un dossier → ce dossier est la racine de la base de connaissances.
• L'utilisateur donne un ou plusieurs fichiers → demander : utiliser le dossier contenant ces fichiers comme racine (recommandé, les documents historiques pourront se connecter en graphe) ou créer un nouveau dossier de base de connaissances indépendant pour les stocker.
• L'utilisateur n'a aucun fichier et veut d'abord créer la base → aller à l'étape 2 « squelette de base vide ».
• Avant de commencer, confirmer en deux ou trois phrases à l'utilisateur : la racine, quels fichiers seront modifiés (frontmatter des documents source + nouveau répertoire graph/), que le corps des documents ne sera pas touché.

Étape 1 : Détecter l'état de la base de connaissances

Lire le répertoire racine :

• Si <racine>/gen_kb_graph.py ou <racine>/graph/INDEX.md existe → mode itération (base existante)
• Sinon → mode création (nouvelle base)

Étape 2 A : Mode création (y compris squelette de base vide)

1. Squelette de base vide (si l'utilisateur n'a pas de fichier historique) : créer les fichiers suivants, puis passer à l'étape 3 pour informer —
   • <racine>/Aperçu des règles de la base de connaissances.md : extraire de references/schema.md les modèles de frontmatter et les trois règles principales, faciles à consulter pour l'utilisateur lors de la rédaction quotidienne (avec status: reference intégré)
   • <racine>/Modèle-document d'analyse.md : modèle vierge avec frontmatter complet (idem avec frontmatter intégré)
2. Installer le script : copier scripts/gen_kb_graph.py du répertoire de compétence vers <racine>/gen_kb_graph.py (sauter si existe déjà). L'installer dans la base de connaissances assure son auto-contenance — l'utilisateur ou un autre agent peut régénérer le graphe sans dépendre de cette compétence.
3. Essai : python3 <racine>/gen_kb_graph.py <racine>. Lire l'aperçu de <racine>/graph/report.md, rapporter la taille à l'utilisateur (combien de documents, combien manquent de frontmatter).
4. Rédaction des métadonnées (charge principale) : lire d'abord references/schema.md, puis traiter par sous-dossier ou domaine en lots :
   • Lire chaque document, rédiger le frontmatter : date (date de la conclusion), domain, status (active/superseded/reference), conclusion (une phrase, seulement « ce que ce document défend finalement », pas un résumé de contenu)
   • Montrer un échantillon d'abord : choisir 2-3 documents représentatifs (un document de décision, une ressource), montrer le frontmatter que vous allez écrire, l'utilisateur valide le ton avant d'écrire en masse
   • Identifier les relations d'évolution : paires de documents dont le nom contient v2/nouvelle version/copie/révision, ou qui se contredisent dans le contenu, proposer des pointeurs supersedes, les lister pour confirmation de l'utilisateur avant d'écrire
   • Rapporter l'avancement après chaque lot ; ne pas toucher au corps du document, seulement au frontmatter
5. Régénération et livraison : relancer le script (génère automatiquement graph/kb-graph.html, page de visualisation), montrer les premières lignes d'INDEX.md et les lacunes restantes dans report.md, et informer que l'utilisateur peut ouvrir kb-graph.html dans un navigateur pour voir le graphe interactif.

Étape 2 B : Mode itération (base existante)

1. Exécuter le <racine>/gen_kb_graph.py existant (s'il n'existe plus, le recopier depuis le répertoire de compétence)
2. Lire graph/report.md, ne traiter que l'incrément : nouveaux documents sans frontmatter, documents sans date/conclusion, liens brisés. Rédiger → confirmer → écrire
3. Compléter les arêtes sémantiques : pour les nouveaux documents, après lecture complète, proposer des relations related (« deux facettes d'une même chose ») et supersedes (« ce document corrige celui-là ») avec les documents existants, accompagnées d'une phrase de justification, confirmer avant écriture
4. Régénérer (y compris rafraîchissement de la page de visualisation kb-graph.html), rapporter les changements à l'utilisateur (nombre de nouveaux nœuds/arêtes, lacunes restantes)

Étape 3 : Informer l'utilisateur sur l'utilisation future

À la fin de chaque création/itération, suggérer à l'utilisateur (référence) :

Désormais, avant une analyse ou une décision, dites-moi simplement : « Rappelle-moi mes réflexions et conclusions sur XX », je consulterai le graphe, suivrai les chaînes d'évolution, vérifierai la fraîcheur, et vous fournirai un rapport de référence. Pour voir le graphe visuellement, ouvrez graph/kb-graph.html dans un navigateur (recherche, filtres, clic sur nœuds pour détails). Continuez à rédiger vos documents comme d'habitude, dites « mets à jour la base de connaissances » quand vous avez fini, et j'ajouterai automatiquement les métadonnées et les relations pour les nouveaux documents.

---

Mode Rappel (recherche avant décision)

Quand l'utilisateur demande de se souvenir de réflexions passées et que le répertoire cible contient déjà graph/ généré, suivre ce processus, lecture seule :

1. Lire graph/INDEX.md, faire correspondre les mots-clés thématiques avec les titres et conclusions des documents, présélectionner les éléments pertinents (plutôt trop que pas assez)
2. Si besoin d'extension, lire graph/GRAPH.md : suivre les chaînes d'évolution supersedes des documents présélectionnés, les voisins related pour compléter le contexte
3. Lire attentivement le frontmatter et la section de conclusion des documents pertinents (pas besoin de lire l'intégralité)
4. Produire un rapport structuré au format fixe (exemple complet dans references/schema.md) :
   • Liste des idées pertinentes : chaque entrée = date | conclusion en une phrase | statut | lien vers le document
   • Chaîne d'évolution : trajectoire des changements d'idée sur ce sujet, noter quand et pourquoi telle ou telle a été renversée/corrigée
   • Points de référence pour le problème actuel : quelles conclusions sont directement exploitables, lesquelles sont obsolètes et à noter
   • Déclaration d'absence de précédent : si le graphe ne contient aucune décision antérieure sur ce problème, dire clairement « C'est une décision entièrement nouvelle, aucun précédent existant sur lequel s'appuyer » — c'est également une sortie précieuse

---

Points de vérification avec l'utilisateur (doit s'arrêter)

1. Avant la création de la base : périmètre de la racine, règles d'ignorance (utiliser <racine>/.kbignore pour exclure des répertoires, un motif par ligne)
2. Avant d'écrire le frontmatter en masse : échantillon de 2-3 documents à confirmer
3. Avant d'écrire les relations supersedes : confirmation de la liste de paires
4. Toute modification du corps du document : interdite par défaut, seulement si l'utilisateur le demande explicitement

Utilisation du script

python3 gen_kb_graph.py <répertoire_racine_de_la_base> [--output graph] [--ignore "books,old,*_old"] [--no-html]

Ignoré par défaut : répertoires cachés, .venv, venv, node_modules, pycache, .git, le répertoire de sortie lui-même. Idempotent, peut être relancé à tout moment ; produit 5 fichiers (INDEX.md / GRAPH.md / kb-graph.json / report.md / kb-graph.html), format décrit dans references/schema.md. kb-graph.html est une page de visualisation mono-fichier sans dépendance (graphe orienté par force + tableau de registre de décisions, avec recherche, filtres, clic sur nœud pour détails, double-clic pour ouvrir le fichier source). Si l'environnement le permet, ouvrez-la directement dans un navigateur pour la présenter à l'utilisateur.

Limite d'évolution

Lorsque le nombre de documents dépasse environ 500, que GRAPH.md n'est plus lisible en une seule fois, ou qu'un raisonnement à plusieurs sauts fréquent est nécessaire, le graphe fichier atteint sa limite. Il est conseillé de migrer vers LightRAG (graphe + recherche vectorielle hybride) — le frontmatter et les doubles crochets sont le meilleur corpus de migration, sans perte. D'ici là, n'introduisez ni base de données ni service externe.