memento-mcp-server 0.1.0

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

@@ -0,0 +1,298 @@
+---
+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

@@ -0,0 +1,426 @@
+---
+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 검사 로직
+- [ ] 배치 처리 구현
+- [ ] 데이터베이스 연동
+- [ ] 통합 테스트 작성