ontology

• Quieres que un agente recuerde información estructurada entre sesiones (p. ej., "Recuerda que Alice es propietaria del Proyecto X").
• Necesitas vincular objetos relacionados y recorrer esos vínculos más tarde (p. ej., "Mostrar todas las tareas del proyecto Z", "¿Qué depende de X?").
• Varias habilidades necesitan compartir estado sin intercambiar texto sin formato — una habilidad escribe un Commitment, otra lo lee como una Task.
• Estás planificando trabajo en varios pasos y quieres que cada paso sea modelado como una transformación de grafo validada con reversión en caso de violación de restricciones.

• Solo necesitas contexto efímero de un único turno y no tienes necesidad de persistencia entre ejecuciones del agente.
• Tus datos son puramente no estructurados (prosa en formato libre) sin relaciones de entidades significativas que modelar.
• Necesitas una base de datos de grafos de nivel productivo con alta concurrencia — para grafos grandes o complejos, el propio SKILL.md recomienda migrar a SQLite.

Incluye un conjunto exhaustivo de tipos predefinidos que abarcan agentes (Person, Organization), trabajo (Project, Task, Goal), tiempo y lugar (Event, Location), información (Document, Message, Note) y recursos (Account, Device, Credential). Cada tipo cuenta con propiedades tipadas y campos opcionales para que puedas modelar el mundo real sin necesidad de inventar esquemas desde cero.

Toda mutación es validada contra las reglas definidas en memory/ontology/schema.yaml antes de ser confirmada. Las restricciones incluyen campos obligatorios, valores de enumeración, propiedades prohibidas (p. ej., el bloqueo de secretos en texto plano en Credential), reglas de tipo y cardinalidad de relaciones, verificaciones de aciclicidad y comprobaciones de coherencia temporal como end >= start en Event.

El grafo se almacena como un archivo memory/ontology/graph.jsonl de solo escritura — cada operación de creación, actualización y relación es una nueva línea, preservando el historial completo. Para grafos complejos, el SKILL.md recomienda migrar a SQLite, manteniendo la misma interfaz.

Un CLI scripts/ontology.py proporciona comandos para todas las operaciones principales: create, query, get, related, relate, validate y schema-append. Esto permite ejecutarlo mediante scripts desde cualquier paso de shell o acción de agente sin necesidad de escribir código de grafo personalizado.

Los skills pueden declarar un contrato de ontology en su propio SKILL.md especificando qué tipos reads (lee) y writes (escribe), junto con pre/postcondiciones. Esto hace que las dependencias de datos entre skills sean explícitas y auditables, convirtiendo el ontology en un bus de mensajes tipado entre capacidades.

Los planes de múltiples pasos pueden modelarse como secuencias ordenadas de operaciones sobre grafos (CREATE → RELATE → CREATE …). Cada paso se valida antes de su ejecución y el plan completo puede revertirse ante una violación de restricciones, lo que proporciona a los agentes una capa de planificación estructurada e inspeccionable.

Un agente crea entidades Person y Project la primera vez que se mencionan, y luego las vincula mediante relaciones has_owner o has_member. En turnos posteriores, la consulta "¿Qué sé sobre Alice?" recorre el grafo para mostrar todos los proyectos, tareas y eventos relacionados, sin depender del historial de conversación.

Una habilidad de lectura de correo electrónico extrae un compromiso de un mensaje y escribe una entidad Commitment en el ontology. Una habilidad de gestión de tareas independiente consulta periódicamente los objetos Commitment pendientes y crea automáticamente entidades Task vinculadas — sin necesidad de acoplamiento directo entre las dos habilidades.

Un agente de planificación modela un proyecto como un conjunto de entidades Task con relaciones blocks. La restricción de aciclicidad evita que se confirmen dependencias circulares, y una consulta related muestra al instante qué debe completarse antes de que una tarea determinada pueda comenzar.

Antes de ejecutar un flujo de trabajo complejo (por ejemplo, "Programar reunión de equipo y asignar tareas de seguimiento"), el agente convierte cada paso en una operación de grafo validada. Si algún paso viola una restricción, toda la secuencia se revierte, proporcionando un historial de ejecución seguro e inspeccionable a través del registro de tipo Action.