Ontology XGJK

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 consistent: it implements a local, append-only typed ontology stored under memory/ontology and the code and instructions match that purpose; no external credentials, downloads, or suspicious network behavior are declared — but part of the implementation is truncated in the supplied view, so review the complete script before use.

Purpose & Capability

Name/description (typed knowledge graph for agent memory) matches what is present: SKILL.md documents entity types and workflows and scripts/ontology.py implements create/query/relate/validate against a local graph file. No unrelated credentials, binaries, or cloud APIs are requested.

Instruction Scope

Instructions operate on local storage (memory/ontology/graph.jsonl), describe CLI usage, and encourage append-only mutations and schema validation. This is appropriate, but the skill permits storing file paths (Document.path) and secret references (secret_ref). While the schema forbids storing raw secrets in Credential objects, the ontology can hold references to local file paths or external secret-store references which could be used by other skills to access sensitive data. Also: portions of the python script and SKILL.md were truncated in the supplied view, so confirm there are no additional instructions that read arbitrary system files or call external endpoints.

Install Mechanism

No install spec or external downloads; code is included in the package and the runtime behavior is file-based. This is low-risk from an install perspective (nothing is fetched from remote URLs).

Credentials

No environment variables, credentials, or config paths are required. The declared data model includes credential references but explicitly forbids embedding raw secrets; requested privileges are consistent with a local graph store.

Persistence & Privilege

always is false and the skill is user-invocable; it does not request persistent platform-level privileges. It writes to its own workspace path (memory/ontology) which is expected behavior for a local datastore.

Assessment

This skill appears coherent for local structured memory: it reads/writes an append-only graph file under memory/ontology and provides Python utilities to manage entities and relations. Before installing, review the full scripts/ontology.py (the provided snippet was truncated) to ensure there are no hidden network calls or code that reads arbitrary system files. Consider these practical precautions: (1) run the tool in a restricted workspace or container so the graph file cannot reference sensitive host paths, (2) enforce file permissions on memory/ontology to prevent other processes from reading stored references, (3) avoid putting secrets directly into the graph (use secret_ref patterns and an appropriate secret store), and (4) if other skills are allowed to read this ontology, vet those skills because cross-skill access can leak sensitive references. If you want stronger assurance, provide the complete untruncated script for review or run the tool in an isolated environment first.

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.