核心类型

# 代理与人员
Person: { name, email?, phone?, notes? }
Organization: { name, type?, members[] }

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

# 时间与地点
Event: { title, start, end?, location?, attendees[], recurrence? }
Location: { name, address?, coordinates? }

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

# 资源
Account: { service, username, credential_ref? }
Device: { name, type, identifiers[] }
Credential: { service, secret_ref }  # 切勿直接存储密钥

# 元数据
Action: { type, target, timestamp, outcome? }
Policy: { scope, rule, enforcement }

存储

默认路径：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"}

通过脚本或直接文件操作进行查询。对于复杂的图，可迁移到 SQLite。

仅追加规则

处理现有的本体数据或模式时，应追加/合并更改，而不是覆盖文件。这可以保留历史记录并避免破坏先前的定义。

工作流程

使用模块化 API

from src.services.entity_service import create_entity, query_entities
from src.services.relation_service import create_relation
from src.services.validation_service import validate_graph

# 创建实体
alice = create_entity("Person", {"name": "Alice"}, "memory/ontology/graph.jsonl")
project = create_entity("Project", {"name": "Website"}, "memory/ontology/graph.jsonl")

# 创建关系
create_relation(alice["id"], "owns", project["id"], {}, "memory/ontology/graph.jsonl")

# 验证
errors = validate_graph("memory/ontology/graph.jsonl", "memory/ontology/schema.yaml")

使用 CLI

# 创建实体
python3 -m src.cli create --type Person --props '{"name":"Alice"}'

# 查询
python3 -m src.cli query --type Task --where '{"status":"open"}'
python3 -m src.cli get --id task_001
python3 -m src.cli related --id proj_001 --rel has_task

# 链接实体
python3 -m src.cli relate --from proj_001 --rel has_task --to task_001

# 验证
python3 -m src.cli validate

旧版 CLI（已弃用）

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

约束

在 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]  # 强制间接引用

relations:
  has_owner:
    from_types: [Project, Task]
    to_types: [Person]
    cardinality: many_to_one
  
  blocks:
    from_types: [Task]
    to_types: [Task]
    acyclic: true  # 无循环依赖

技能契约

使用本体的技能应声明：

# 在 SKILL.md 的前言或头部
ontology:
  reads: [Task, Project, Person]
  writes: [Task, Action]
  preconditions:
    - "Task.assignee must exist"
  postconditions:
    - "Created Task has status=open"

作为图转换的规划

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

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

每个步骤在执行前都会进行验证。违反约束时回滚。

集成模式

与因果推断集成

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

# 当创建/更新实体时，也记录到因果动作日志
action = {
    "action": "create_entity",
    "domain": "ontology", 
    "context": {"type": "Task", "project": "proj_001"},
    "outcome": "created"
}

跨技能通信

# 邮件技能创建承诺
commitment = ontology.create("Commitment", {
    "source_message": msg_id,
    "description": "Send report by Friday",
    "due": "2026-01-31"
})

# 任务技能接收并处理
tasks = ontology.query("Commitment", {"status": "pending"})
for c in tasks:
    ontology.create("Task", {
        "title": c.description,
        "due": c.due,
        "source": c.id
    })

快速开始

# 初始化本体存储
mkdir -p memory/ontology
touch memory/ontology/graph.jsonl

# 运行测试
cd skills/ontology
python3 -m pytest tests/ -v

# 创建模式（可选但推荐）
python3 -m src.cli schema-append --data '{
  "types": {
    "Task": { "required": ["title", "status"] },
    "Project": { "required": ["name"] },
    "Person": { "required": ["name"] }
  }
}'

# 开始使用
python3 -m src.cli create --type Person --props '{"name":"Alice"}'
python3 -m src.cli list --type Person

参考

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

指令范围

运行时指令操作本地文件（memory/ontology/graph.jsonl 和 memory/ontology/schema.yaml），并提供用于创建/查询/关联/验证的 CLI 用法；这属于范围之内。该技能读取/写入工作区文件，并在使用时创建 memory/ontology 目录。验证包括属性/枚举/禁止检查、关系类型/基数验证、标记为 acyclic: true 的关系的无环性检查，以及 Event 的 end >= start 检查；其他更高级别的约束可能仍然是仅文档性的，除非在代码中实现。

每周安装次数

140

代码仓库

hiveminderbot/ontology

首次出现

2026年3月8日

安全审计

Gen Agent Trust HubPassSocketPassSnykPass

安装于

cursor139

gemini-cli138

github-copilot138

amp138

cline138

codex138

When to Use

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

Using the Modular API

from src.services.entity_service import create_entity, query_entities
from src.services.relation_service import create_relation
from src.services.validation_service import validate_graph

# Create entities
alice = create_entity("Person", {"name": "Alice"}, "memory/ontology/graph.jsonl")
project = create_entity("Project", {"name": "Website"}, "memory/ontology/graph.jsonl")

# Create relation
create_relation(alice["id"], "owns", project["id"], {}, "memory/ontology/graph.jsonl")

# Validate
errors = validate_graph("memory/ontology/graph.jsonl", "memory/ontology/schema.yaml")

Using the CLI

# Create entity
python3 -m src.cli create --type Person --props '{"name":"Alice"}'

# Query
python3 -m src.cli query --type Task --where '{"status":"open"}'
python3 -m src.cli get --id task_001
python3 -m src.cli related --id proj_001 --rel has_task

# Link entities
python3 -m src.cli relate --from proj_001 --rel has_task --to task_001

# Validate
python3 -m src.cli validate

Legacy CLI (deprecated)

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

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

# Run tests
cd skills/ontology
python3 -m pytest tests/ -v

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

# Start using
python3 -m src.cli create --type Person --props '{"name":"Alice"}'
python3 -m src.cli 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.

Weekly Installs

140

Repository

hiveminderbot/ontology

First Seen

Mar 8, 2026

Security Audits

Gen Agent Trust HubPassSocketPassSnykPass

Installed on

cursor139

gemini-cli138

github-copilot138

amp138

cline138

codex138