claude-memory-layer 1.0.31 → 1.0.33

package/specs/entity-edge-model/context.md

@@ -1,401 +0,0 @@
-# Entity-Edge Model Context
-
-> **Version**: 1.0.0
-> **Created**: 2026-01-31
-
-## 1. 배경
-
-### 1.1 그래프 기반 지식 표현의 필요성
-
-지식 시스템에서 관계(relationship)는 노드만큼 중요합니다:
-
-- **Fact A**가 **Task B**의 증거가 된다
-- **Task C**가 **Condition D**에 의해 blocked 되어있다
-- **Entry E**가 **Entry F**를 대체(supersede)한다
-
-이런 관계를 JSON 내부에 저장하면:
-1. 쿼리가 복잡해짐 (JSON 파싱 필요)
-2. 일관성 보장 어려움 (양방향 관계)
-3. 성능 저하 (인덱스 활용 불가)
-
-### 1.2 Property Graph 모델
-
-```
-(Entry)-[:EVIDENCE_OF]->(Entity)
-(Entity)-[:BLOCKED_BY]->(Entity)
-(Entry)-[:DERIVED_FROM]->(Entry)
-```
-
-**장점**:
-- 관계가 1급 시민 (first-class citizen)
-- 인덱스를 통한 빠른 탐색
-- 복잡한 경로 쿼리 가능 (e.g., 증거 체인)
-
-## 2. Memo.txt 참고 사항
-
-### 2.1 스키마 분리 (섹션 4)
-
-> **entries / entities / edges 분리**
-> - entries: 불변 기록
-> - entities: 상태 변화 개체
-> - edges: 관계 그래프
-
-### 2.2 edges 테이블 (섹션 4.3)
-
-```sql
-CREATE TABLE edges (
-  edge_id     VARCHAR PRIMARY KEY,
-  src_type    VARCHAR NOT NULL,  -- entry|entity
-  src_id      VARCHAR NOT NULL,
-  rel_type    VARCHAR NOT NULL,  -- evidence_of|blocked_by|...
-  dst_type    VARCHAR NOT NULL,
-  dst_id      VARCHAR NOT NULL,
-  meta_json   JSON,
-  created_at  TIMESTAMP DEFAULT CURRENT_TIMESTAMP
-);
-```
-
-### 2.3 관계 타입
-
-**Entity ↔ Entity**:
-- `blocked_by`: 확정된 blocker
-- `blocked_by_suggested`: 제안된 blocker (미확정)
-- `resolves_to`: Condition이 실제 Entity로 해결
-
-**Entry ↔ Entity**:
-- `evidence_of`: Entry가 Entity의 증거
-
-### 2.4 Effective Blockers (섹션 9.1)
-
-> **v_task_blockers_effective 뷰**:
-> blocked_by edge의 대상이 condition이고 resolves_to가 있으면
-> effective blocker를 resolved_to로 펼쳐서 반환
-
-## 3. Idris2 영감 적용
-
-### 3.1 Dependent Types로 관계 제약
-
-**Idris2 개념**:
-```idris
--- 타입 수준에서 유효한 관계만 허용
-data Edge : NodeType -> RelationType -> NodeType -> Type where
-  EvidenceOf : (src : Entry) -> (dst : Entity) -> Edge Entry EvidenceOf Entity
-  BlockedBy  : (src : Task) -> (dst : Entity) -> Edge Entity BlockedBy Entity
-```
-
-**TypeScript 적용**:
-```typescript
-// Discriminated Union으로 유효 조합 정의
-type ValidEdge =
-  | { srcType: 'entry'; relType: 'evidence_of'; dstType: 'entity' }
-  | { srcType: 'entity'; relType: 'blocked_by'; dstType: 'entity' }
-  | { srcType: 'entity'; relType: 'resolves_to'; dstType: 'entity' };
-
-// 타입 가드
-function isValidEdge(edge: EdgeInput): edge is ValidEdge {
-  const patterns: ValidEdge[] = [ ... ];
-  return patterns.some(p =>
-    p.srcType === edge.srcType &&
-    p.relType === edge.relType &&
-    p.dstType === edge.dstType
-  );
-}
-```
-
-### 3.2 관계 불변식
-
-```typescript
-// 불변식: blocked_by edge가 있으면 Task는 blocked 상태여야 함
-const BlockedByInvariant = z.object({
-  task: z.object({
-    status: z.literal('blocked')
-  }),
-  edges: z.array(z.object({
-    relType: z.literal('blocked_by')
-  })).min(1)  // 최소 1개의 blocker
-});
-
-// 불변식: done 상태면 blocked_by edge가 없어야 함
-const DoneInvariant = z.object({
-  task: z.object({
-    status: z.literal('done')
-  }),
-  edges: z.array(z.object({
-    relType: z.literal('blocked_by')
-  })).max(0)  // blocker 없음
-});
-```
-
-### 3.3 양방향 탐색 안전성
-
-```typescript
-// Idris2: 양방향 탐색이 타입 안전
-interface BidirectionalEdge<S, R, D> {
-  from(src: S): Edge<S, R, D>[];
-  to(dst: D): Edge<S, R, D>[];
-
-  // 불변식: from(x).filter(e => e.dst === y) === to(y).filter(e => e.src === x)
-}
-
-// TypeScript: 인덱스로 보장
-// idx_edges_src: (src_id, rel_type)
-// idx_edges_dst: (dst_id, rel_type)
-```
-
-## 4. 기존 코드와의 관계
-
-### 4.1 types.ts
-
-현재 Edge 관련 타입 없음 → 추가 필요:
-
-```typescript
-// 현재
-export const EvidenceSpanSchema = z.object({
-  start: z.number(),
-  end: z.number(),
-  confidence: z.number(),
-  matchType: z.enum(['exact', 'fuzzy', 'none']),
-  ...
-});
-
-// 추가
-export const EdgeSchema = z.object({
-  edgeId: z.string(),
-  srcType: NodeTypeSchema,
-  srcId: z.string(),
-  relType: RelationTypeSchema,
-  dstType: NodeTypeSchema,
-  dstId: z.string(),
-  metaJson: z.record(z.unknown()).optional()
-});
-```
-
-### 4.2 event-store.ts
-
-Edge 생성은 Projector가 담당, EventStore와 직접 연관 없음.
-단, source_of edge를 통해 이벤트와 Entry/Entity 연결 가능:
-
-```typescript
-// 세션 이벤트와 생성된 Entry 연결
-edges.create({
-  srcType: 'event',
-  srcId: sessionIngestedEvent.id,
-  relType: 'source_of',
-  dstType: 'entry',
-  dstId: newEntry.id
-});
-```
-
-### 4.3 matcher.ts
-
-현재 Matcher는 이벤트 매칭용 → Entity 매칭으로 확장 시 edge 활용:
-
-```typescript
-// Entity 검색 시 관계 정보도 반환
-async function findTaskWithRelations(taskId: string): Promise<TaskWithRelations> {
-  const task = await entityRepo.findById(taskId);
-  const blockedByEdges = await edgeRepo.findBySrc(taskId, 'blocked_by');
-  const evidenceEdges = await edgeRepo.findByDst(taskId, 'evidence_of');
-
-  return {
-    ...task,
-    blockers: blockedByEdges.map(e => e.dstId),
-    evidence: evidenceEdges.map(e => e.srcId)
-  };
-}
-```
-
-## 5. 설계 결정 사항
-
-### 5.1 왜 별도 edges 테이블인가?
-
-**대안 1: JSON 내 저장**
-```json
-{
-  "id": "task_1",
-  "blockers": ["cond_a", "task_b"]
-}
-```
-- 단점: 역방향 쿼리 어려움 ("cond_a를 blocker로 가진 Task는?")
-
-**대안 2: 관계형 테이블**
-```sql
-CREATE TABLE task_blockers (
-  task_id VARCHAR,
-  blocker_id VARCHAR
-);
-```
-- 단점: 관계 타입마다 테이블 필요
-
-**선택: 범용 edges 테이블**
-- 장점: 모든 관계를 하나의 패턴으로 처리
-- 장점: 메타데이터 유연하게 저장
-- 장점: 인덱스로 양방향 탐색 최적화
-
-### 5.2 왜 meta_json을 사용하는가?
-
-관계마다 필요한 메타데이터가 다름:
-
-```typescript
-// evidence_of: span, confidence, method
-{ span: { start: 10, end: 50 }, confidence: 0.95, method: 'fuzzy' }
-
-// blocked_by: mode, raw_text
-{ mode: 'suggest', raw_text: '인증 API 완료 필요' }
-
-// resolves_to: resolution_type, resolved_at
-{ resolution_type: 'exact_match', resolved_at: '2026-01-31T10:00:00Z' }
-```
-
-JSON 컬럼으로 유연하게 처리.
-
-### 5.3 중복 방지 전략
-
-**Unique 인덱스**:
-```sql
-CREATE UNIQUE INDEX idx_edges_unique
-ON edges(src_type, src_id, rel_type, dst_type, dst_id);
-```
-
-**INSERT OR IGNORE / ON CONFLICT**:
-```sql
-INSERT INTO edges (...)
-VALUES (...)
-ON CONFLICT (src_type, src_id, rel_type, dst_type, dst_id)
-DO NOTHING;  -- 또는 UPDATE meta_json
-```
-
-## 6. 쿼리 패턴 예시
-
-### 6.1 Task의 모든 관계 조회
-
-```sql
--- Task를 중심으로 한 모든 관계
-SELECT
-  'outgoing' AS direction,
-  e.rel_type,
-  e.dst_type,
-  e.dst_id,
-  e.meta_json
-FROM edges e
-WHERE e.src_type = 'entity' AND e.src_id = :task_id
-
-UNION ALL
-
-SELECT
-  'incoming' AS direction,
-  e.rel_type,
-  e.src_type,
-  e.src_id,
-  e.meta_json
-FROM edges e
-WHERE e.dst_type = 'entity' AND e.dst_id = :task_id;
-```
-
-### 6.2 Blocked Tasks 조회 (blocker 정보 포함)
-
-```sql
-SELECT
-  t.entity_id AS task_id,
-  t.title AS task_title,
-  JSON_GROUP_ARRAY(
-    JSON_OBJECT(
-      'blocker_id', e.dst_id,
-      'blocker_type', ent.entity_type,
-      'blocker_title', ent.title
-    )
-  ) AS blockers
-FROM entities t
-JOIN edges e ON e.src_id = t.entity_id AND e.rel_type = 'blocked_by'
-JOIN entities ent ON ent.entity_id = e.dst_id
-WHERE t.entity_type = 'task'
-  AND JSON_EXTRACT(t.current_json, '$.status') = 'blocked'
-GROUP BY t.entity_id;
-```
-
-### 6.3 증거 체인 탐색 (2-hop)
-
-```sql
--- Entry → Entity → 관련 Entry
-WITH first_hop AS (
-  SELECT
-    e1.src_id AS entry_id,
-    e1.dst_id AS entity_id
-  FROM edges e1
-  WHERE e1.src_type = 'entry'
-    AND e1.rel_type = 'evidence_of'
-    AND e1.src_id = :start_entry_id
-),
-second_hop AS (
-  SELECT
-    f.entry_id AS origin_entry,
-    f.entity_id,
-    e2.src_id AS related_entry_id
-  FROM first_hop f
-  JOIN edges e2 ON e2.dst_id = f.entity_id
-               AND e2.rel_type = 'evidence_of'
-               AND e2.src_type = 'entry'
-  WHERE e2.src_id != f.entry_id  -- 자기 자신 제외
-)
-SELECT * FROM second_hop;
-```
-
-## 7. 성능 고려사항
-
-### 7.1 인덱스 전략
-
-```sql
--- 출발점 기준 탐색 (가장 빈번)
-CREATE INDEX idx_edges_src ON edges(src_id, rel_type);
-
--- 도착점 기준 탐색 (역방향)
-CREATE INDEX idx_edges_dst ON edges(dst_id, rel_type);
-
--- 관계 타입별 통계
-CREATE INDEX idx_edges_rel ON edges(rel_type);
-```
-
-### 7.2 캐싱
-
-```typescript
-// 자주 조회되는 관계 캐싱
-const relationCache = new LRUCache<string, Edge[]>({
-  max: 5000,
-  ttl: 1000 * 60 * 5  // 5분
-});
-
-async function getBlockers(taskId: string): Promise<Edge[]> {
-  const key = `blockers:${taskId}`;
-  if (relationCache.has(key)) {
-    return relationCache.get(key)!;
-  }
-
-  const edges = await edgeRepo.findBySrc(taskId, 'blocked_by');
-  relationCache.set(key, edges);
-  return edges;
-}
-```
-
-### 7.3 배치 처리
-
-```typescript
-// 대량 edge 생성 시 배치 insert
-async function createManyEdges(edges: EdgeInput[]): Promise<void> {
-  const BATCH_SIZE = 1000;
-
-  for (let i = 0; i < edges.length; i += BATCH_SIZE) {
-    const batch = edges.slice(i, i + BATCH_SIZE);
-    await db.transaction(async (tx) => {
-      for (const edge of batch) {
-        await tx.run('INSERT INTO edges ...', [...]);
-      }
-    });
-  }
-}
-```
-
-## 8. 참고 자료
-
-- **Memo.txt**: 섹션 4.3 (edges 테이블), 섹션 9.1 (effective blockers)
-- **Property Graph**: Neo4j, AWS Neptune 모델 참고
-- **AXIOMMIND**: Principle 5 (Task는 Entity)