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 }

所有内容都是entity，具备type、properties以及与其他实体的relations。所有变更在提交前都会根据类型约束进行校验。

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

触发词	对应操作
"Remember that..."	创建/更新实体
"What do I know about X?"	查询图
"Link X to Y"	创建关系
"Show all tasks for project Z"	图遍历
"What depends on X?"	依赖查询
规划多步骤工作	建模为图转换
技能需要共享状态	读写本体对象

Core Types

核心类型

yaml

undefined

yaml

undefined

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 }

undefined

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

undefined

Storage

存储

Default:

memory/ontology/graph.jsonl

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.

默认存储路径：

memory/ontology/graph.jsonl

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"}

可通过脚本或直接文件操作查询。复杂图场景可迁移到SQLite。

Workflows

工作流

Create Entity

创建实体

bash

python3 scripts/ontology.py create --type Person --props '{"name":"Alice","email":"alice@example.com"}'

bash

python3 scripts/ontology.py create --type Person --props '{"name":"Alice","email":"alice@example.com"}'

Query

查询

bash

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

bash

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

关联实体

bash

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

bash

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

Validate

校验

bash

python3 scripts/ontology.py validate  # Check all constraints

bash

python3 scripts/ontology.py validate  # Check all constraints

Constraints

约束

Define in

memory/ontology/schema.yaml

:

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

在

memory/ontology/schema.yaml

中定义：

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:

yaml

undefined

使用本体的技能需要声明：

yaml

undefined

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"

undefined

ontology: reads: [Task, Project, Person] writes: [Task, Action] preconditions: - "Task.assignee must exist" postconditions: - "Created Task has status=open"

undefined

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.

将多步计划建模为一系列图操作：

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] }

每一步执行前都会进行校验，违反约束时会回滚。

Integration Patterns

集成模式

With Causal Inference

结合因果推断

Log ontology mutations as causal actions:

python

undefined

将本体变更作为因果动作记录：

python

undefined

When creating/updating entities, also log to causal action log

action = { "action": "create_entity", "domain": "ontology", "context": {"type": "Task", "project": "proj_001"}, "outcome": "created" }

undefined

action = { "action": "create_entity", "domain": "ontology", "context": {"type": "Task", "project": "proj_001"}, "outcome": "created" }

undefined

Cross-Skill Communication

跨技能通信

python

undefined

python

undefined

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 })

undefined

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

undefined

Quick Start

快速开始

bash

undefined

bash

undefined

Initialize ontology storage

mkdir -p memory/ontology touch memory/ontology/graph.jsonl

Create schema (optional but recommended)

cat > memory/ontology/schema.yaml << 'EOF' types: Task: required: [title, status] Project: required: [name] Person: required: [name] EOF

Start using

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

undefined

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

undefined

References

参考资料

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

```
references/schema.md
```
— 完整类型定义与约束模式
```
references/queries.md
```
— 查询语言与遍历示例

ontology

Original

Translation

Ontology

本体

Core Concept

核心概念

When to Use

使用场景

Core Types

核心类型

Agents & People

Agents & People

Work

Work

Time & Place

Time & Place

Information

Information

Resources

Resources

Meta

Meta

Storage

存储

Workflows

工作流

Create Entity

创建实体

Query

查询

Link Entities

关联实体

Validate

校验

Constraints

约束

Skill Contract

技能契约

In SKILL.md frontmatter or header

In SKILL.md frontmatter or header

Planning as Graph Transformation

作为图转换的规划

Integration Patterns

集成模式

With Causal Inference

结合因果推断

When creating/updating entities, also log to causal action log

When creating/updating entities, also log to causal action log

Cross-Skill Communication

跨技能通信

Email skill creates commitment

Email skill creates commitment

Task skill picks it up

Task skill picks it up

Quick Start

快速开始

Initialize ontology storage

Initialize ontology storage

Create schema (optional but recommended)

Create schema (optional but recommended)

Start using

Start using

References

参考资料