| name | ontology |
| description | Build a typed knowledge graph and structured agent memory as a relation layer over the LLM wiki. LOAD when the user asks to model entities/relations, track structured facts with types, answer "how is X related to Y", or give the wiki a queryable schema. Not for free-text notes (use llm_wiki) or short-lived task state (use todo). |
| category | agent |
Ontology — 带类型的知识图谱 / 结构化 agent 记忆
给 agent 一个带类型的知识图谱:实体有类型(Person/Paper/Concept/Tool…),
关系是有方向、有类型的边(authored_by/cites/part_of/instance_of…)。
它是 [[llm_wiki]] 的结构化关系层 —— wiki 存自由文本,ontology 存可查询的类型与关系,
两者用 [[wikilink]] 互相指向,让技能可组合。
纯文件约定,零新依赖:全部用现有通用工具(write/read/edit/list_dir/find_files/search_content)
读写 <workspace>/ontology/ 下的 Markdown。不需要也不要引入任何图数据库或本体库。
何时 LOAD / 不 LOAD
| 用 ontology | 用别的 |
|---|
| 建模实体与它们之间的关系("A 引用 B""X 属于 Y") | 纯自由文本笔记 → [[llm_wiki]] |
| 需要类型约束 / schema("只允许这几类实体和关系") | 本轮临时执行清单 → todo |
| 结构化问答:"谁写了 X""X 的上游依赖有哪些""从 A 到 B 有没有路径" | 问用户要什么 → clarify |
| 长期结构化记忆,跨会话可遍历 | 一次性偏好/事实 → memory_add |
与 llm_wiki 的分工:wiki 页面是"文章";ontology 实体是"图里的节点+带类型的边"。
一个概念常常两边都有:wiki 页写它是什么,ontology 实体记它和别的节点的类型化关系,
并在 wiki: 字段用 [[slug]] 指回 wiki。
存储布局(<workspace>/ontology/)
ontology/
schema.md # TBox:允许的实体类型 + 关系类型(含 domain/range/inverse)
entities/<slug>.md # ABox:每个实体一个文件,frontmatter 存类型/属性/关系
- slug 规则:小写、非字母数字转
-、首尾去 -(与 llm_wiki slugify 一致),
这样 ontology 实体的 slug 能直接对上同名 wiki 页的 slug。
- 所有读写走通用文件工具;不要用
wiki_write 存实体 —— 它只保留固定 frontmatter 字段,
会丢弃 type/relations 等自定义键。
schema.md 格式
---
entity_types:
Person: { description: "人:作者/研究者/用户" }
Paper: { description: "论文或技术报告" }
Concept: { description: "抽象概念/方法/架构" }
Tool: { description: "软件/库/CLI/agent 工具" }
relation_types:
authored_by: { domain: [Paper], range: [Person], inverse: authored }
cites: { domain: [Paper], range: [Paper], inverse: cited_by }
instance_of: { domain: ["*"], range: [Concept], inverse: has_instance }
part_of: { domain: ["*"], range: ["*"], inverse: has_part }
depends_on: { domain: [Tool], range: [Tool], inverse: dependency_of }
---
# Schema
本体的类型定义。新增类型前先读这里;需要新类型就在此登记(附一句 description),
保持 schema 与实体一致。`domain`/`range` 用 `"*"` 表示不限类型。
entities/<slug>.md 格式
---
id: rotary-positional-embeddings
type: Concept
labels: [RoPE, Rotary Positional Embeddings] # 别名,便于检索
wiki: "[[rotary-positional-embeddings]]" # 指回 llm_wiki 同名页(可空)
attributes:
year: 2021
relations:
- { predicate: instance_of, target: positional-encoding }
- { predicate: cited_by, target: roformer-paper }
created: 2026-07-13T00:00:00Z
updated: 2026-07-13T00:00:00Z
---
# Rotary Positional Embeddings
一句话说明这个节点是什么(详情放 wiki 页,这里只放图谱需要的结构)。
约定:
relations 只存出边;查入边(反向)靠遍历所有实体(见下)。登记正向边时,
优先用 schema 里定义了 inverse 的谓词,保证图是可双向遍历的。target 用目标实体的 slug(不是标题)。目标实体可以先不存在(悬空边),
就像 wiki 的 broken link —— 是"接下来该建的节点"的信号。- 时间戳用 ISO-8601 UTC。
操作配方
所有操作 = 读/写 ontology/ 下文件 + 维护一致性。开始一句、结束给摘要,中间静默。
1. 建/改实体 (assert)
read ontology/schema.md(不存在就先按上面的模板 write 一个基础 schema)。- 校验实体
type 与每条关系的 predicate 都在 schema 里;缺就先补 schema。
- 校验每条关系的
domain/range 与两端实体类型相符,不符则报告并让用户确认。
read entities/<slug>.md:存在则 edit(保留 created,更新 updated),
不存在则 write(created=updated=now)。- 对有
inverse 的谓词,在目标实体文件里补一条反向边(目标不存在时可跳过,留作悬空)。
2. 查实体 / 邻居 (get)
read entities/<slug>.md 拿类型、属性、出边。- 入边(反向):
search_content 在 ontology/entities/ 里搜 target: <slug>,
或 list_dir 后逐个 read,收集所有指向它的边。
- 需要文本细节时,顺着
wiki: 的 [[slug]] 用 wiki_read 取 wiki 正文。
3. 关系查询 / 找路径 (query)
- "谁 authored X" →
read X 的实体,看 authored_by。
- "X 依赖什么" → 出边里
depends_on 的 target。
- "A 到 B 有没有路径" → 从 A 出边做广度优先:逐跳
read target 实体、
展开其出边,直到命中 B 或用尽(设跳数上限 ~4,并记已访问 slug 防环)。
- 结果按
{起点, 边序列, 终点} 汇报,并列出沿途悬空/缺失的目标。
4. 校验 (validate)
list_dir entities/ → 逐个 read:
- 每个
type 在 schema? 每个 predicate 在 schema?
- 每条边
target 对应的实体文件是否存在(悬空边 = 建议下一步补的节点)?
- 有
inverse 的边,反向边是否也在目标里(缺就补)?
- 汇报:未知类型/谓词、悬空边、缺失的反向边。
5. 删实体 (retract)
- 先
search_content 找出所有指向它的入边,delete 前告知用户这些会变悬空。
- 删实体文件;按用户意愿清理或保留对端的反向边。
与其他技能组合(可组合性)
- [[llm_wiki]]:wiki = 文本层,ontology = 关系层。写 wiki 页后,若它和别的节点有类型化关系,
就在 ontology 建对应实体并用
wiki: 回指。用户问"关系/路径/类型"走 ontology,问"细节/解释"走 wiki。
memory_add / memory_search:一次性偏好或事实进 memory;需要类型与结构化关系时进 ontology。clarify:类型/关系有歧义(该建哪类实体、用哪个谓词)时先问,别乱建 schema。todo:批量导入或大范围重构图谱时,用 todo 跟踪进度。
原则
- schema 先行、保持一致:先看/补
schema.md,再断言实体;类型和谓词都要有登记。
- slug 对齐 llm_wiki:同一概念两边同 slug,
[[wikilink]] 才互通。
- 悬空边是特性不是错误:等于 wiki 的 broken link,标记"下一个该建的节点"。
- 零依赖:只用现有文件工具读写 Markdown,永远不要为此加图数据库/本体库依赖。
- 静默维护:建/改多文件时别逐步播报,开头一句、结尾给结构化摘要。
