Back to Details

ontology

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

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

使用场景

TriggerAction
"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 workModel as graph transformations
Skill needs shared stateRead/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

Agents & People

Person: { name, email?, phone?, notes? } Organization: { name, type?, members[] }
Person: { name, email?, phone?, notes? } Organization: { name, type?, members[] }

Work

Work

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

Time & Place

Time & Place

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

Information

Information

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

Resources

Resources

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

Meta

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

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

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

Email skill creates commitment

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

Task skill picks it up

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

Initialize ontology storage

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

Create schema (optional but recommended)

Create schema (optional but recommended)

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

Start using

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
    — 查询语言与遍历示例