ontology

• 에이전트가 세션 전반에 걸쳐 구조화된 정보를 기억하길 원할 때 (예: "Alice가 프로젝트 X를 소유하고 있다는 것을 기억해").
• 관련 객체를 연결하고 나중에 해당 링크를 탐색해야 할 때 (예: "프로젝트 Z의 모든 태스크 보여줘", "X에 의존하는 것은 무엇인가?").
• 여러 스킬이 원시 텍스트를 주고받지 않고 상태를 공유해야 할 때 — 한 스킬은 Commitment를 작성하고, 다른 스킬은 이를 Task로 읽음.
• 다단계 작업을 계획하고 있으며, 각 단계를 제약 위반 시 롤백이 가능한 검증된 그래프 변환으로 모델링하고 싶을 때.

• 에이전트 실행 간 지속성이 필요 없고 일시적인 단일 턴 컨텍스트만 필요한 경우.
• 데이터가 순전히 비정형(자유 형식 산문)이며 모델링할 의미 있는 엔티티 관계가 없는 경우.
• 높은 동시성을 갖춘 프로덕션 수준의 그래프 데이터베이스가 필요한 경우 — 크거나 복잡한 그래프의 경우, SKILL.md 자체에서 SQLite로 마이그레이션할 것을 권장합니다.

에이전트(Person, Organization), 작업(Project, Task, Goal), 시간 및 장소(Event, Location), 정보(Document, Message, Note), 리소스(Account, Device, Credential)를 포함하는 포괄적인 사전 정의 타입 세트를 기본으로 제공합니다. 각 타입은 타입이 지정된 속성과 선택적 필드를 포함하고 있어, 스키마를 처음부터 직접 설계하지 않고도 실제 세계를 그대로 모델링할 수 있습니다.

모든 변형(mutation)은 커밋되기 전에 memory/ontology/schema.yaml에 정의된 규칙에 따라 검증됩니다. 제약 조건에는 필수 필드, 열거형(enum) 값, 금지된 속성(예: Credential에서 원시 시크릿 차단), 관계 유형/카디널리티 규칙, 비순환성 검사, 그리고 Event의 end >= start와 같은 시간적 유효성 검사가 포함됩니다.

그래프는 추가 전용 memory/ontology/graph.jsonl 파일로 저장됩니다 — 모든 생성, 업데이트, 연결 작업이 새 줄로 추가되어 전체 기록이 보존됩니다. 복잡한 그래프의 경우 SKILL.md는 동일한 인터페이스를 유지하면서 SQLite로 마이그레이션할 것을 권장합니다.

scripts/ontology.py CLI는 모든 핵심 작업에 대한 명령어를 제공합니다: create, query, get, related, relate, validate, schema-append. 이를 통해 커스텀 그래프 코드를 작성하지 않고도 셸 스텝이나 에이전트 액션에서 스크립트로 실행할 수 있습니다.

스킬은 자체 SKILL.md에 ontology 계약을 선언하여 reads(읽기) 및 writes(쓰기) 타입과 사전/사후 조건을 명시할 수 있습니다. 이를 통해 스킬 간 데이터 의존성이 명시적으로 드러나고 감사 가능해지며, ontology는 각 기능(capability) 사이의 타입이 지정된 메시지 버스로 기능하게 됩니다.

다단계 계획은 그래프 연산의 순서 있는 시퀀스(CREATE → RELATE → CREATE …)로 모델링할 수 있습니다. 각 단계는 실행 전에 검증되며, 제약 조건 위반 시 전체 계획을 롤백할 수 있어 에이전트에게 구조화되고 검사 가능한 계획 레이어를 제공합니다.

에이전트는 Person 및 Project 엔티티가 처음 언급될 때 생성하고, has_owner 또는 has_member 관계로 연결합니다. 이후 대화에서 "Alice에 대해 무엇을 알고 있나요?"라고 쿼리하면, 대화 기록에 의존하지 않고 그래프를 탐색하여 관련된 모든 프로젝트, 작업 및 이벤트를 표시합니다.

이메일 읽기 스킬은 메시지에서 약속 사항을 추출하여 Commitment 엔티티를 ontology에 기록합니다. 별도의 작업 관리 스킬은 주기적으로 보류 중인 Commitment 객체를 조회하고 연결된 Task 엔티티를 자동으로 생성합니다 — 두 스킬 간의 직접적인 결합은 필요하지 않습니다.

계획 에이전트는 프로젝트를 blocks 관계를 가진 Task 엔티티의 집합으로 모델링합니다. 비순환성 제약 조건은 순환 의존성이 커밋되는 것을 방지하며, related 쿼리는 특정 작업이 시작되기 전에 완료되어야 하는 항목을 즉시 보여줍니다.

복잡한 워크플로우(예: "팀 회의 일정 잡고 후속 작업 할당")를 실행하기 전에, 에이전트는 각 단계를 검증된 그래프 작업으로 변환합니다. 어느 단계라도 제약 조건을 위반하면 전체 시퀀스가 롤백되며, Action 타입 로그를 통해 안전하고 검사 가능한 실행 추적 기록을 제공합니다.