ontology

• You want an agent to remember structured information across sessions (e.g. "Remember that Alice owns Project X").
• You need to link related objects and traverse those links later (e.g. "Show all tasks for project Z", "What depends on X?").
• Multiple skills need to share state without passing raw text — one skill writes a Commitment, another reads it as a Task.
• You are planning multi-step work and want each step modelled as a validated graph transformation with rollback on constraint violation.

• You only need ephemeral, single-turn context and have no need for persistence between agent runs.
• Your data is purely unstructured (free-form prose) with no meaningful entity relationships to model.
• You need a production-grade graph database with high concurrency — for large or complex graphs, the SKILL.md itself recommends migrating to SQLite.

Ships with a comprehensive set of pre-defined types covering agents (Person, Organization), work (Project, Task, Goal), time and place (Event, Location), information (Document, Message, Note), and resources (Account, Device, Credential). Each type carries typed properties and optional fields so you model the real world without inventing schemas from scratch.

Every mutation is validated against rules defined in memory/ontology/schema.yaml before being committed. Constraints include required fields, enum values, forbidden properties (e.g. blocking raw secrets on Credential), relation type/cardinality rules, acyclicity checks, and temporal sanity checks like end >= start on Event.

The graph is stored as an append-only memory/ontology/graph.jsonl file — every create, update, and relate operation is a new line, preserving full history. For complex graphs the SKILL.md recommends migrating to SQLite, keeping the same interface.

A scripts/ontology.py CLI provides commands for all core operations: create, query, get, related, relate, validate, and schema-append. This makes it scriptable from any shell step or agent action without writing custom graph code.

Skills can declare an ontology contract in their own SKILL.md specifying which types they reads and writes plus pre/post-conditions. This makes inter-skill data dependencies explicit and auditable, turning the ontology into a typed message bus between capabilities.

Multi-step plans can be modelled as ordered sequences of graph operations (CREATE → RELATE → CREATE …). Each step is validated before execution and the entire plan can roll back on a constraint violation, giving agents a structured, inspectable planning layer.

An agent creates Person and Project entities the first time they are mentioned, then links them with has_owner or has_member relations. On future turns, querying "What do I know about Alice?" traverses the graph to surface all related projects, tasks, and events without relying on conversation history.

An email-reading skill extracts a commitment from a message and writes a Commitment entity to the ontology. A separate task-management skill periodically queries pending Commitment objects and automatically creates linked Task entities — no direct coupling between the two skills required.

A planning agent models a project as a set of Task entities with blocks relations. The acyclicity constraint prevents circular dependencies from being committed, and a related query instantly shows what must be completed before a given task can start.

Before executing a complex workflow (e.g. "Schedule team meeting and assign follow-up tasks"), the agent converts each step into a validated graph operation. If any step violates a constraint the whole sequence rolls back, providing a safe and inspectable execution trail via the Action type log.