Ontology KG — 给你的 AI 一个结构化大脑
Story
你的 AI agent 记住了 200 条信息，全塞在一个 MEMORY.md 里。找东西靠 grep，关系靠脑补。
"Alice 负责哪个项目？" —— grep Alice，翻 10 条记录，猜。
"什么任务 block 了发布？" —— 没法回答，因为依赖关系没存。
"上次会议谁参加了？" —— 运气好能找到，运气不好淹在 200 行里。
问题不是记忆太少，是记忆没有结构。
Ontology KG 给 agent 的记忆加上类型、关系和约束。Person 有 name，Task 有 status 和 blocker，Project 有 owner。entity 之间用 relation 连接，约束自动校验。
存储是 JSONL append-only 文件，零依赖，git 友好。
Core Concept
CODEBLOCK0
Types
| Category | Types |
|---|
| People | Person, Organization |
| Work |
Project, Task, Goal |
| Time | Event, Location |
| Info | Document, Message, Note |
| Resources | Account, Device, Credential |
| Meta | Action, Policy |
Quick Start
CODEBLOCK1
Storage Format (JSONL)
CODEBLOCK2
Append-only. Git-friendly. Migrate to SQLite for big graphs.
Key Constraints
- -
Credential cannot store secrets directly (must use secret_ref) - INLINECODE2 relation is acyclic (no circular dependencies)
- INLINECODE3
- INLINECODE4 requires
title + INLINECODE6
When to Use
| Trigger | Action |
|---|
| "Remember that..." | Create/update entity |
| "What do I know about X?" |
Query graph |
| "Link X to Y" | Create relation |
| "What depends on X?" | Traverse dependencies |
| "Show project status" | Aggregate by relations |
| Skills need shared state | Read/write entities |
References
- -
references/schema.md — Full type definitions, relation types, constraints - INLINECODE8 — Query patterns, traversal examples, aggregations
Credits
Inspired by oswalpalash/ontology. Optimized for practical agent use with streamlined schema and better defaults.
Ontology KG — 给你的 AI 一个结构化大脑
故事
你的 AI agent 记住了 200 条信息，全塞在一个 MEMORY.md 里。找东西靠 grep，关系靠脑补。
Alice 负责哪个项目？ —— grep Alice，翻 10 条记录，猜。
什么任务阻塞了发布？ —— 没法回答，因为依赖关系没存。
上次会议谁参加了？ —— 运气好能找到，运气不好淹在 200 行里。
问题不是记忆太少，而是记忆没有结构。
Ontology KG 给 agent 的记忆加上类型、关系和约束。Person 有 name，Task 有 status 和 blocker，Project 有 owner。实体之间用关系连接，约束自动校验。
存储是 JSONL 追加写入文件，零依赖，git 友好。
核心概念
Entity = { id, type, properties }
Relation = { from → rel_type → to }
Constraint = { type rules, relation rules, acyclic checks }
类型
| 类别 | 类型 |
|---|
| 人员 | Person, Organization |
| 工作 |
Project, Task, Goal |
| 时间 | Event, Location |
| 信息 | Document, Message, Note |
| 资源 | Account, Device, Credential |
| 元数据 | Action, Policy |
快速开始
bash
初始化存储
mkdir -p memory/ontology
touch memory/ontology/graph.jsonl
创建实体
python3 scripts/ontology.py create --type Person --props {name:Alice}
python3 scripts/ontology.py create --type Project --props {name:Website,status:active}
关联它们
python3 scripts/ontology.py relate --from proj
001 --rel hasowner --to p_001
查询
python3 scripts/ontology.py query --type Task --where {status:open}
python3 scripts/ontology.py related --id proj
001 --rel hastask
验证所有约束
python3 scripts/ontology.py validate
存储格式 (JSONL)
jsonl
{op:create,entity:{id:p_001,type:Person,properties:{name:Alice}}}
{op:relate,from:proj001,rel:hasowner,to:p_001}
追加写入。Git 友好。大型图可迁移至 SQLite。
关键约束
- - Credential 不能直接存储密钥（必须使用 secret_ref）
- blocks 关系无环（无循环依赖）
- Event.end >= Event.start
- Task 需要 title + status
使用场景
| 触发条件 | 操作 |
|---|
| 记住... | 创建/更新实体 |
| 关于 X 我知道什么？ |
查询图 |
| 将 X 链接到 Y | 创建关系 |
| X 依赖什么？ | 遍历依赖 |
| 显示项目状态 | 按关系聚合 |
| 技能需要共享状态 | 读写实体 |
参考
- - references/schema.md — 完整类型定义、关系类型、约束
- references/queries.md — 查询模式、遍历示例、聚合
致谢
灵感来源于 oswalpalash/ontology。针对实际 agent 使用进行了优化，简化了模式并提供了更好的默认值。
