Ontology

1---2name: ontology3description: Typed knowledge graph for structured agent memory and composable skills. Use when creating/querying entities (Person, Project, Task, Event, Document), linking related objects, enforcing constraints, planning multi-step actions as graph transformations, or when skills need to share state. Trigger on "remember", "what do I know about", "link X to Y", "show dependencies", entity CRUD, or cross-skill data access.4---5 6# Ontology7 8A typed vocabulary + constraint system for representing knowledge as a verifiable graph.9 10## Core Concept11 12Everything is an **entity** with a **type**, **properties**, and **relations** to other entities. Every mutation is validated against type constraints before committing.13 14```15Entity: { id, type, properties, relations, created, updated }16Relation: { from_id, relation_type, to_id, properties }17```18 19## When to Use20 21| Trigger | Action |22|---------|--------|23| "Remember that..." | Create/update entity |24| "What do I know about X?" | Query graph |25| "Link X to Y" | Create relation |26| "Show all tasks for project Z" | Graph traversal |27| "What depends on X?" | Dependency query |28| Planning multi-step work | Model as graph transformations |29| Skill needs shared state | Read/write ontology objects |30 31## Core Types32 33```yaml34# Agents & People35Person: { name, email?, phone?, notes? }36Organization: { name, type?, members[] }37 38# Work39Project: { name, status, goals[], owner? }40Task: { title, status, due?, priority?, assignee?, blockers[] }41Goal: { description, target_date?, metrics[] }42 43# Time & Place44Event: { title, start, end?, location?, attendees[], recurrence? }45Location: { name, address?, coordinates? }46 47# Information48Document: { title, path?, url?, summary? }49Message: { content, sender, recipients[], thread? }50Thread: { subject, participants[], messages[] }51Note: { content, tags[], refs[] }52 53# Resources54Account: { service, username, credential_ref? }55Device: { name, type, identifiers[] }56Credential: { service, secret_ref }  # Never store secrets directly57 58# Meta59Action: { type, target, timestamp, outcome? }60Policy: { scope, rule, enforcement }61```62 63## Storage64 65Default: `memory/ontology/graph.jsonl`66 67```jsonl68{"op":"create","entity":{"id":"p_001","type":"Person","properties":{"name":"Alice"}}}69{"op":"create","entity":{"id":"proj_001","type":"Project","properties":{"name":"Website Redesign","status":"active"}}}70{"op":"relate","from":"proj_001","rel":"has_owner","to":"p_001"}71```72 73Query via scripts or direct file ops. For complex graphs, migrate to SQLite.74 75## Workflows76 77### Create Entity78 79```bash80python3 scripts/ontology.py create --type Person --props '{"name":"Alice","email":"alice@example.com"}'81```82 83### Query84 85```bash86python3 scripts/ontology.py query --type Task --where '{"status":"open"}'87python3 scripts/ontology.py get --id task_00188python3 scripts/ontology.py related --id proj_001 --rel has_task89```90 91### Link Entities92 93```bash94python3 scripts/ontology.py relate --from proj_001 --rel has_task --to task_00195```96 97### Validate98 99```bash100python3 scripts/ontology.py validate  # Check all constraints101```102 103## Constraints104 105Define in `memory/ontology/schema.yaml`:106 107```yaml108types:109  Task:110    required: [title, status]111    status_enum: [open, in_progress, blocked, done]112  113  Event:114    required: [title, start]115    validate: "end >= start if end exists"116 117  Credential:118    required: [service, secret_ref]119    forbidden_properties: [password, secret, token]  # Force indirection120 121relations:122  has_owner:123    from_types: [Project, Task]124    to_types: [Person]125    cardinality: many_to_one126  127  blocks:128    from_types: [Task]129    to_types: [Task]130    acyclic: true  # No circular dependencies131```132 133## Skill Contract134 135Skills that use ontology should declare:136 137```yaml138# In SKILL.md frontmatter or header139ontology:140  reads: [Task, Project, Person]141  writes: [Task, Action]142  preconditions:143    - "Task.assignee must exist"144  postconditions:145    - "Created Task has status=open"146```147 148## Planning as Graph Transformation149 150Model multi-step plans as a sequence of graph operations:151 152```153Plan: "Schedule team meeting and create follow-up tasks"154 1551. CREATE Event { title: "Team Sync", attendees: [p_001, p_002] }1562. RELATE Event -> has_project -> proj_0011573. CREATE Task { title: "Prepare agenda", assignee: p_001 }1584. RELATE Task -> for_event -> event_0011595. CREATE Task { title: "Send summary", assignee: p_001, blockers: [task_001] }160```161 162Each step is validated before execution. Rollback on constraint violation.163 164## Integration Patterns165 166### With Causal Inference167 168Log ontology mutations as causal actions:169 170```python171# When creating/updating entities, also log to causal action log172action = {173    "action": "create_entity",174    "domain": "ontology", 175    "context": {"type": "Task", "project": "proj_001"},176    "outcome": "created"177}178```179 180### Cross-Skill Communication181 182```python183# Email skill creates commitment184commitment = ontology.create("Commitment", {185    "source_message": msg_id,186    "description": "Send report by Friday",187    "due": "2026-01-31"188})189 190# Task skill picks it up191tasks = ontology.query("Commitment", {"status": "pending"})192for c in tasks:193    ontology.create("Task", {194        "title": c.description,195        "due": c.due,196        "source": c.id197    })198```199 200## Quick Start201 202```bash203# Initialize ontology storage204mkdir -p memory/ontology205touch memory/ontology/graph.jsonl206 207# Create schema (optional but recommended)208cat > memory/ontology/schema.yaml << 'EOF'209types:210  Task:211    required: [title, status]212  Project:213    required: [name]214  Person:215    required: [name]216EOF217 218# Start using219python3 scripts/ontology.py create --type Person --props '{"name":"Alice"}'220python3 scripts/ontology.py list --type Person221```222 223## References224 225- `references/schema.md` — Full type definitions and constraint patterns226- `references/queries.md` — Query language and traversal examples