memento-mcp-server 1.11.1 → 1.12.0-a

package/dist/services/relation-graph.d.ts

@@ -0,0 +1,275 @@
+/**
+ * 관계 그래프 서비스
+ * 기억 간의 관계를 저장하고 관리하는 서비스
+ *
+ * 주요 기능:
+ * - 관계 추가/삭제/조회
+ * - 순환 참조 감지 (DFS)
+ * - N-hop 관계 탐색 (BFS)
+ * - 신뢰도 갱신
+ * - 캐싱 계층 (L1: MemoryCache 10분, L2: PersistentCache 7일)
+ * - 배치 삽입 최적화
+ */
+import Database from 'better-sqlite3';
+import type { MemoryRelation, RelationMetadata, GetRelationsOptions, GetRelatedMemoriesOptions, AddRelationOptions, IRelationGraph } from '../types/relation-graph.js';
+import type { RelationType } from '../types/relation.js';
+/**
+ * 관계 그래프 서비스
+ */
+export declare class RelationGraph implements IRelationGraph {
+    private db;
+    private l1Cache;
+    private l2Cache;
+    private cacheKeyIndex;
+    constructor(db: Database.Database);
+    /**
+     * 관계 추가
+     * UNIQUE 제약 검증 및 순환 참조 감지를 수행합니다.
+     *
+     * 트랜잭션 내에서 실행하여 순환 참조 감지와 관계 추가를 원자적으로 처리합니다.
+     * 이를 통해 경쟁 조건을 방지하고 일관성을 보장합니다.
+     *
+     * @param sourceId 소스 기억 ID
+     * @param targetId 타겟 기억 ID
+     * @param relationType 관계 유형
+     * @param options 추가 옵션
+     * @returns 추가된 관계 ID
+     */
+    addRelation(sourceId: string, targetId: string, relationType: RelationType, options?: AddRelationOptions): Promise<number>;
+    /**
+     * 관계 추가 내부 로직
+     * 기존 관계 확인 및 새 관계 추가를 수행합니다.
+     *
+     * @param sourceId 소스 기억 ID
+     * @param targetId 타겟 기억 ID
+     * @param relationType 관계 유형
+     * @param confidence 신뢰도
+     * @param metadata 메타데이터
+     * @param metadataJson 메타데이터 JSON 문자열
+     * @param updateOnConflict 충돌 시 업데이트 여부
+     * @param allowCyclic 순환 참조 허용 여부
+     * @returns 관계 ID
+     */
+    private addRelationInternal;
+    /**
+     * 관계 추가 에러 처리
+     * 동시성 문제로 인한 UNIQUE constraint 에러를 처리합니다.
+     *
+     * @param error 발생한 에러
+     * @param sourceId 소스 기억 ID
+     * @param targetId 타겟 기억 ID
+     * @param relationType 관계 유형
+     * @param confidence 신뢰도
+     * @param metadata 메타데이터
+     * @param updateOnConflict 충돌 시 업데이트 여부
+     * @returns 관계 ID 또는 에러를 throw
+     */
+    private handleRelationAddError;
+    /**
+     * 관계 입력 검증
+     *
+     * @param sourceId 소스 기억 ID
+     * @param targetId 타겟 기억 ID
+     */
+    private validateRelationInput;
+    /**
+     * 순환 참조 확인
+     * 트랜잭션 내에서 호출되는 경우 중첩 트랜잭션을 방지하기 위해
+     * 트랜잭션 상태를 확인합니다.
+     *
+     * @param sourceId 소스 기억 ID
+     * @param targetId 타겟 기억 ID
+     * @param relationType 관계 유형
+     */
+    private checkForCyclicRelation;
+    /**
+     * 메타데이터 준비
+     *
+     * @param options 추가 옵션
+     * @param allowCyclic 순환 참조 허용 여부
+     * @returns 준비된 메타데이터
+     */
+    private prepareMetadata;
+    /**
+     * 기존 관계 조회
+     *
+     * @param sourceId 소스 기억 ID
+     * @param targetId 타겟 기억 ID
+     * @param relationType 관계 유형
+     * @returns 기존 관계 정보 또는 null
+     */
+    private findExistingRelation;
+    /**
+     * 기존 관계 처리
+     *
+     * @param existing 기존 관계 정보
+     * @param sourceId 소스 기억 ID
+     * @param targetId 타겟 기억 ID
+     * @param relationType 관계 유형
+     * @param confidence 신뢰도
+     * @param metadata 메타데이터
+     * @param updateOnConflict 충돌 시 업데이트 여부
+     * @returns 관계 ID
+     */
+    private handleExistingRelation;
+    /**
+     * 새 관계 추가
+     *
+     * @param sourceId 소스 기억 ID
+     * @param targetId 타겟 기억 ID
+     * @param relationType 관계 유형
+     * @param confidence 신뢰도
+     * @param metadataJson 메타데이터 JSON 문자열
+     * @param allowCyclic 순환 참조 허용 여부
+     * @returns 추가된 관계 ID
+     */
+    private insertNewRelation;
+    /**
+     * 순환 참조 플래그 업데이트
+     *
+     * @param relationId 관계 ID
+     */
+    private updateCyclicFlag;
+    /**
+     * 관계 조회
+     *
+     * @param memoryId 기억 ID
+     * @param options 조회 옵션
+     * @returns 관계 목록
+     */
+    getRelations(memoryId: string, options?: GetRelationsOptions): Promise<MemoryRelation[]>;
+    /**
+     * 관련 기억 조회 (N-hop 관계 탐색)
+     * BFS 알고리즘을 사용하여 N-hop 관계를 탐색합니다.
+     *
+     * @param memoryId 시작 기억 ID
+     * @param options 탐색 옵션
+     * @returns 관련 기억 ID 목록과 hop 거리
+     */
+    getRelatedMemories(memoryId: string, options?: GetRelatedMemoriesOptions): Promise<Array<{
+        memory_id: string;
+        hop_distance: number;
+        relation_path: Array<{
+            source_id: string;
+            target_id: string;
+            relation_type: RelationType;
+        }>;
+    }>>;
+    /**
+     * 관계 삭제
+     *
+     * @param sourceId 소스 기억 ID
+     * @param targetId 타겟 기억 ID
+     * @param relationType 관계 유형
+     * @returns 삭제 성공 여부
+     */
+    removeRelation(sourceId: string, targetId: string, relationType: RelationType): Promise<boolean>;
+    /**
+     * 신뢰도 갱신
+     *
+     * @param sourceId 소스 기억 ID
+     * @param targetId 타겟 기억 ID
+     * @param relationType 관계 유형
+     * @param newConfidence 새로운 신뢰도
+     * @param reason 갱신 이유
+     * @returns 갱신 성공 여부
+     */
+    updateConfidence(sourceId: string, targetId: string, relationType: RelationType, newConfidence: number, reason?: string): Promise<boolean>;
+    /**
+     * 순환 참조 감지 (DFS)
+     *
+     * 트랜잭션 내에서 실행하여 경쟁 조건을 방지합니다.
+     * 순환 참조 감지 중에 다른 프로세스/스레드에서 관계가 추가되는 것을 방지하기 위해
+     * 트랜잭션 격리 수준을 사용합니다.
+     *
+     * 성능 최적화:
+     * - 최대 탐색 깊이 제한 (기본값: 10)
+     * - 대규모 그래프에서 무한 루프 방지
+     *
+     * @param sourceId 소스 기억 ID
+     * @param targetId 타겟 기억 ID
+     * @param relationType 관계 유형
+     * @param maxDepth 최대 탐색 깊이 (기본값: 10)
+     * @returns 순환 참조 여부
+     */
+    /**
+     * 순환 참조 감지 내부 로직 (트랜잭션 없이 실행)
+     *
+     * @param sourceId 소스 기억 ID
+     * @param targetId 타겟 기억 ID
+     * @param relationType 관계 유형
+     * @param maxDepth 최대 탐색 깊이
+     * @returns 순환 참조 여부
+     */
+    private detectCycleInternal;
+    /**
+     * 순환 참조 감지 (공개 메서드)
+     * 트랜잭션을 자동으로 관리합니다.
+     *
+     * @param sourceId 소스 기억 ID
+     * @param targetId 타겟 기억 ID
+     * @param relationType 관계 유형
+     * @param maxDepth 최대 탐색 깊이 (기본값: 10)
+     * @returns 순환 참조 여부
+     */
+    detectCycle(sourceId: string, targetId: string, relationType: RelationType, maxDepth?: number): Promise<boolean>;
+    /**
+     * 캐시 키 생성
+     * 공통 유틸리티를 사용하여 일관된 캐시 키를 생성합니다.
+     *
+     * @param memoryId 기억 ID
+     * @param options 조회 옵션
+     * @returns 캐시 키
+     */
+    private generateCacheKey;
+    /**
+     * 캐시 키를 인덱스에 추가
+     * 정확한 캐시 무효화를 위해 사용
+     *
+     * @param memoryId 기억 ID
+     * @param cacheKey 캐시 키
+     */
+    private addCacheKeyToIndex;
+    /**
+     * 캐시 무효화
+     * 특정 메모리 ID와 관련된 캐시를 정확하게 무효화합니다.
+     *
+     * 최적화 전략:
+     * 1. 캐시 키 인덱스를 우선 사용하여 O(1) 접근으로 정확한 캐시 키 삭제
+     * 2. 인덱스가 없는 경우에만 패턴 기반 삭제 수행 (fallback)
+     *
+     * 성능 고려사항:
+     * - 인덱스가 있는 경우: O(n) where n = 해당 memoryId의 캐시 키 수
+     * - 인덱스가 없는 경우: O(m) where m = 전체 캐시 키 수 (최악의 경우)
+     * - 일반적으로 인덱스가 있으므로 효율적
+     *
+     * @param memoryId 기억 ID
+     */
+    private invalidateCache;
+    /**
+     * 배치 관계 추가
+     * 여러 관계를 한 번에 추가하여 성능을 최적화합니다.
+     *
+     * @param relations 추가할 관계 목록
+     * @returns 배치 처리 결과 (성공한 관계 ID 목록 및 실패한 관계 정보)
+     */
+    addRelationsBatch(relations: Array<{
+        source_id: string;
+        target_id: string;
+        relation_type: RelationType;
+        confidence?: number;
+        metadata?: RelationMetadata;
+    }>): Promise<{
+        insertedIds: number[];
+        failed: Array<{
+            source_id: string;
+            target_id: string;
+            relation_type: RelationType;
+            error: string;
+        }>;
+        total: number;
+        success: number;
+        failedCount: number;
+    }>;
+}
+//# sourceMappingURL=relation-graph.d.ts.map

package/dist/services/relation-graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relation-graph.d.ts","sourceRoot":"","sources":["../../src/services/relation-graph.ts"],"names":[],"mappings":"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"}