03-relationships-explicit

Dec 7, 2025

Explicit Relationships

📁 관련 코드: lib/types/relationships/explicit.ts

LLM이 추출하는 관계입니다. 이메일 내용의 의미 분석을 통해 도출됩니다.

핵심 개념

이메일: "김철수님이 ABC회사 프로젝트 보고서를 내일까지 제출해달라고 했습니다"

LLM 추출:
┌─────────────────────────────────────────────────────────┐
│ [Memory] ──MENTIONS──→ [Person: 김철수]                 │
│          ──MENTIONS──→ [Entity: ABC회사]                │
│          ──CREATES───→ [Task: 보고서 제출]              │
└─────────────────────────────────────────────────────────┘

Implicit vs Explicit (복습)

	Implicit	Explicit
기반	구조적 속성	의미적 분석
생성	자동	LLM
예시	same_thread	mentions

ExplicitRelationType

enum ExplicitRelationType {
  // 구조적 관계
  IS_PART_OF = 'is_part_of',
  BELONGS_TO = 'belongs_to',

  // 참조 관계
  MENTIONS = 'mentions',
  REFERS_TO = 'refers_to',
  FOLLOWS_UP = 'follows_up',

  // 변경 관계
  UPDATES = 'updates',
  CONTRADICTS = 'contradicts',

  // 사람-관련 관계
  ASSIGNED_TO = 'assigned_to',
  INVOLVES = 'involves',
  WORKS_AT = 'works_at',

  // 엔티티 관계
  PRODUCES = 'produces',
}

관계별 상세 설명

MENTIONS

[Memory] ──MENTIONS──→ [Entity/Person]

의미: 메모리가 특정 엔티티나 사람을 언급함 예시: "ABC회사와 계약 체결" → Memory MENTIONS ABC회사

const rel = createMentionsRelation(
  memory.id,
  entity.id,
  NodeType.ENTITY,
  0.95,  // confidence
  "ABC회사와 계약"  // evidence
);

UPDATES

[Memory v2] ──UPDATES──→ [Memory v1]

의미: 새 메모리가 기존 메모리의 정보를 갱신 예시: "미팅 3시로 변경" → 새 Memory UPDATES 이전 Memory

// 미팅 시간 변경 감지 시
const rel = createUpdatesRelation(
  newMemory.id,
  oldMemory.id,
  0.9,
  "3시로 변경"
);

CONTRADICTS

[Memory A] ──CONTRADICTS──→ [Memory B]

의미: 두 메모리가 상충되는 정보를 포함 예시: "예산 500만원" vs "예산 300만원"

왜 중요한가? → 충돌 해결 시스템에서 사용자에게 알림

ASSIGNED_TO

[Task] ──ASSIGNED_TO──→ [Person]

의미: 태스크가 특정 사람에게 할당됨

const rel = createAssignedToRelation(
  task.id,
  person.id,
  0.95
);

WORKS_AT

[Person] ──WORKS_AT──→ [Entity: Company]

의미: 사람이 특정 회사에서 근무 추출 예시: "ABC회사 김철수입니다" → 김철수 WORKS_AT ABC회사

PRODUCES

[Entity: Company] ──PRODUCES──→ [Entity: Product]

의미: 회사가 제품/서비스를 생산 예시: "Apple의 iPhone" → Apple PRODUCES iPhone

타입 검증

VALID_RELATIONSHIP_TYPES

const VALID_RELATIONSHIP_TYPES = {
  [ExplicitRelationType.MENTIONS]: [
    { source: NodeType.MEMORY, target: NodeType.ENTITY },
    { source: NodeType.MEMORY, target: NodeType.PERSON },
  ],
  [ExplicitRelationType.ASSIGNED_TO]: [
    { source: NodeType.TASK, target: NodeType.PERSON },
  ],
  // ...
};

검증 함수

isValidRelationship(
  ExplicitRelationType.ASSIGNED_TO,
  NodeType.TASK,    // ✅ 유효
  NodeType.PERSON
);

isValidRelationship(
  ExplicitRelationType.ASSIGNED_TO,
  NodeType.MEMORY,  // ❌ 유효하지 않음
  NodeType.PERSON
);

왜 검증이 필요한가?

문제: LLM이 잘못된 관계를 추출할 수 있음

"김철수가 ABC회사를 언급했다"
→ LLM이 실수로 Person MENTIONS Entity 생성 (잘못됨)
→ 올바른 것: Memory MENTIONS Entity

해결: createExplicitRelationship에서 자동 검증

createExplicitRelationship({
  type: ExplicitRelationType.MENTIONS,
  sourceType: NodeType.PERSON,  // ❌ Error 발생!
  targetType: NodeType.ENTITY,
  // ...
});

Confidence (신뢰도)

confidence: number;  // 0-1

LLM 추출 신뢰도

신뢰도	의미	조치
0.9+	확실함	바로 저장
0.7-0.9	높음	저장, 나중에 검증
0.5-0.7	불확실	저장, 사용자 확인 필요
0.5 미만	낮음	저장하지 않음

프롬프트 예시

이메일에서 다음 관계를 추출하세요:
- 언급된 사람, 회사, 제품
- 각 관계의 신뢰도 (0-1)

예시:
{
  "relations": [
    {
      "type": "mentions",
      "target": "ABC회사",
      "targetType": "entity",
      "confidence": 0.95,
      "evidence": "ABC회사와의 계약"
    }
  ]
}

Evidence (근거)

evidence?: string;  // 추출 근거 텍스트

왜 저장하는가?

디버깅: "왜 이 관계가 추출됐지?" 검증: 사용자가 관계 정확성 확인 학습: 추출 품질 개선용 데이터

{
  type: ExplicitRelationType.MENTIONS,
  sourceId: memory.id,
  targetId: entity.id,
  confidence: 0.92,
  evidence: "ABC회사 김철수 부장님과 미팅 예정"
  //         ^^^^^^^^^ 이 부분이 근거
}

그래프 구조 예시

                    ┌─────────────────┐
                    │  Thread: 계약   │
                    └────────┬────────┘
                             │ BELONGS_TO
                             ▼
┌──────────────┐    ┌─────────────────┐    ┌──────────────┐
│ Person: 김철수 │◄───│ Memory: 계약체결 │───►│ Entity: ABC  │
└──────────────┘    └────────┬────────┘    └──────────────┘
       │  INVOLVES            │ CREATES           │ MENTIONS
       │                      ▼                   │
       │           ┌─────────────────┐            │
       └──────────►│ Task: 서명      │            │
         ASSIGNED  └─────────────────┘            │
                                                  │
                                          ┌───────▼───────┐
                                          │Product: X-Pro │
                                          └───────────────┘
                                               PRODUCES

Factory Functions 사용

createMentionsRelation

// Memory가 Entity를 언급
const rel = createMentionsRelation(
  memory.id,
  entity.id,
  NodeType.ENTITY,
  0.95,
  "ABC회사와 계약 체결"
);

createAssignedToRelation

// Task가 Person에게 할당
const rel = createAssignedToRelation(
  task.id,
  person.id,
  0.9
);

createUpdatesRelation

// 새 Memory가 이전 Memory를 업데이트
const rel = createUpdatesRelation(
  newMemory.id,
  oldMemory.id,
  0.85,
  "시간 변경됨"
);

다음 문서

→ Importance Scoring: 중요도 점수
→ Conflict Resolution: 충돌 해결

‹

›