ontology

• Vous souhaitez qu'un agent mémorise des informations structurées entre les sessions (ex. : « Se souvenir qu'Alice est responsable du Projet X »).
• Vous avez besoin de relier des objets connexes et de parcourir ces liens ultérieurement (ex. : « Afficher toutes les tâches du projet Z », « De quoi dépend X ? »).
• Plusieurs skills doivent partager un état sans échanger de texte brut — un skill écrit un Commitment, un autre le lit comme une Task.
• Vous planifiez un travail en plusieurs étapes et souhaitez que chaque étape soit modélisée comme une transformation de graphe validée, avec annulation en cas de violation de contrainte.

• Vous n'avez besoin que d'un contexte éphémère à tour unique et n'avez aucun besoin de persistance entre les exécutions de l'agent.
• Vos données sont purement non structurées (prose libre) sans relations d'entités significatives à modéliser.
• Vous avez besoin d'une base de données graphe de niveau production avec une haute concurrence — pour les graphes volumineux ou complexes, le SKILL.md lui-même recommande de migrer vers SQLite.

Fourni avec un ensemble complet de types prédéfinis couvrant les agents (Person, Organization), le travail (Project, Task, Goal), le temps et le lieu (Event, Location), l'information (Document, Message, Note), ainsi que les ressources (Account, Device, Credential). Chaque type comporte des propriétés typées et des champs optionnels, vous permettant de modéliser le monde réel sans avoir à inventer des schémas de toutes pièces.

Chaque mutation est validée par rapport aux règles définies dans memory/ontology/schema.yaml avant d'être enregistrée. Les contraintes comprennent les champs obligatoires, les valeurs d'énumération, les propriétés interdites (par exemple, le blocage des secrets bruts sur Credential), les règles de type/cardinalité des relations, les vérifications d'acyclicité, ainsi que les vérifications de cohérence temporelle telles que end >= start sur Event.

Le graphe est stocké sous forme de fichier memory/ontology/graph.jsonl en ajout seul — chaque opération de création, mise à jour et relation est une nouvelle ligne, préservant l'historique complet. Pour les graphes complexes, le SKILL.md recommande de migrer vers SQLite, en conservant la même interface.

Un CLI scripts/ontology.py fournit des commandes pour toutes les opérations principales : create, query, get, related, relate, validate et schema-append. Cela permet de l'intégrer dans des scripts depuis n'importe quelle étape shell ou action d'agent, sans avoir à écrire de code graphe personnalisé.

Les compétences peuvent déclarer un contrat ontology dans leur propre fichier SKILL.md, en précisant les types qu'elles reads (lisent) et writes (écrivent), ainsi que les pré/post-conditions associées. Cela rend les dépendances de données entre compétences explicites et auditables, transformant ainsi l'ontology en un bus de messages typé entre les différentes capacités.

Les plans en plusieurs étapes peuvent être modélisés comme des séquences ordonnées d'opérations de graphe (CREATE → RELATE → CREATE …). Chaque étape est validée avant son exécution et l'ensemble du plan peut être annulé en cas de violation de contrainte, offrant aux agents une couche de planification structurée et inspectable.

Un agent crée des entités Person et Project la première fois qu'elles sont mentionnées, puis les relie avec des relations has_owner ou has_member. Lors des échanges ultérieurs, la requête « Que sais-je sur Alice ? » parcourt le graphe pour faire remonter tous les projets, tâches et événements associés, sans s'appuyer sur l'historique de la conversation.

Une compétence de lecture d'e-mails extrait un engagement d'un message et écrit une entité Commitment dans l'ontology. Une compétence de gestion des tâches distincte interroge périodiquement les objets Commitment en attente et crée automatiquement des entités Task liées — aucun couplage direct entre les deux compétences n'est nécessaire.

Un agent de planification modélise un projet sous forme d'un ensemble d'entités Task reliées par des relations blocks. La contrainte d'acyclicité empêche la validation de dépendances circulaires, et une requête related affiche instantanément ce qui doit être accompli avant qu'une tâche donnée puisse démarrer.

Avant d'exécuter un flux de travail complexe (par exemple, « Planifier une réunion d'équipe et assigner des tâches de suivi »), l'agent convertit chaque étape en une opération de graphe validée. Si une étape quelconque enfreint une contrainte, l'ensemble de la séquence est annulé, fournissant ainsi une piste d'exécution sûre et inspectable via le journal de type Action.