Ontology 1.0.4

Typed knowledge graph for structured agent memory and composable skills. Use when creating/querying entities (Person, Project, Task, Event, Document), linkin...

Security Scan

The skill is internally coherent with its stated purpose (a local typed knowledge graph) and does not request credentials or network access, but there are a few implementation issues you should review before use.

Purpose & Capability

Name/description (typed knowledge graph / structured memory) matches the provided SKILL.md and the included Python script which implements create/query/relate/validate operations. No unrelated credentials, binaries, or external services are required.

Instruction Scope

SKILL.md instructs the agent to read/write a local append-only graph file (memory/ontology/graph.jsonl) and to use the included CLI. The instructions stay within the stated domain (entity CRUD, relations, queries). They mention document paths and secret references (secret_ref) but do not instruct reading arbitrary system files or exfiltrating data.

Install Mechanism

No install spec (instruction-only) and the included script is pure Python with no network/download steps. This is low risk from installation/execution perspective.

Credentials

The skill requires no environment variables, no credentials, and asks the user to store secrets by reference rather than directly. The requested environment access is proportionate to a local ontology tool.

Persistence & Privilege

It is not always-enabled and does not request elevated platform privileges. It writes only to workspace-local storage by default and does not modify other skills or global agent settings.

Assessment

This skill appears to implement a local ontology/knowledge-graph and is coherent with its description. Before installing and using it: 1) run it in an isolated workspace (the default graph path is memory/ontology/graph.jsonl) to limit file writes; 2) review scripts/ontology.py yourself—there is a resolve_safe_path helper but other file I/O functions (load_graph/append_op) do not enforce it, so if you or an automation pass an arbitrary path you could write outside the workspace; 3) follow the schema guidance to store secrets via secret references (secret_ref) rather than embedding secrets; 4) if you need stronger safety, modify the script to apply resolve_safe_path to all file-path inputs or restrict CLI/path inputs to the workspace. Overall the package looks benign but has small implementation hygiene issues worth fixing before broad use.

Ontology

A typed vocabulary + constraint system for representing knowledge as a verifiable graph.

Core Concept

Everything is an entity with a type, properties, and relations to other entities. Every mutation is validated against type constraints before committing.

Entity: { id, type, properties, relations, created, updated }
Relation: { from_id, relation_type, to_id, properties }

When to Use

Trigger	Action
"Remember that..."	Create/update entity
"What do I know about X?"	Query graph
"Link X to Y"	Create relation
"Show all tasks for project Z"	Graph traversal
"What depends on X?"	Dependency query
Planning multi-step work	Model as graph transformations
Skill needs shared state	Read/write ontology objects

Core Types

# Agents & People
Person: { name, email?, phone?, notes? }
Organization: { name, type?, members[] }

# Work
Project: { name, status, goals[], owner? }
Task: { title, status, due?, priority?, assignee?, blockers[] }
Goal: { description, target_date?, metrics[] }

# Time & Place
Event: { title, start, end?, location?, attendees[], recurrence? }
Location: { name, address?, coordinates? }

# Information
Document: { title, path?, url?, summary? }
Message: { content, sender, recipients[], thread? }
Thread: { subject, participants[], messages[] }
Note: { content, tags[], refs[] }

# Resources
Account: { service, username, credential_ref? }
Device: { name, type, identifiers[] }
Credential: { service, secret_ref }  # Never store secrets directly

# Meta
Action: { type, target, timestamp, outcome? }
Policy: { scope, rule, enforcement }

Storage

Default: memory/ontology/graph.jsonl

{"op":"create","entity":{"id":"p_001","type":"Person","properties":{"name":"Alice"}}}
{"op":"create","entity":{"id":"proj_001","type":"Project","properties":{"name":"Website Redesign","status":"active"}}}
{"op":"relate","from":"proj_001","rel":"has_owner","to":"p_001"}

Query via scripts or direct file ops. For complex graphs, migrate to SQLite.

Append-Only Rule

When working with existing ontology data or schema, append/merge changes instead of overwriting files. This preserves history and avoids clobbering prior definitions.

Workflows

Create Entity

python3 scripts/ontology.py create --type Person --props '{"name":"Alice","email":"[e-mail]"}'

Query

python3 scripts/ontology.py query --type Task --where '{"status":"open"}'
python3 scripts/ontology.py get --id task_001
python3 scripts/ontology.py related --id proj_001 --rel has_task

Link Entities

python3 scripts/ontology.py relate --from proj_001 --rel has_task --to task_001

Validate

python3 scripts/ontology.py validate  # Check all constraints

Constraints

Define in memory/ontology/schema.yaml:

types:
  Task:
    required: [title, status]
    status_enum: [open, in_progress, blocked, done]
  
  Event:
    required: [title, start]
    validate: "end >= start if end exists"

  Credential:
    required: [service, secret_ref]
    forbidden_properties: [password, secret, token]  # Force indirection

relations:
  has_owner:
    from_types: [Project, Task]
    to_types: [Person]
    cardinality: many_to_one
  
  blocks:
    from_types: [Task]
    to_types: [Task]
    acyclic: true  # No circular dependencies

Skill Contract

Skills that use ontology should declare:

# In SKILL.md frontmatter or header
ontology:
  reads: [Task, Project, Person]
  writes: [Task, Action]
  preconditions:
    - "Task.assignee must exist"
  postconditions:
    - "Created Task has status=open"

Planning as Graph Transformation

Model multi-step plans as a sequence of graph operations:

Plan: "Schedule team meeting and create follow-up tasks"

1. CREATE Event { title: "Team Sync", attendees: [p_001, p_002] }
2. RELATE Event -> has_project -> proj_001
3. CREATE Task { title: "Prepare agenda", assignee: p_001 }
4. RELATE Task -> for_event -> event_001
5. CREATE Task { title: "Send summary", assignee: p_001, blockers: [task_001] }

Each step is validated before execution. Rollback on constraint violation.

Integration Patterns

With Causal Inference

Log ontology mutations as causal actions:

# When creating/updating entities, also log to causal action log
action = {
    "action": "create_entity",
    "domain": "ontology", 
    "context": {"type": "Task", "project": "proj_001"},
    "outcome": "created"
}

Cross-Skill Communication

# Email skill creates commitment
commitment = ontology.create("Commitment", {
    "source_message": msg_id,
    "description": "Send report by Friday",
    "due": "2026-01-31"
})

# Task skill picks it up
tasks = ontology.query("Commitment", {"status": "pending"})
for c in tasks:
    ontology.create("Task", {
        "title": c.description,
        "due": c.due,
        "source": c.id
    })

Quick Start

# Initialize ontology storage
mkdir -p memory/ontology
touch memory/ontology/graph.jsonl

# Create schema (optional but recommended)
python3 scripts/ontology.py schema-append --data '{
  "types": {
    "Task": { "required": ["title", "status"] },
    "Project": { "required": ["name"] },
    "Person": { "required": ["name"] }
  }
}'

# Start using
python3 scripts/ontology.py create --type Person --props '{"name":"Alice"}'
python3 scripts/ontology.py list --type Person

References

• references/schema.md — Full type definitions and constraint patterns
• references/queries.md — Query language and traversal examples

Instruction Scope

Runtime instructions operate on local files (memory/ontology/graph.jsonl and memory/ontology/schema.yaml) and provide CLI usage for create/query/relate/validate; this is within scope. The skill reads/writes workspace files and will create the memory/ontology directory when used. Validation includes property/enum/forbidden checks, relation type/cardinality validation, acyclicity for relations marked acyclic: true, and Event end >= start checks; other higher-level constraints may still be documentation-only unless implemented in code.