memento-mcp-server 0.1.0 → 1.7.1

package/.cursor/rules/error-logging.mdc

@@ -1,298 +0,0 @@
----
-globs: *error-logging*
-description: Memento 프로젝트의 에러 로깅 시스템 개발 규칙입니다. 구조화된 에러 로깅, 통계 수집, 해결 추적을 통한 시스템 안정성 향상을 위한 가이드라인을 제공합니다.
----
-
-# 에러 로깅 시스템 개발 규칙
-
-## 🎯 개요
-
-에러 로깅 시스템은 Memento MCP Server의 안정성을 보장하기 위한 핵심 컴포넌트입니다. 구조화된 에러 로깅, 통계 수집, 해결 추적을 통해 시스템의 신뢰성을 향상시킵니다.
-
-## 📁 파일 구조
-
-```
-src/services/
-├── error-logging-service.ts    # 메인 서비스
-└── test-error-logging.ts       # 테스트 파일
-```
-
-## 🔧 핵심 기능
-
-### 1. 구조화된 에러 로깅
-- **심각도 분류**: LOW, MEDIUM, HIGH, CRITICAL
-- **카테고리 분류**: DATABASE, NETWORK, TOOL_EXECUTION, VALIDATION, SYSTEM
-- **컨텍스트 정보**: 사용자 ID, 작업 유형, 타임스탬프
-- **스택 트레이스**: 상세한 에러 정보
-
-### 2. 에러 통계 수집
-- **심각도별 통계**: 에러 분포 분석
-- **카테고리별 통계**: 문제 영역 식별
-- **시간별 통계**: 트렌드 분석
-- **해결률 통계**: 처리 효율성 측정
-
-### 3. 에러 해결 추적
-- **해결 상태 관리**: PENDING, IN_PROGRESS, RESOLVED
-- **해결자 추적**: 담당자 식별
-- **해결 방법 기록**: 문제 해결 과정
-- **재발 방지**: 근본 원인 분석
-
-## 🛠️ 개발 가이드라인
-
-### 서비스 인터페이스
-```typescript
-interface ErrorLoggingService {
-  // 에러 로깅
-  logError(
-    error: Error,
-    severity: ErrorSeverity,
-    category: ErrorCategory,
-    context?: Record<string, any>
-  ): void;
-  
-  // 에러 통계 조회
-  getErrorStats(filters?: ErrorFilters): Promise<ErrorStats>;
-  
-  // 에러 해결
-  resolveError(
-    errorId: string,
-    resolvedBy: string,
-    resolution?: string
-  ): Promise<boolean>;
-  
-  // 에러 검색
-  searchErrors(filters: ErrorSearchFilters): Promise<ErrorLog[]>;
-}
-```
-
-### 에러 심각도 정의
-```typescript
-enum ErrorSeverity {
-  LOW = 'LOW',           // 정보성 에러 (로깅만)
-  MEDIUM = 'MEDIUM',     // 경고성 에러 (모니터링)
-  HIGH = 'HIGH',         // 심각한 에러 (알림 필요)
-  CRITICAL = 'CRITICAL'  // 치명적 에러 (즉시 대응)
-}
-```
-
-### 에러 카테고리 정의
-```typescript
-enum ErrorCategory {
-  UNKNOWN = 'UNKNOWN',           // 알 수 없는 에러
-  DATABASE = 'DATABASE',         // 데이터베이스 관련
-  NETWORK = 'NETWORK',           // 네트워크 관련
-  TOOL_EXECUTION = 'TOOL_EXECUTION', // 도구 실행 관련
-  VALIDATION = 'VALIDATION',     // 입력 검증 관련
-  SYSTEM = 'SYSTEM'              // 시스템 관련
-}
-```
-
-### 에러 로깅 예시
-```typescript
-// 기본 에러 로깅
-errorLoggingService.logError(
-  new Error('Database connection failed'),
-  ErrorSeverity.HIGH,
-  ErrorCategory.DATABASE,
-  {
-    operation: 'memory_search',
-    userId: 'user123',
-    timestamp: new Date().toISOString()
-  }
-);
-
-// 복잡한 에러 로깅
-try {
-  await riskyOperation();
-} catch (error) {
-  errorLoggingService.logError(
-    error instanceof Error ? error : new Error(String(error)),
-    ErrorSeverity.CRITICAL,
-    ErrorCategory.SYSTEM,
-    {
-      operation: 'memory_creation',
-      userId: 'user456',
-      memoryId: 'memory-789',
-      stackTrace: error.stack,
-      additionalContext: {
-        memoryType: 'episodic',
-        contentLength: content.length
-      }
-    }
-  );
-}
-```
-
-## 📊 통계 및 분석
-
-### 에러 통계 구조
-```typescript
-interface ErrorStats {
-  totalErrors: number;
-  errorsBySeverity: Record<ErrorSeverity, number>;
-  errorsByCategory: Record<ErrorCategory, number>;
-  errorsByHour: Record<number, number>;
-  resolutionRate: number;
-  averageResolutionTime: number;
-  topErrors: Array<{
-    message: string;
-    count: number;
-    lastOccurred: Date;
-  }>;
-}
-```
-
-### 통계 조회 예시
-```typescript
-// 전체 통계
-const stats = await errorLoggingService.getErrorStats();
-
-// 필터링된 통계
-const highErrors = await errorLoggingService.getErrorStats({
-  severity: ErrorSeverity.HIGH,
-  hours: 24
-});
-
-// 카테고리별 통계
-const dbErrors = await errorLoggingService.getErrorStats({
-  category: ErrorCategory.DATABASE,
-  limit: 10
-});
-```
-
-## 🔍 에러 해결 워크플로우
-
-### 1. 에러 발견
-```typescript
-// 에러 로깅 시 자동으로 해결 대기 상태로 설정
-const errorId = errorLoggingService.logError(error, severity, category, context);
-```
-
-### 2. 에러 분석
-```typescript
-// 에러 상세 정보 조회
-const errorDetails = await errorLoggingService.getErrorDetails(errorId);
-
-// 관련 에러 검색
-const relatedErrors = await errorLoggingService.searchErrors({
-  message: errorDetails.message,
-  category: errorDetails.category,
-  timeRange: '24h'
-});
-```
-
-### 3. 에러 해결
-```typescript
-// 에러 해결 처리
-const resolved = await errorLoggingService.resolveError(
-  errorId,
-  'admin',
-  '데이터베이스 연결 풀 크기 증가로 해결'
-);
-
-// 해결 확인
-if (resolved) {
-  console.log('에러가 성공적으로 해결되었습니다.');
-}
-```
-
-## 🧪 테스트 가이드라인
-
-### 단위 테스트
-```typescript
-describe('ErrorLoggingService', () => {
-  let service: ErrorLoggingService;
-  
-  beforeEach(() => {
-    service = new ErrorLoggingService();
-  });
-  
-  it('should log error with correct severity', () => {
-    const error = new Error('Test error');
-    service.logError(error, ErrorSeverity.HIGH, ErrorCategory.SYSTEM);
-    
-    const stats = service.getErrorStats();
-    expect(stats.errorsBySeverity[ErrorSeverity.HIGH]).toBe(1);
-  });
-  
-  it('should resolve error correctly', async () => {
-    const error = new Error('Test error');
-    service.logError(error, ErrorSeverity.MEDIUM, ErrorCategory.VALIDATION);
-    
-    const errors = service.searchErrors({ limit: 1 });
-    const errorId = errors[0].id;
-    
-    const resolved = await service.resolveError(errorId, 'test_user', 'Test resolution');
-    expect(resolved).toBe(true);
-  });
-});
-```
-
-### 통합 테스트
-```typescript
-describe('ErrorLogging Integration', () => {
-  it('should integrate with MCP server', async () => {
-    const server = new MCPServer();
-    const errorService = new ErrorLoggingService();
-    
-    // 서버에 에러 로깅 서비스 연결
-    server.setErrorLogger(errorService);
-    
-    // 에러 발생 시나리오
-    try {
-      await server.executeTool('invalid_tool', {});
-    } catch (error) {
-      // 에러가 자동으로 로깅되는지 확인
-      const stats = errorService.getErrorStats();
-      expect(stats.totalErrors).toBeGreaterThan(0);
-    }
-  });
-});
-```
-
-## 📈 모니터링 및 알림
-
-### 실시간 모니터링
-```typescript
-// 에러 발생 시 실시간 알림
-errorLoggingService.on('error', (errorLog) => {
-  if (errorLog.severity === ErrorSeverity.CRITICAL) {
-    // 즉시 알림 전송
-    alertService.sendCriticalAlert(errorLog);
-  }
-});
-```
-
-### 대시보드 메트릭
-- **에러 발생률**: 시간당 에러 수
-- **해결률**: 해결된 에러 비율
-- **평균 해결 시간**: 에러 해결 소요 시간
-- **심각도 분포**: 에러 심각도별 분포
-
-## 🚀 배포 고려사항
-
-### 환경 변수
-```bash
-# 에러 로깅 설정
-ERROR_LOGGING_ENABLED=true
-ERROR_LOGGING_LEVEL=INFO
-ERROR_LOGGING_RETENTION_DAYS=30
-ERROR_LOGGING_ALERT_THRESHOLD=10
-```
-
-### 로그 저장소
-- **로컬 파일**: 개발 환경
-- **데이터베이스**: 프로덕션 환경
-- **외부 서비스**: ELK Stack, Splunk 등
-
-### 성능 최적화
-- **비동기 로깅**: 논블로킹 에러 로깅
-- **배치 처리**: 여러 에러를 한 번에 처리
-- **압축**: 오래된 로그 압축 저장
-
-## 📚 참고 자료
-
-- [Node.js Error Handling](https://nodejs.org/api/errors.html)
-- [Winston Logger](https://github.com/winstonjs/winston)
-- [Structured Logging](https://www.elastic.co/guide/en/ecs/current/index.html)
-- [Error Monitoring Best Practices](https://sentry.io/for/error-monitoring/)

package/.cursor/rules/forgetting-algorithms.mdc

@@ -1,426 +0,0 @@
----
-globs: "src/algorithms/forgetting-algorithm.ts,src/services/forgetting-policy-service.ts"
-description: 망각 알고리즘 및 망각 정책 서비스 개발 규칙
----
-
-# 망각 알고리즘 및 망각 정책 서비스 규칙
-
-## 📋 망각 알고리즘
-
-### 현재 구현 상태
-- **파일**: `src/algorithms/forgetting-algorithm.ts` (244줄)
-- **기능**: Memento-Goals.md의 망각 공식 구현
-- **특징**: 최근성, 사용성, 중복 비율, 중요도, 고정 여부를 종합한 망각 점수 계산
-
-### 핵심 인터페이스
-
-```typescript
-interface ForgettingFeatures {
-  recency: number;        // 최근성 (0-1)
-  usage: number;          // 사용성 (0-1)
-  duplication_ratio: number; // 중복 비율 (0-1)
-  importance: number;     // 중요도 (0-1)
-  pinned: boolean;        // 고정 여부
-}
-
-interface ForgettingWeights {
-  recency: number;        // U1 = 0.35
-  usage: number;          // U2 = 0.25
-  duplication: number;    // U3 = 0.20
-  importance: number;     // U4 = 0.15
-  pinned: number;         // U5 = 0.30
-}
-
-interface ForgettingResult {
-  memory_id: string;
-  forget_score: number;
-  should_forget: boolean;
-  reason: string;
-  features: ForgettingFeatures;
-}
-```
-
-### 구현 가이드라인
-
-#### 1. 망각 점수 계산
-```typescript
-calculateForgetScore(features: ForgettingFeatures): number {
-  const { recency, usage, duplication_ratio, importance, pinned } = features;
-  
-  // 망각 점수 공식: U1*(1-recency) + U2*(1-usage) + U3*duplication - U4*importance - U5*pinned
-  const score = 
-    this.weights.recency * (1 - recency) +
-    this.weights.usage * (1 - usage) +
-    this.weights.duplication * duplication_ratio -
-    this.weights.importance * importance -
-    this.weights.pinned * (pinned ? 1 : 0);
-  
-  return Math.max(0, Math.min(1, score));
-}
-```
-
-#### 2. 특징 계산
-```typescript
-// 최근성 계산 (지수 감쇠)
-calculateRecency(createdAt: Date, type: string): number {
-  const ageDays = this.getAgeInDays(createdAt);
-  const halfLife = this.getHalfLife(type);
-  return Math.exp(-Math.log(2) * ageDays / halfLife);
-}
-
-// 사용성 계산 (로그 스케일)
-calculateUsage(viewCount: number, citeCount: number, editCount: number): number {
-  const rawUsage = 
-    Math.log(1 + viewCount) +
-    2 * Math.log(1 + citeCount) +
-    0.5 * Math.log(1 + editCount);
-  
-  return this.normalize(rawUsage, this.batchMin, this.batchMax);
-}
-
-// 중복 비율 계산
-calculateDuplicationRatio(memoryId: string, similarMemories: string[]): number {
-  if (similarMemories.length === 0) return 0;
-  
-  const similarityScores = similarMemories.map(id => 
-    this.calculateSimilarity(memoryId, id)
-  );
-  
-  return Math.max(...similarityScores);
-}
-```
-
-#### 3. 망각 결정
-```typescript
-shouldForget(features: ForgettingFeatures, threshold: number = 0.6): boolean {
-  const forgetScore = this.calculateForgetScore(features);
-  return forgetScore >= threshold && !features.pinned;
-}
-```
-
-## 🔄 간격 반복 알고리즘
-
-### 현재 구현 상태
-- **파일**: `src/algorithms/spaced-repetition.ts` (239줄)
-- **기능**: 중요도와 사용성 기반 리뷰 간격 계산
-- **특징**: 피드백에 따른 동적 간격 조정
-
-### 핵심 인터페이스
-
-```typescript
-interface SpacedRepetitionFeatures {
-  importance: number;        // 중요도 (0-1)
-  usage: number;            // 사용성 (0-1)
-  helpful_feedback: number; // 도움됨 피드백 (0-1)
-  bad_feedback: number;     // 나쁨 피드백 (0-1)
-}
-
-interface ReviewSchedule {
-  memory_id: string;
-  current_interval: number;  // 현재 간격 (일)
-  next_review: Date;        // 다음 리뷰 날짜
-  recall_probability: number; // 리콜 확률
-  needs_review: boolean;    // 리뷰 필요 여부
-  multiplier: number;       // 간격 배수
-}
-```
-
-### 구현 가이드라인
-
-#### 1. 간격 계산
-```typescript
-calculateNextInterval(
-  currentInterval: number,
-  features: SpacedRepetitionFeatures
-): number {
-  const multiplier = 1 + 
-    this.weights.importance * features.importance +
-    this.weights.usage * features.usage +
-    this.weights.helpful_feedback * features.helpful_feedback -
-    this.weights.bad_feedback * features.bad_feedback;
-  
-  return Math.ceil(currentInterval * multiplier);
-}
-```
-
-#### 2. 리콜 확률 계산
-```typescript
-calculateRecallProbability(
-  timeSinceLastReview: number,
-  interval: number
-): number {
-  return Math.exp(-timeSinceLastReview / interval);
-}
-```
-
-#### 3. 리뷰 필요 여부 판단
-```typescript
-needsReview(
-  timeSinceLastReview: number,
-  interval: number,
-  threshold: number = 0.7
-): boolean {
-  const recallProb = this.calculateRecallProbability(timeSinceLastReview, interval);
-  return recallProb <= threshold;
-}
-```
-
-## 🧠 망각 정책 서비스
-
-### 현재 구현 상태
-- **파일**: `src/services/forgetting-policy-service.ts` (335줄)
-- **기능**: 망각 알고리즘과 간격 반복을 통합한 메모리 관리
-- **특징**: TTL 기반 정책, 소프트/하드 삭제
-
-### 핵심 인터페이스
-
-```typescript
-interface ForgettingPolicyConfig {
-  forgetThreshold: number;        // 망각 임계값 (기본: 0.6)
-  softDeleteThreshold: number;    // 소프트 삭제 임계값 (기본: 0.6)
-  hardDeleteThreshold: number;    // 하드 삭제 임계값 (기본: 0.8)
-  
-  ttlSoft: {
-    working: number;
-    episodic: number;
-    semantic: number;
-    procedural: number;
-  };
-  
-  ttlHard: {
-    working: number;
-    episodic: number;
-    semantic: number;
-    procedural: number;
-  };
-}
-```
-
-### 구현 가이드라인
-
-#### 1. 정책 적용
-```typescript
-async applyForgettingPolicy(): Promise<ForgettingPolicyResult> {
-  const memories = await this.getMemoriesForReview();
-  const results: ForgettingPolicyResult = {
-    softDeleted: [],
-    hardDeleted: [],
-    scheduledForReview: []
-  };
-  
-  for (const memory of memories) {
-    const features = await this.calculateFeatures(memory);
-    const forgetScore = this.forgettingAlgorithm.calculateForgetScore(features);
-    
-    if (forgetScore >= this.config.hardDeleteThreshold) {
-      await this.hardDelete(memory.id);
-      results.hardDeleted.push(memory.id);
-    } else if (forgetScore >= this.config.softDeleteThreshold) {
-      await this.softDelete(memory.id);
-      results.softDeleted.push(memory.id);
-    } else {
-      const schedule = await this.scheduleReview(memory, features);
-      if (schedule.needs_review) {
-        results.scheduledForReview.push(schedule);
-      }
-    }
-  }
-  
-  return results;
-}
-```
-
-#### 2. TTL 검사
-```typescript
-isTTLExpired(memory: MemoryItem, type: 'soft' | 'hard'): boolean {
-  const ageDays = this.getAgeInDays(memory.created_at);
-  const ttl = type === 'soft' ? 
-    this.config.ttlSoft[memory.type] : 
-    this.config.ttlHard[memory.type];
-  
-  return ageDays >= ttl;
-}
-```
-
-#### 3. 배치 처리
-```typescript
-async processBatchForgetting(batchSize: number = 100): Promise<void> {
-  const memories = await this.getMemoriesBatch(batchSize);
-  
-  for (const memory of memories) {
-    try {
-      await this.processMemoryForgetting(memory);
-    } catch (error) {
-      console.error(`Failed to process memory ${memory.id}:`, error);
-    }
-  }
-}
-```
-
-## 🧪 테스트 가이드라인
-
-### 망각 알고리즘 테스트
-```typescript
-describe('ForgettingAlgorithm', () => {
-  let algorithm: ForgettingAlgorithm;
-  
-  beforeEach(() => {
-    algorithm = new ForgettingAlgorithm();
-  });
-  
-  it('should calculate forget score correctly', () => {
-    const features: ForgettingFeatures = {
-      recency: 0.2,
-      usage: 0.1,
-      duplication_ratio: 0.8,
-      importance: 0.3,
-      pinned: false
-    };
-    
-    const score = algorithm.calculateForgetScore(features);
-    expect(score).toBeGreaterThan(0.6);
-  });
-  
-  it('should not forget pinned memories', () => {
-    const features: ForgettingFeatures = {
-      recency: 0.1,
-      usage: 0.1,
-      duplication_ratio: 0.9,
-      importance: 0.2,
-      pinned: true
-    };
-    
-    const shouldForget = algorithm.shouldForget(features);
-    expect(shouldForget).toBe(false);
-  });
-});
-```
-
-### 간격 반복 테스트
-```typescript
-describe('SpacedRepetitionAlgorithm', () => {
-  let algorithm: SpacedRepetitionAlgorithm;
-  
-  beforeEach(() => {
-    algorithm = new SpacedRepetitionAlgorithm();
-  });
-  
-  it('should calculate next interval correctly', () => {
-    const features: SpacedRepetitionFeatures = {
-      importance: 0.8,
-      usage: 0.6,
-      helpful_feedback: 0.7,
-      bad_feedback: 0.1
-    };
-    
-    const nextInterval = algorithm.calculateNextInterval(7, features);
-    expect(nextInterval).toBeGreaterThan(7);
-  });
-  
-  it('should determine review need correctly', () => {
-    const needsReview = algorithm.needsReview(10, 7, 0.7);
-    expect(needsReview).toBe(true);
-  });
-});
-```
-
-## 📊 성능 최적화
-
-### 1. 배치 처리
-```typescript
-// 대량 메모리 처리 시 배치 단위로 처리
-async processMemoriesInBatches(memories: MemoryItem[], batchSize: number = 100) {
-  for (let i = 0; i < memories.length; i += batchSize) {
-    const batch = memories.slice(i, i + batchSize);
-    await Promise.all(batch.map(memory => this.processMemory(memory)));
-  }
-}
-```
-
-### 2. 캐싱
-```typescript
-// 특징 계산 결과 캐싱
-private featureCache = new Map<string, ForgettingFeatures>();
-
-async getCachedFeatures(memoryId: string): Promise<ForgettingFeatures> {
-  if (this.featureCache.has(memoryId)) {
-    return this.featureCache.get(memoryId)!;
-  }
-  
-  const features = await this.calculateFeatures(memoryId);
-  this.featureCache.set(memoryId, features);
-  return features;
-}
-```
-
-### 3. 인덱스 최적화
-```sql
--- 망각 정책 쿼리 최적화를 위한 인덱스
-CREATE INDEX idx_memory_item_forgetting ON memory_item(
-  created_at, last_accessed, importance, pinned
-);
-
-CREATE INDEX idx_memory_item_type_created ON memory_item(type, created_at);
-```
-
-## 🔧 설정 관리
-
-### 환경 변수
-```bash
-# .env 파일
-FORGET_THRESHOLD=0.6
-SOFT_DELETE_THRESHOLD=0.6
-HARD_DELETE_THRESHOLD=0.8
-
-# TTL 설정 (일 단위)
-TTL_SOFT_WORKING=2
-TTL_SOFT_EPISODIC=30
-TTL_SOFT_SEMANTIC=180
-TTL_SOFT_PROCEDURAL=90
-
-TTL_HARD_WORKING=7
-TTL_HARD_EPISODIC=180
-TTL_HARD_SEMANTIC=365
-TTL_HARD_PROCEDURAL=180
-```
-
-### 설정 검증
-```typescript
-private validateConfig(config: ForgettingPolicyConfig): void {
-  if (config.forgetThreshold < 0 || config.forgetThreshold > 1) {
-    throw new Error('forgetThreshold must be between 0 and 1');
-  }
-  
-  if (config.softDeleteThreshold >= config.hardDeleteThreshold) {
-    throw new Error('softDeleteThreshold must be less than hardDeleteThreshold');
-  }
-  
-  // TTL 값 검증
-  Object.values(config.ttlSoft).forEach(ttl => {
-    if (ttl <= 0) throw new Error('TTL values must be positive');
-  });
-}
-```
-
-## 📋 개발 체크리스트
-
-### 망각 알고리즘
-- [ ] 망각 점수 계산 로직 구현
-- [ ] 특징 계산 함수 구현
-- [ ] 망각 결정 로직 구현
-- [ ] 에러 처리 및 로깅 추가
-- [ ] 단위 테스트 작성
-
-### 간격 반복 알고리즘
-- [ ] 간격 계산 로직 구현
-- [ ] 리콜 확률 계산 함수
-- [ ] 리뷰 필요 여부 판단 로직
-- [ ] 피드백 처리 로직
-- [ ] 단위 테스트 작성
-
-### 망각 정책 서비스
-- [ ] 정책 적용 로직 구현
-- [ ] TTL 검사 로직
-- [ ] 배치 처리 구현
-- [ ] 데이터베이스 연동
-- [ ] 통합 테스트 작성