ontology

• Você quer que um agente lembre informações estruturadas entre sessões (ex.: "Lembre que Alice é dona do Projeto X").
• Você precisa vincular objetos relacionados e percorrer esses vínculos posteriormente (ex.: "Mostre todas as tarefas do projeto Z", "O que depende de X?").
• Múltiplas skills precisam compartilhar estado sem passar texto bruto — uma skill escreve um Commitment, outra lê como uma Task.
• Você está planejando um trabalho em múltiplas etapas e quer que cada etapa seja modelada como uma transformação de grafo validada com rollback em caso de violação de restrição.

• Você só precisa de contexto efêmero e de turno único, sem necessidade de persistência entre execuções do agente.
• Seus dados são puramente não estruturados (texto em prosa livre) sem relações de entidade significativas para modelar.
• Você precisa de um banco de dados de grafos em nível de produção com alta concorrência — para grafos grandes ou complexos, o próprio SKILL.md recomenda migrar para o SQLite.

Acompanha um conjunto abrangente de tipos pré-definidos cobrindo agentes (Person, Organization), trabalho (Project, Task, Goal), tempo e lugar (Event, Location), informação (Document, Message, Note) e recursos (Account, Device, Credential). Cada tipo possui propriedades tipadas e campos opcionais para que você modele o mundo real sem precisar criar schemas do zero.

Toda mutação é validada em relação às regras definidas em memory/ontology/schema.yaml antes de ser confirmada. As restrições incluem campos obrigatórios, valores de enum, propriedades proibidas (por exemplo, bloqueio de segredos brutos em Credential), regras de tipo/cardinalidade de relações, verificações de aciclicidade e verificações de sanidade temporal como end >= start em Event.

O grafo é armazenado como um arquivo memory/ontology/graph.jsonl somente com anexação — cada operação de criação, atualização e relacionamento gera uma nova linha, preservando o histórico completo. Para grafos complexos, o SKILL.md recomenda migrar para o SQLite, mantendo a mesma interface.

Um CLI scripts/ontology.py fornece comandos para todas as operações principais: create, query, get, related, relate, validate e schema-append. Isso o torna executável por scripts a partir de qualquer etapa de shell ou ação de agente, sem a necessidade de escrever código de grafo personalizado.

As skills podem declarar um contrato de ontology em seu próprio SKILL.md, especificando quais tipos elas reads (leem) e writes (escrevem), além de pré e pós-condições. Isso torna as dependências de dados entre skills explícitas e auditáveis, transformando o ontology em um barramento de mensagens tipado entre capacidades.

Planos de múltiplas etapas podem ser modelados como sequências ordenadas de operações de grafo (CREATE → RELATE → CREATE …). Cada etapa é validada antes da execução e o plano completo pode ser revertido em caso de violação de restrição, oferecendo aos agentes uma camada de planejamento estruturada e inspecionável.

Um agente cria entidades Person e Project na primeira vez que são mencionadas e, em seguida, as vincula com relações has_owner ou has_member. Em turnos futuros, ao consultar "O que eu sei sobre a Alice?", o grafo é percorrido para trazer à tona todos os projetos, tarefas e eventos relacionados, sem depender do histórico da conversa.

Uma skill de leitura de e-mails extrai um compromisso de uma mensagem e grava uma entidade Commitment na ontology. Uma skill separada de gerenciamento de tarefas consulta periodicamente os objetos Commitment pendentes e cria automaticamente entidades Task vinculadas — sem necessidade de acoplamento direto entre as duas skills.

Um agente de planejamento modela um projeto como um conjunto de entidades Task com relações blocks. A restrição de aciclicidade impede que dependências circulares sejam confirmadas, e uma consulta related mostra instantaneamente o que deve ser concluído antes que uma determinada tarefa possa ser iniciada.

Antes de executar um fluxo de trabalho complexo (por exemplo, "Agendar reunião da equipe e atribuir tarefas de acompanhamento"), o agente converte cada etapa em uma operação de grafo validada. Se qualquer etapa violar uma restrição, toda a sequência é revertida, fornecendo um rastro de execução seguro e inspecionável por meio do log do tipo Action.