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
Entity = { id, type, properties }
Relation = { from → rel_type → to }
Constraint = { type rules, relation rules, acyclic checks }
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
# Init storage
mkdir -p memory/ontology
touch memory/ontology/graph.jsonl
# Create entities
python3 scripts/ontology.py create --type Person --props '{"name":"Alice"}'
python3 scripts/ontology.py create --type Project --props '{"name":"Website","status":"active"}'
# Link them
python3 scripts/ontology.py relate --from proj_001 --rel has_owner --to p_001
# Query
python3 scripts/ontology.py query --type Task --where '{"status":"open"}'
python3 scripts/ontology.py related --id proj_001 --rel has_task
# Validate all constraints
python3 scripts/ontology.py validate
Storage Format (JSONL)
{"op":"create","entity":{"id":"p_001","type":"Person","properties":{"name":"Alice"}}}
{"op":"relate","from":"proj_001","rel":"has_owner","to":"p_001"}
Append-only. Git-friendly. Migrate to SQLite for big graphs.
Key Constraints
Credentialcannot store secrets directly (must usesecret_ref)blocksrelation is acyclic (no circular dependencies)Event.end >= Event.startTaskrequirestitle+status
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, constraintsreferences/queries.md— Query patterns, traversal examples, aggregations
Credits
Inspired by oswalpalash/ontology. Optimized for practical agent use with streamlined schema and better defaults.
