ontology

• Vuoi che un agente ricordi informazioni strutturate tra le sessioni (ad es. "Ricorda che Alice possiede il Progetto X").
• Hai bisogno di collegare oggetti correlati e attraversare quei collegamenti in seguito (ad es. "Mostra tutti i task per il progetto Z", "Cosa dipende da X?").
• Più skill devono condividere lo stato senza passare testo grezzo — una skill scrive un Commitment, un'altra lo legge come Task.
• Stai pianificando un lavoro in più fasi e vuoi che ogni fase sia modellata come una trasformazione del grafo validata con rollback in caso di violazione dei vincoli.

• Hai bisogno solo di un contesto effimero a turno singolo e non hai necessità di persistenza tra le esecuzioni dell'agente.
• I tuoi dati sono puramente non strutturati (testo in prosa libera) senza relazioni significative tra entità da modellare.
• Hai bisogno di un database a grafo di livello produttivo con alta concorrenza — per grafi grandi o complessi, lo stesso SKILL.md raccomanda di migrare a SQLite.

Viene fornito con un insieme completo di tipi predefiniti che coprono agenti (Person, Organization), lavoro (Project, Task, Goal), tempo e luogo (Event, Location), informazioni (Document, Message, Note) e risorse (Account, Device, Credential). Ogni tipo include proprietà tipizzate e campi opzionali, così puoi modellare il mondo reale senza dover inventare schemi da zero.

Ogni mutazione viene validata rispetto alle regole definite in memory/ontology/schema.yaml prima di essere applicata. I vincoli includono campi obbligatori, valori enum, proprietà vietate (ad es. il blocco di segreti grezzi su Credential), regole di tipo/cardinalità delle relazioni, verifiche di aciclicità e controlli di coerenza temporale come end >= start su Event.

Il grafo viene archiviato come file memory/ontology/graph.jsonl in modalità append-only — ogni operazione di creazione, aggiornamento e collegamento corrisponde a una nuova riga, preservando la cronologia completa. Per grafi complessi, il file SKILL.md raccomanda di migrare a SQLite, mantenendo la stessa interfaccia.

Un CLI scripts/ontology.py fornisce comandi per tutte le operazioni principali: create, query, get, related, relate, validate e schema-append. Questo lo rende scriptabile da qualsiasi passaggio di shell o azione di agente senza dover scrivere codice grafico personalizzato.

Le skill possono dichiarare un contratto ontology nel proprio SKILL.md specificando quali tipi reads (legge) e writes (scrive), insieme a pre/post-condizioni. Questo rende esplicite e verificabili le dipendenze di dati tra skill, trasformando l'ontology in un bus di messaggi tipizzato tra le varie capacità.

I piani multi-step possono essere modellati come sequenze ordinate di operazioni su grafi (CREATE → RELATE → CREATE …). Ogni passo viene validato prima dell'esecuzione e l'intero piano può essere annullato in caso di violazione di un vincolo, fornendo agli agenti un livello di pianificazione strutturato e ispezionabile.

Un agente crea entità Person e Project la prima volta che vengono menzionate, quindi le collega tramite relazioni has_owner o has_member. Nei turni successivi, la domanda "Cosa so di Alice?" attraversa il grafo per recuperare tutti i progetti, i task e gli eventi correlati, senza fare affidamento sulla cronologia della conversazione.

Una skill di lettura delle email estrae un impegno da un messaggio e scrive un'entità Commitment nell'ontology. Una skill separata di gestione delle attività interroga periodicamente gli oggetti Commitment in sospeso e crea automaticamente entità Task collegate — senza alcun accoppiamento diretto tra le due skill.

Un agente di pianificazione modella un progetto come un insieme di entità Task con relazioni blocks. Il vincolo di aciclicità impedisce che le dipendenze circolari vengano salvate, e una query related mostra immediatamente cosa deve essere completato prima che un determinato task possa iniziare.

Prima di eseguire un flusso di lavoro complesso (ad esempio "Pianifica una riunione del team e assegna le attività di follow-up"), l'agente converte ogni fase in un'operazione su grafo validata. Se un qualsiasi passaggio viola un vincolo, l'intera sequenza viene annullata, fornendo un percorso di esecuzione sicuro e ispezionabile tramite il log di tipo Action.