ontology-kg

name	ontology-kg
description	Typed knowledge graph for AI agent memory. Create entities, link relations, enforce constraints. JSONL append-only storage, zero dependencies. Use when agent needs structured memory beyond flat files.

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

• Credential cannot store secrets directly (must use secret_ref)
• blocks relation is acyclic (no circular dependencies)
• Event.end >= Event.start
• Task requires title + 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, constraints
• references/queries.md — Query patterns, traversal examples, aggregations

Credits

Inspired by oswalpalash/ontology. Optimized for practical agent use with streamlined schema and better defaults.