ontology

• 您希望代理人在多個工作階段之間記住結構化資訊（例如：「記住 Alice 擁有 Project X」）。
• 您需要連結相關物件並在之後遍歷這些連結（例如：「顯示 Project Z 的所有任務」、「哪些項目依賴 X？」）。
• 多個技能需要共享狀態而不傳遞純文字——一個技能寫入 Commitment，另一個技能將其讀取為 Task。
• 您正在規劃多步驟工作，並希望將每個步驟建模為經過驗證的圖形轉換，在違反約束條件時可進行回滾。

• 您只需要短暫的、單次的上下文，且無需在代理執行之間保留持久性。
• 您的資料純粹是非結構化的（自由格式文字），沒有任何有意義的實體關係需要建模。
• 您需要一個具備高並發能力的生產級圖形資料庫——對於大型或複雜的圖形，ontology 的 SKILL.md 本身建議遷移至 SQLite。

內建一套完整的預定義類型，涵蓋代理人（Person、Organization）、工作（Project、Task、Goal）、時間與地點（Event、Location）、資訊（Document、Message、Note）以及資源（Account、Device、Credential）。每種類型均附帶具有型別的屬性與選填欄位，讓您無需從頭設計結構描述，即可對真實世界進行建模。

每次變更在提交前都會根據 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 …）。每個步驟在執行前都會經過驗證，且整個計畫可在違反約束條件時進行回滾，為代理人提供一個結構化、可檢視的規劃層。

代理人在第一次提及 Person（人員）和 Project（專案）實體時便會建立對應節點，並透過 has_owner 或 has_member 關聯將它們連結起來。在後續對話輪次中，查詢「我對 Alice 了解哪些？」時，系統會遍歷知識圖譜，將所有相關的專案、任務與事件一併呈現，而無需依賴對話歷史紀錄。

一個電子郵件讀取技能從訊息中擷取承諾事項，並將 Commitment 實體寫入 ontology。另一個獨立的任務管理技能定期查詢待處理的 Commitment 物件，並自動建立關聯的 Task 實體——兩個技能之間無需直接耦合。

一個規劃代理程式將專案建模為一組帶有 blocks 關係的 Task 實體。非循環約束可防止循環依賴被提交，而 related 查詢則能即時顯示在特定任務開始之前必須完成哪些工作。

在執行複雜的工作流程之前（例如「安排團隊會議並指派後續任務」），代理程式會將每個步驟轉換為經過驗證的圖形操作。若任何步驟違反約束條件，整個序列將會回滾，並透過 Action 類型日誌提供安全且可檢視的執行軌跡。