ontology

• 您希望智能体在会话之间记住结构化信息（例如："记住 Alice 拥有项目 X"）。
• 您需要关联相关对象并在之后遍历这些关联（例如："显示项目 Z 的所有任务"、"什么依赖于 X？"）。
• 多个技能需要共享状态而无需传递原始文本——一个技能写入 Commitment，另一个将其作为 Task 读取。
• 您正在规划多步骤工作，并希望将每个步骤建模为在违反约束时可回滚的经过验证的图转换。

• 您只需要临时的、单轮的上下文，无需在代理运行之间保持持久性。
• 您的数据是纯非结构化的（自由格式的散文），没有有意义的实体关系需要建模。
• 您需要一个支持高并发的生产级图数据库——对于大型或复杂的图，SKILL.md 本身建议迁移到 SQLite。

内置全面的预定义类型集合，涵盖主体（Person、Organization）、工作（Project、Task、Goal）、时间与地点（Event、Location）、信息（Document、Message、Note）以及资源（Account、Device、Credential）。每种类型均包含带类型的属性和可选字段，让您无需从零设计 schema 即可对真实世界进行建模。

每次变更在提交之前都会根据 memory/ontology/schema.yaml 中定义的规则进行验证。约束内容包括：必填字段、枚举值、禁止属性（例如在 Credential 上阻止原始密钥）、关系类型/基数规则、无环性检查，以及时间合理性检查（如 Event 上的 end >= start）。

图以仅追加的 memory/ontology/graph.jsonl 文件形式存储——每次创建、更新和关联操作都会新增一行，完整保留历史记录。对于复杂图，SKILL.md 建议迁移到 SQLite，同时保持相同的接口。

scripts/ontology.py CLI 提供了涵盖所有核心操作的命令：create、query、get、related、relate、validate 以及 schema-append。这使得无需编写自定义图代码，即可在任意 shell 步骤或代理操作中以脚本方式调用这些功能。

技能可以在其自身的 SKILL.md 中声明一个 ontology 契约，指定其 reads（读取）和 writes（写入）的类型，以及前置条件与后置条件。这使得技能间的数据依赖关系变得明确且可审计，从而将 ontology 转化为各能力之间的类型化消息总线。

多步骤规划可以建模为图操作的有序序列（CREATE → RELATE → CREATE……）。每个步骤在执行前都会经过验证，一旦发生约束冲突，整个规划可以回滚，从而为智能体提供一个结构化、可检查的规划层。

Agent 在首次提及时创建 Person 和 Project 实体，然后通过 has_owner 或 has_member 关系将它们相互关联。在后续对话轮次中，查询"我对 Alice 了解哪些？"会遍历知识图谱，呈现所有相关的项目、任务和事件，而无需依赖对话历史记录。

一个电子邮件读取技能从消息中提取承诺事项，并将 Commitment 实体写入 ontology。一个独立的任务管理技能定期查询待处理的 Commitment 对象，并自动创建关联的 Task 实体——两个技能之间无需直接耦合。

一个规划智能体将项目建模为一组带有 blocks 关系的 Task 实体。无环约束可防止循环依赖被提交，而 related 查询能即时显示在某项任务开始之前必须完成的所有前置内容。

在执行复杂工作流（例如"安排团队会议并分配后续任务"）之前，智能体将每个步骤转换为经过验证的图操作。如果任何步骤违反约束条件，整个序列将回滚，并通过 Action 类型日志提供安全且可检查的执行记录。