memento-mcp-server 1.6.0 → 1.7.2

package/docs/ko/architecture.md

@@ -1,1302 +0,0 @@
-# 아키텍처 문서
-
-## 개요
-
-Memento MCP Server는 AI Agent의 기억을 인간의 기억 체계를 모사하여 관리하는 시스템입니다. 이 문서는 시스템의 전체 아키텍처, 컴포넌트 간 상호작용, 데이터 플로우를 상세히 설명합니다.
-
-## 목차
-
-1. [시스템 아키텍처](#시스템-아키텍처)
-2. [핵심 컴포넌트](#핵심-컴포넌트)
-3. [데이터 모델](#데이터-모델)
-4. [검색 시스템](#검색-시스템)
-5. [망각 시스템](#망각-시스템)
-6. [마일스톤별 아키텍처](#마일스톤별-아키텍처)
-7. [성능 고려사항](#성능-고려사항)
-8. [보안 아키텍처](#보안-아키텍처)
-
-## 시스템 아키텍처
-
-### 전체 아키텍처 다이어그램
-
-```mermaid
-graph TB
-    subgraph "AI Agent Layer"
-        A[Claude Desktop] --> B[MCP Client]
-        C[ChatGPT] --> B
-        D[Cursor] --> B
-        E[Other AI Agents] --> B
-    end
-    
-    subgraph "MCP Protocol Layer"
-        B --> F[MCP Memory Server]
-    end
-    
-    subgraph "Memory Management Layer"
-        F --> G[Memory Manager]
-        F --> H[Search Engine]
-        F --> I[Forgetting Policy]
-        F --> J[Spaced Review]
-        F --> K[Error Logging Service]
-        F --> L[Performance Alert Service]
-        F --> M[Performance Monitoring Integration]
-    end
-    
-    subgraph "Storage Layer"
-        G --> N[SQLite M1]
-        G --> O[PostgreSQL M3+]
-        H --> P[Vector Search]
-        H --> Q[Text Search]
-        I --> R[Memory Queue]
-        K --> S[Error Logs]
-        L --> T[Alert Logs]
-    end
-    
-    subgraph "Data Processing"
-        J --> U[Memory Consolidation]
-        I --> V[Memory Deletion]
-        U --> W[Memory Summary]
-        M --> X[Real-time Monitoring]
-        K --> Y[Error Analysis]
-        L --> Z[Alert Management]
-    end
-```
-
-### 레이어별 역할
-
-#### 1. AI Agent Layer
-- **역할**: MCP 클라이언트를 통해 기억 시스템과 상호작용
-- **구성요소**: Claude Desktop, ChatGPT, Cursor 등
-- **특징**: 다양한 AI Agent가 동일한 MCP 프로토콜 사용
-
-#### 2. MCP Protocol Layer
-- **역할**: 표준화된 통신 프로토콜 제공
-- **구성요소**: MCP Memory Server
-- **특징**: Tools, Resources, Prompts를 통한 기능 제공
-
-#### 3. Memory Management Layer
-- **역할**: 기억의 생성, 검색, 관리, 삭제 및 시스템 모니터링
-- **구성요소**: Memory Manager, Search Engine, Forgetting Policy, Spaced Review, Error Logging Service, Performance Alert Service, Performance Monitoring Integration
-- **특징**: 인간의 기억 체계를 모사한 관리 및 실시간 시스템 모니터링
-
-#### 4. Storage Layer
-- **역할**: 데이터 영구 저장 및 검색
-- **구성요소**: SQLite/PostgreSQL, Vector Search, Text Search
-- **특징**: 마일스톤별 다른 저장소 사용
-
-## 핵심 컴포넌트
-
-### 1. MCP Memory Server
-
-#### 구조
-
-```typescript
-interface MCPServer {
-  // Tools
-  tools: {
-    remember: RememberTool;
-    recall: RecallTool;
-    pin: PinTool;
-    unpin: UnpinTool;
-    forget: ForgetTool;
-    summarize_thread: SummarizeThreadTool;
-    link: LinkTool;
-    export: ExportTool;
-    feedback: FeedbackTool;
-  };
-  
-  // Resources
-  resources: {
-    memory: MemoryResource;
-    search: SearchResource;
-  };
-  
-  // Prompts
-  prompts: {
-    memory_injection: MemoryInjectionPrompt;
-  };
-}
-```
-
-#### 주요 기능
-
-- **Tool 처리**: MCP Tools 실행 및 응답
-- **Resource 제공**: 캐시된 데이터 제공
-- **Prompt 생성**: 컨텍스트 주입용 프롬프트 생성
-- **인증/권한**: 사용자 인증 및 권한 관리 (M2+)
-
-### 2. Memory Manager
-
-#### 구조
-
-```typescript
-interface MemoryManager {
-  // 기억 생성
-  createMemory(params: CreateMemoryParams): Promise<MemoryItem>;
-  
-  // 기억 조회
-  getMemory(id: string): Promise<MemoryItem | null>;
-  
-  // 기억 업데이트
-  updateMemory(id: string, updates: Partial<MemoryItem>): Promise<MemoryItem>;
-  
-  // 기억 삭제
-  deleteMemory(id: string, hard?: boolean): Promise<boolean>;
-  
-  // 기억 고정
-  pinMemory(id: string): Promise<boolean>;
-  unpinMemory(id: string): Promise<boolean>;
-}
-```
-
-#### 주요 기능
-
-- **CRUD 작업**: 기억의 생성, 조회, 수정, 삭제
-- **타입 관리**: 작업기억, 일화기억, 의미기억, 절차기억 구분
-- **메타데이터 관리**: 태그, 중요도, 출처 등 관리
-- **관계 관리**: 기억 간의 관계 설정 및 관리
-
-### 3. Search Engine
-
-#### 구조
-
-```typescript
-interface SearchEngine {
-  // 2단계 검색
-  search(query: string, filters?: SearchFilters): Promise<SearchResult>;
-  
-  // 벡터 검색
-  vectorSearch(query: string, limit: number): Promise<VectorSearchResult>;
-  
-  // 키워드 검색
-  keywordSearch(query: string, filters?: SearchFilters): Promise<KeywordSearchResult>;
-  
-  // 랭킹 계산
-  calculateRanking(results: SearchResult[]): Promise<RankedResult[]>;
-}
-```
-
-#### 검색 파이프라인
-
-```mermaid
-graph LR
-    A[검색 쿼리] --> B[쿼리 전처리]
-    B --> C[벡터 검색]
-    B --> D[키워드 검색]
-    C --> E[결과 병합]
-    D --> E
-    E --> F[랭킹 계산]
-    F --> G[MMR 다양성 제어]
-    G --> H[최종 결과]
-```
-
-#### 랭킹 알고리즘
-
-```typescript
-interface SearchRanking {
-  calculateFinalScore(features: SearchFeatures): number {
-    return this.ALPHA * features.relevance +           // 0.50
-           this.BETA * features.recency +              // 0.20
-           this.GAMMA * features.importance +          // 0.20
-           this.DELTA * features.usage -               // 0.10
-           this.EPSILON * features.duplication_penalty; // 0.15
-  }
-}
-```
-
-### 4. Forgetting Policy
-
-#### 구조
-
-```typescript
-interface ForgettingPolicy {
-  // 망각 점수 계산
-  calculateForgetScore(memory: MemoryItem): number;
-  
-  // 삭제 후보 선정
-  getDeletionCandidates(): Promise<MemoryItem[]>;
-  
-  // 소프트 삭제
-  softDelete(memory: MemoryItem): Promise<boolean>;
-  
-  // 하드 삭제
-  hardDelete(memory: MemoryItem): Promise<boolean>;
-}
-```
-
-#### 망각 알고리즘
-
-```typescript
-interface ForgetScore {
-  calculate(memory: MemoryItem): number {
-    const age = this.calculateAge(memory.created_at);
-    const importance = memory.importance;
-    const usage = this.calculateUsage(memory);
-    
-    return this.baseForgetScore * 
-           Math.exp(-this.importanceWeight * importance) *
-           Math.exp(-this.usageWeight * usage) *
-           Math.exp(this.ageWeight * age);
-  }
-}
-```
-
-### 5. Spaced Review
-
-#### 구조
-
-```typescript
-interface SpacedReview {
-  // 리뷰 스케줄 계산
-  calculateReviewSchedule(memory: MemoryItem): Date;
-  
-  // 리뷰 대상 선정
-  getReviewCandidates(): Promise<MemoryItem[]>;
-  
-  // 리뷰 실행
-  executeReview(memory: MemoryItem): Promise<ReviewResult>;
-  
-  // 간격 조정
-  adjustInterval(memory: MemoryItem, performance: number): void;
-}
-```
-
-### 6. Error Logging Service
-
-#### 구조
-
-```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[]>;
-}
-
-enum ErrorSeverity {
-  LOW = 'LOW',
-  MEDIUM = 'MEDIUM', 
-  HIGH = 'HIGH',
-  CRITICAL = 'CRITICAL'
-}
-
-enum ErrorCategory {
-  UNKNOWN = 'UNKNOWN',
-  DATABASE = 'DATABASE',
-  NETWORK = 'NETWORK',
-  TOOL_EXECUTION = 'TOOL_EXECUTION',
-  VALIDATION = 'VALIDATION',
-  SYSTEM = 'SYSTEM'
-}
-```
-
-#### 주요 기능
-
-- **구조화된 에러 로깅**: 심각도, 카테고리, 컨텍스트 정보 포함
-- **에러 통계 수집**: 심각도별, 카테고리별 에러 분석
-- **에러 해결 추적**: 에러 해결 상태 및 해결 방법 기록
-- **실시간 모니터링**: 에러 발생 패턴 분석 및 알림
-
-### 7. Performance Alert Service
-
-#### 구조
-
-```typescript
-interface PerformanceAlertService {
-  // 알림 생성
-  createAlert(level: AlertLevel, type: AlertType, metric: string, value: number, threshold: number, message: string, context?: Record<string, any>): PerformanceAlert;
-  
-  // 알림 해결
-  resolveAlert(alertId: string, resolvedBy: string, resolution?: string): PerformanceAlert | null;
-  
-  // 활성 알림 조회
-  getActiveAlerts(): PerformanceAlert[];
-  
-  // 알림 검색
-  searchAlerts(filters: AlertSearchFilters): PerformanceAlert[];
-  
-  // 알림 통계
-  getStats(): AlertStats;
-}
-
-enum AlertLevel {
-  INFO = 'INFO',
-  WARNING = 'WARNING',
-  CRITICAL = 'CRITICAL'
-}
-
-enum AlertType {
-  RESPONSE_TIME = 'response_time',
-  MEMORY_USAGE = 'memory_usage',
-  ERROR_RATE = 'error_rate',
-  THROUGHPUT = 'throughput',
-  CUSTOM = 'custom'
-}
-```
-
-#### 주요 기능
-
-- **임계값 기반 알림**: 성능 메트릭이 임계값을 초과할 때 자동 알림
-- **알림 관리**: 알림 생성, 해결, 검색, 통계 기능
-- **로그 파일 저장**: 알림을 JSONL 형식으로 파일에 저장
-- **콘솔 출력**: 심각도별 색상 구분된 콘솔 알림
-
-### 8. Performance Monitoring Integration
-
-#### 구조
-
-```typescript
-interface PerformanceMonitoringIntegration {
-  // 실시간 모니터링 시작
-  startRealTimeMonitoring(): void;
-  
-  // 실시간 모니터링 중지
-  stopRealTimeMonitoring(): void;
-  
-  // 성능 체크
-  private checkPerformance(): Promise<void>;
-  
-  // 임계값 확인
-  private checkResponseTime(avgResponseTime: number): void;
-  private checkMemoryUsage(heapUsedMB: number): void;
-  private checkErrorRate(errorRate: number): void;
-  private checkThroughput(throughput: number): void;
-}
-
-interface AlertThresholds {
-  responseTime: { warning: number; critical: number }; // ms
-  memoryUsage: { warning: number; critical: number }; // MB
-  errorRate: { warning: number; critical: number }; // %
-  throughput: { warning: number; critical: number }; // ops/sec
-}
-```
-
-#### 주요 기능
-
-- **실시간 모니터링**: 30초마다 자동 성능 체크
-- **임계값 기반 알림**: 설정된 임계값 초과 시 자동 알림 생성
-- **통합 모니터링**: PerformanceMonitor와 PerformanceAlertService 연동
-- **자동 복구**: 심각한 문제 발생 시 자동 복구 작업 수행
-
-#### 간격 반복 알고리즘
-
-```typescript
-interface SpacedRepetition {
-  calculateNextReview(memory: MemoryItem, performance: number): Date {
-    const currentInterval = memory.review_interval || 1;
-    const newInterval = this.calculateInterval(currentInterval, performance);
-    
-    return new Date(Date.now() + newInterval * 24 * 60 * 60 * 1000);
-  }
-}
-```
-
-## 데이터 모델
-
-### 1. 메모리 아이템
-
-```typescript
-interface MemoryItem {
-  id: string;                       // 고유 식별자
-  content: string;                  // 기억 내용
-  type: 'working' | 'episodic' | 'semantic' | 'procedural';  // 기억 타입
-  importance: number;               // 중요도 (0-1)
-  created_at: Date;                 // 생성 시간
-  last_accessed: Date;              // 마지막 접근 시간
-  access_count: number;             // 접근 횟수
-  pinned: boolean;                  // 고정 여부
-  source?: string;                  // 출처
-  tags: string[];                   // 태그
-  privacy_scope: 'private' | 'team' | 'public';  // 공개 범위
-  project_id?: string;              // 프로젝트 ID (M2+)
-  user_id?: string;                 // 사용자 ID (M3+)
-  metadata: Record<string, any>;    // 추가 메타데이터
-}
-```
-
-### 2. 검색 결과
-
-```typescript
-interface SearchResult {
-  items: MemoryItem[];              // 검색된 기억 목록
-  total_count: number;              // 전체 결과 수
-  query_time: number;               // 검색 소요 시간 (ms)
-  search_metadata: {
-    vector_matches: number;         // 벡터 검색 매치 수
-    keyword_matches: number;        // 키워드 검색 매치 수
-    ranking_time: number;           // 랭킹 계산 시간
-  };
-}
-```
-
-### 3. 기억 관계
-
-```typescript
-interface MemoryLink {
-  id: string;                       // 링크 ID
-  source_id: string;                // 소스 기억 ID
-  target_id: string;                // 대상 기억 ID
-  relation_type: 'cause_of' | 'derived_from' | 'duplicates' | 'contradicts';
-  created_at: Date;                 // 생성 시간
-  strength: number;                 // 관계 강도 (0-1)
-}
-```
-
-### 4. 피드백
-
-```typescript
-interface Feedback {
-  id: string;                       // 피드백 ID
-  memory_id: string;                // 기억 ID
-  helpful: boolean;                 // 유용성 여부
-  score?: number;                   // 점수 (0-1)
-  comment?: string;                 // 코멘트
-  created_at: Date;                 // 생성 시간
-  user_id?: string;                 // 사용자 ID (M3+)
-}
-```
-
-## 검색 시스템
-
-### 하이브리드 검색 아키텍처
-
-Memento는 FTS5 텍스트 검색과 벡터 검색을 결합한 하이브리드 검색 시스템을 제공합니다.
-
-```mermaid
-graph TB
-    subgraph "하이브리드 검색 엔진"
-        A[사용자 쿼리] --> B[하이브리드 검색 엔진]
-        B --> C[FTS5 텍스트 검색]
-        B --> D[벡터 검색]
-        C --> E[텍스트 점수]
-        D --> F[벡터 점수]
-        E --> G[점수 정규화]
-        F --> G
-        G --> H[가중치 적용]
-        H --> I[최종 하이브리드 점수]
-        I --> J[결과 정렬 및 반환]
-    end
-    
-    subgraph "임베딩 서비스"
-        K[텍스트 입력] --> L[OpenAI API]
-        L --> M[1536차원 벡터]
-        M --> N[데이터베이스 저장]
-        N --> O[벡터 검색 인덱스]
-    end
-```
-
-### 임베딩 서비스 아키텍처
-
-```mermaid
-graph TB
-    subgraph "임베딩 서비스 레이어"
-        A[텍스트 입력] --> B[EmbeddingService]
-        B --> C[OpenAI API 호출]
-        C --> D[text-embedding-3-small]
-        D --> E[1536차원 벡터]
-        E --> F[MemoryEmbeddingService]
-        F --> G[데이터베이스 저장]
-        G --> H[벡터 검색 인덱스]
-    end
-    
-    subgraph "에러 처리 및 캐싱"
-        I[API 재시도 로직]
-        J[임베딩 결과 캐싱]
-        K[에러 복구 메커니즘]
-    end
-```
-
-### 1. 2단계 검색 파이프라인
-
-#### 1단계: 벡터 검색 (ANN)
-
-```typescript
-interface VectorSearch {
-  // 임베딩 생성
-  generateEmbedding(text: string): Promise<number[]>;
-  
-  // 벡터 검색
-  search(embedding: number[], limit: number): Promise<VectorSearchResult>;
-  
-  // 인덱스 업데이트
-  updateIndex(memory: MemoryItem): Promise<void>;
-}
-```
-
-**특징**:
-- 의미적 유사도 검색
-- 빠른 검색 속도 (O(log n))
-- 다국어 지원
-
-#### 2단계: 키워드 검색 (BM25)
-
-```typescript
-interface KeywordSearch {
-  // 텍스트 인덱싱
-  indexText(memory: MemoryItem): Promise<void>;
-  
-  // BM25 검색
-  search(query: string, filters?: SearchFilters): Promise<KeywordSearchResult>;
-  
-  // 인덱스 최적화
-  optimizeIndex(): Promise<void>;
-}
-```
-
-**특징**:
-- 정확한 키워드 매칭
-- 가중치 기반 랭킹
-- 필터링 지원
-
-### 2. 랭킹 알고리즘
-
-#### 복합 점수 계산
-
-```typescript
-interface SearchRanking {
-  calculateFinalScore(features: SearchFeatures): number {
-    const relevance = this.calculateRelevance(features);
-    const recency = this.calculateRecency(features);
-    const importance = this.calculateImportance(features);
-    const usage = this.calculateUsage(features);
-    const duplication = this.calculateDuplicationPenalty(features);
-    
-    return this.ALPHA * relevance +           // 0.50
-           this.BETA * recency +              // 0.20
-           this.GAMMA * importance +          // 0.20
-           this.DELTA * usage -               // 0.10
-           this.EPSILON * duplication;        // 0.15
-  }
-}
-```
-
-#### 관련성 계산
-
-```typescript
-interface RelevanceCalculation {
-  calculate(features: SearchFeatures): number {
-    const vectorSimilarity = features.vector_similarity;
-    const bm25Score = features.bm25_score;
-    const tagMatch = features.tag_match_score;
-    const titleHit = features.title_hit_score;
-    
-    return (vectorSimilarity * 0.4) +
-           (bm25Score * 0.3) +
-           (tagMatch * 0.2) +
-           (titleHit * 0.1);
-  }
-}
-```
-
-### 3. MMR 다양성 제어
-
-```typescript
-interface MMRDiversity {
-  selectDiverseResults(results: SearchResult[], lambda: number = 0.7): SearchResult[] {
-    const selected: SearchResult[] = [];
-    const remaining = [...results];
-    
-    while (remaining.length > 0 && selected.length < this.maxResults) {
-      let bestIndex = 0;
-      let bestScore = -Infinity;
-      
-      for (let i = 0; i < remaining.length; i++) {
-        const relevance = remaining[i].score;
-        const diversity = this.calculateDiversity(remaining[i], selected);
-        const score = lambda * relevance + (1 - lambda) * diversity;
-        
-        if (score > bestScore) {
-          bestScore = score;
-          bestIndex = i;
-        }
-      }
-      
-      selected.push(remaining[bestIndex]);
-      remaining.splice(bestIndex, 1);
-    }
-    
-    return selected;
-  }
-}
-```
-
-## 망각 시스템
-
-### 1. TTL 기반 자동 삭제
-
-#### 기억 타입별 TTL
-
-```typescript
-interface MemoryTTL {
-  WORKING_MEMORY: 48 * 60 * 60 * 1000;    // 48시간
-  EPISODIC_MEMORY: 90 * 24 * 60 * 60 * 1000;  // 90일
-  SEMANTIC_MEMORY: Infinity;              // 무기한
-  PROCEDURAL_MEMORY: Infinity;            // 무기한
-}
-```
-
-#### 삭제 스케줄링
-
-```typescript
-interface DeletionScheduler {
-  scheduleDeletion(memory: MemoryItem): void {
-    const ttl = this.getTTL(memory.type);
-    if (ttl === Infinity) return;
-    
-    const deletionTime = new Date(memory.created_at.getTime() + ttl);
-    this.scheduleTask(deletionTime, () => this.deleteMemory(memory));
-  }
-}
-```
-
-### 2. 중요도 기반 망각
-
-#### 망각 점수 계산
-
-```typescript
-interface ForgetScore {
-  calculate(memory: MemoryItem): number {
-    const age = this.calculateAge(memory.created_at);
-    const importance = memory.importance;
-    const usage = this.calculateUsage(memory);
-    const recency = this.calculateRecency(memory.last_accessed);
-    
-    return this.baseForgetScore *
-           Math.exp(-this.importanceWeight * importance) *
-           Math.exp(-this.usageWeight * usage) *
-           Math.exp(-this.recencyWeight * recency) *
-           Math.exp(this.ageWeight * age);
-  }
-}
-```
-
-### 3. 간격 반복 시스템
-
-#### 리뷰 스케줄 계산
-
-```typescript
-interface SpacedRepetition {
-  calculateNextReview(memory: MemoryItem, performance: number): Date {
-    const currentInterval = memory.review_interval || 1;
-    const newInterval = this.calculateInterval(currentInterval, performance);
-    
-    return new Date(Date.now() + newInterval * 24 * 60 * 60 * 1000);
-  }
-  
-  calculateInterval(currentInterval: number, performance: number): number {
-    if (performance >= 0.8) {
-      return Math.min(currentInterval * 2.5, 365);  // 성공 시 간격 증가
-    } else if (performance >= 0.6) {
-      return Math.max(currentInterval * 1.2, 1);    // 보통 시 약간 증가
-    } else {
-      return 1;  // 실패 시 다시 1일 후
-    }
-  }
-}
-```
-
-## 마일스톤별 아키텍처
-
-### M1: 개인용 (MVP)
-
-#### 아키텍처
-
-```mermaid
-graph TB
-    A[AI Agent] --> B[MCP Client]
-    B --> C[MCP Memory Server]
-    C --> D[SQLite Database]
-    C --> E[FTS5 Index]
-    C --> F[VEC Index]
-    C --> G[Local File System]
-```
-
-#### 특징
-
-- **스토리지**: better-sqlite3 임베디드
-- **검색**: FTS5 + sqlite-vec
-- **인증**: 없음 (로컬 전용)
-- **배포**: 로컬 실행
-- **추가 기능**: 경량 임베딩, 성능 모니터링, 캐시 시스템
-- **확장성**: 단일 사용자
-
-#### 기술 스택
-
-- **데이터베이스**: better-sqlite3 12.4+
-- **벡터 검색**: sqlite-vec
-- **텍스트 검색**: FTS5
-- **웹 서버**: Express 5.1+
-- **WebSocket**: ws 8.18+
-- **테스트**: Vitest 1.0+
-- **런타임**: Node.js 20+
-
-### M2: 팀 협업
-
-#### 아키텍처
-
-```mermaid
-graph TB
-    A[AI Agents] --> B[MCP Client]
-    B --> C[MCP Memory Server]
-    C --> D[SQLite Server Mode]
-    C --> E[Redis Cache]
-    C --> F[API Gateway]
-    F --> G[Authentication]
-```
-
-#### 특징
-
-- **스토리지**: SQLite 서버 모드 (WAL)
-- **캐싱**: Redis
-- **인증**: API Key
-- **배포**: Docker
-- **확장성**: 팀 단위 (10-50명)
-
-#### 기술 스택
-
-- **데이터베이스**: SQLite Server Mode
-- **캐시**: Redis 7+
-- **컨테이너**: Docker
-- **인증**: API Key
-
-### M3: 조직 초입
-
-#### 아키텍처
-
-```mermaid
-graph TB
-    A[AI Agents] --> B[MCP Client]
-    B --> C[Load Balancer]
-    C --> D[MCP Memory Server]
-    D --> E[PostgreSQL]
-    D --> F[Redis Cache]
-    D --> G[Authentication Service]
-    G --> H[JWT Token]
-```
-
-#### 특징
-
-- **스토리지**: PostgreSQL + pgvector
-- **검색**: pgvector + tsvector
-- **인증**: JWT
-- **배포**: Docker Compose
-- **확장성**: 조직 단위 (100-1000명)
-
-#### 기술 스택
-
-- **데이터베이스**: PostgreSQL 15+ + pgvector
-- **검색**: pgvector, tsvector
-- **캐시**: Redis 7+
-- **인증**: JWT
-- **배포**: Docker Compose
-
-### M4: 엔터프라이즈
-
-#### 아키텍처
-
-```mermaid
-graph TB
-    A[AI Agents] --> B[MCP Client]
-    B --> C[API Gateway]
-    C --> D[Load Balancer]
-    D --> E[MCP Memory Server Cluster]
-    E --> F[PostgreSQL HA]
-    E --> G[Redis Cluster]
-    E --> H[Authentication Service]
-    H --> I[SSO/LDAP]
-    E --> J[Monitoring]
-    J --> K[Prometheus]
-    J --> L[Grafana]
-```
-
-#### 특징
-
-- **스토리지**: PostgreSQL 고가용성
-- **캐싱**: Redis 클러스터
-- **인증**: JWT + RBAC + SSO/LDAP
-- **배포**: Kubernetes
-- **확장성**: 엔터프라이즈 (1000명+)
-
-#### 기술 스택
-
-- **데이터베이스**: PostgreSQL HA + pgvector
-- **캐시**: Redis Cluster
-- **인증**: JWT + RBAC + SSO/LDAP
-- **배포**: Kubernetes
-- **모니터링**: Prometheus + Grafana
-
-## 성능 고려사항
-
-### 1. 검색 성능
-
-#### 하이브리드 검색 최적화
-
-```typescript
-interface HybridSearchOptimization {
-  // FTS5 + 벡터 검색 결합
-  optimizeHybridSearch(): void {
-    this.createFTSIndex('memory_item_fts', 'content');
-    this.createVectorIndex('memory_embedding', 'embedding', 'ivfflat');
-    this.analyzeTable('memory_item');
-  }
-  
-  // 배치 처리
-  batchUpdateEmbeddings(memories: MemoryItem[]): void {
-    const batchSize = 100;
-    for (let i = 0; i < memories.length; i += batchSize) {
-      const batch = memories.slice(i, i + batchSize);
-      this.updateEmbeddingsBatch(batch);
-    }
-  }
-}
-```
-
-#### 경량 임베딩 최적화
-
-```typescript
-interface LightweightEmbeddingOptimization {
-  // TF-IDF 벡터화
-  optimizeTFIDF(): void {
-    this.updateVocabulary();
-    this.calculateIDF();
-    this.normalizeVectors();
-  }
-  
-  // 다국어 지원
-  preprocessText(text: string): string {
-    return this.removeStopWords(text)
-      .normalizeUnicode()
-      .tokenize()
-      .stem();
-  }
-}
-```
-
-#### 캐싱 전략
-
-```typescript
-interface CachingStrategy {
-  // LRU 캐시 구현
-  cacheSearchResult(query: string, result: SearchResult): void {
-    const key = `search:${this.hashQuery(query)}`;
-    this.lruCache.set(key, result, 3600); // 1시간 TTL
-  }
-  
-  // 임베딩 캐싱
-  cacheEmbedding(text: string, embedding: number[]): void {
-    const key = `embedding:${this.hashText(text)}`;
-    this.lruCache.set(key, embedding, 86400); // 24시간 TTL
-  }
-  
-  // 인기 검색어 캐싱
-  cachePopularQueries(): void {
-    const popular = this.getPopularQueries(100);
-    this.lruCache.set('popular_queries', popular, 86400); // 24시간 TTL
-  }
-}
-```
-
-### 2. 메모리 사용량
-
-#### 성능 모니터링
-
-```typescript
-interface PerformanceMonitoring {
-  // 메모리 사용량 모니터링
-  monitorMemoryUsage(): void {
-    const usage = process.memoryUsage();
-    this.metrics.record('memory.heapUsed', usage.heapUsed);
-    this.metrics.record('memory.heapTotal', usage.heapTotal);
-    this.metrics.record('memory.rss', usage.rss);
-  }
-  
-  // 캐시 성능 모니터링
-  monitorCachePerformance(): void {
-    this.metrics.record('cache.hitRate', this.cache.getHitRate());
-    this.metrics.record('cache.size', this.cache.getSize());
-    this.metrics.record('cache.memoryUsage', this.cache.getMemoryUsage());
-  }
-}
-```
-
-#### 메모리 풀 관리
-
-```typescript
-interface MemoryPool {
-  private pool: Buffer[] = [];
-  private maxSize: number = 100;
-  
-  getBuffer(size: number): Buffer {
-    const buffer = this.pool.find(b => b.length >= size);
-    if (buffer) {
-      return buffer;
-    }
-    return Buffer.alloc(size);
-  }
-  
-  returnBuffer(buffer: Buffer): void {
-    if (this.pool.length < this.maxSize) {
-      this.pool.push(buffer);
-    }
-  }
-}
-```
-
-#### 가비지 컬렉션 최적화
-
-```typescript
-interface GCOptimization {
-  // 메모리 사용량 모니터링
-  monitorMemoryUsage(): void {
-    const usage = process.memoryUsage();
-    if (usage.heapUsed > this.threshold) {
-      this.triggerGC();
-    }
-  }
-  
-  // 불필요한 객체 정리
-  cleanup(): void {
-    this.clearExpiredCache();
-    this.clearUnusedConnections();
-    this.optimizeIndexes();
-  }
-}
-```
-
-### 3. 데이터베이스 성능
-
-#### better-sqlite3 최적화
-
-```sql
--- 인덱스 최적화
-CREATE INDEX idx_memory_type_created ON memory_item(type, created_at);
-CREATE INDEX idx_memory_importance ON memory_item(importance DESC);
-CREATE INDEX idx_memory_tags ON memory_item USING GIN(tags);
-
--- 벡터 검색 인덱스
-CREATE INDEX idx_memory_embedding ON memory_embedding 
-USING ivfflat (embedding vector_cosine_ops) WITH (lists = 100);
-
--- FTS 인덱스
-CREATE VIRTUAL TABLE memory_fts USING fts5(
-  content, 
-  tags, 
-  source,
-  content='memory_item',
-  content_rowid='id'
-);
-```
-
-#### 데이터베이스 최적화 서비스
-
-```typescript
-interface DatabaseOptimization {
-  // 자동 인덱스 추천
-  recommendIndexes(): IndexRecommendation[] {
-    const slowQueries = this.analyzeSlowQueries();
-    return slowQueries.map(query => this.generateIndexRecommendation(query));
-  }
-  
-  // 쿼리 성능 분석
-  analyzeQueryPerformance(): QueryAnalysis {
-    return {
-      averageQueryTime: this.getAverageQueryTime(),
-      slowQueries: this.getSlowQueries(),
-      indexUsage: this.getIndexUsage(),
-      recommendations: this.generateRecommendations()
-    };
-  }
-}
-```
-
-#### 연결 풀 관리
-
-```typescript
-interface ConnectionPool {
-  private pool: DatabaseConnection[] = [];
-  private maxConnections: number = 20;
-  
-  async getConnection(): Promise<DatabaseConnection> {
-    if (this.pool.length > 0) {
-      return this.pool.pop()!;
-    }
-    
-    if (this.activeConnections < this.maxConnections) {
-      return await this.createConnection();
-    }
-    
-    return await this.waitForConnection();
-  }
-  
-  releaseConnection(conn: DatabaseConnection): void {
-    if (this.pool.length < this.maxConnections) {
-      this.pool.push(conn);
-    } else {
-      conn.close();
-    }
-  }
-}
-```
-
-## 보안 아키텍처
-
-### 1. 인증 및 권한
-
-#### JWT 기반 인증 (M3+)
-
-```typescript
-interface JWTAuthentication {
-  generateToken(user: User): string {
-    const payload = {
-      sub: user.id,
-      email: user.email,
-      role: user.role,
-      exp: Math.floor(Date.now() / 1000) + (60 * 60 * 24) // 24시간
-    };
-    
-    return jwt.sign(payload, this.secretKey, { algorithm: 'HS256' });
-  }
-  
-  verifyToken(token: string): UserPayload {
-    return jwt.verify(token, this.secretKey) as UserPayload;
-  }
-}
-```
-
-#### RBAC 권한 관리 (M4)
-
-```typescript
-interface RBAC {
-  hasPermission(user: User, resource: string, action: string): boolean {
-    const role = this.getRole(user.role);
-    return role.permissions.some(p => 
-      p.resource === resource && p.actions.includes(action)
-    );
-  }
-  
-  checkMemoryAccess(user: User, memory: MemoryItem): boolean {
-    if (memory.privacy_scope === 'public') return true;
-    if (memory.privacy_scope === 'team' && user.team_id === memory.team_id) return true;
-    if (memory.privacy_scope === 'private' && user.id === memory.user_id) return true;
-    return false;
-  }
-}
-```
-
-### 2. 데이터 암호화
-
-#### 민감한 데이터 암호화
-
-```typescript
-interface DataEncryption {
-  encryptSensitiveData(data: string): string {
-    const cipher = crypto.createCipher('aes-256-gcm', this.encryptionKey);
-    let encrypted = cipher.update(data, 'utf8', 'hex');
-    encrypted += cipher.final('hex');
-    return encrypted;
-  }
-  
-  decryptSensitiveData(encryptedData: string): string {
-    const decipher = crypto.createDecipher('aes-256-gcm', this.encryptionKey);
-    let decrypted = decipher.update(encryptedData, 'hex', 'utf8');
-    decrypted += decipher.final('utf8');
-    return decrypted;
-  }
-}
-```
-
-#### 전송 중 암호화
-
-```typescript
-interface TransportEncryption {
-  // HTTPS 강제
-  enforceHTTPS(): void {
-    this.app.use((req, res, next) => {
-      if (!req.secure && req.get('x-forwarded-proto') !== 'https') {
-        return res.redirect(`https://${req.get('host')}${req.url}`);
-      }
-      next();
-    });
-  }
-  
-  // HSTS 헤더 설정
-  setHSTS(): void {
-    this.app.use((req, res, next) => {
-      res.setHeader('Strict-Transport-Security', 'max-age=31536000; includeSubDomains');
-      next();
-    });
-  }
-}
-```
-
-### 3. 감사 로깅
-
-#### 보안 이벤트 로깅
-
-```typescript
-interface SecurityAudit {
-  logSecurityEvent(event: SecurityEvent): void {
-    const logEntry = {
-      timestamp: new Date().toISOString(),
-      event_type: event.type,
-      user_id: event.user_id,
-      ip_address: event.ip_address,
-      user_agent: event.user_agent,
-      details: event.details,
-      severity: event.severity
-    };
-    
-    this.auditLogger.info(logEntry);
-  }
-  
-  detectAnomalies(): void {
-    // 비정상적인 접근 패턴 감지
-    const recentEvents = this.getRecentEvents(5 * 60 * 1000); // 5분
-    const suspiciousEvents = this.analyzePatterns(recentEvents);
-    
-    if (suspiciousEvents.length > 0) {
-      this.alertSecurityTeam(suspiciousEvents);
-    }
-  }
-}
-```
-
-## 모니터링 및 관측성
-
-### 1. 메트릭 수집
-
-#### Prometheus 메트릭
-
-```typescript
-interface Metrics {
-  // 메모리 관련 메트릭
-  memoryCounter: Counter<string>;
-  memorySize: Gauge<string>;
-  
-  // 검색 관련 메트릭
-  searchDuration: Histogram<string>;
-  searchResults: Counter<string>;
-  
-  // 에러 관련 메트릭
-  errorCounter: Counter<string>;
-  errorRate: Gauge<string>;
-  
-  // 성능 관련 메트릭
-  responseTime: Histogram<string>;
-  throughput: Counter<string>;
-}
-```
-
-### 2. 로깅
-
-#### 구조화된 로깅
-
-```typescript
-interface StructuredLogging {
-  logMemoryOperation(operation: string, memoryId: string, userId?: string): void {
-    this.logger.info({
-      operation,
-      memory_id: memoryId,
-      user_id: userId,
-      timestamp: new Date().toISOString(),
-      level: 'info'
-    });
-  }
-  
-  logSearchQuery(query: string, resultCount: number, duration: number): void {
-    this.logger.info({
-      event: 'search_query',
-      query,
-      result_count: resultCount,
-      duration_ms: duration,
-      timestamp: new Date().toISOString()
-    });
-  }
-}
-```
-
-### 3. 헬스 체크
-
-#### 서비스 상태 모니터링
-
-```typescript
-interface HealthCheck {
-  async checkHealth(): Promise<HealthStatus> {
-    const checks = await Promise.allSettled([
-      this.checkDatabase(),
-      this.checkRedis(),
-      this.checkSearchIndex(),
-      this.checkMemoryUsage()
-    ]);
-    
-    return {
-      status: checks.every(c => c.status === 'fulfilled') ? 'healthy' : 'unhealthy',
-      checks: checks.map((check, index) => ({
-        name: this.checkNames[index],
-        status: check.status === 'fulfilled' ? 'ok' : 'error',
-        details: check.status === 'fulfilled' ? check.value : check.reason
-      }))
-    };
-  }
-}
-```
-
-## 확장성 고려사항
-
-### 1. 수평적 확장
-
-#### 샤딩 전략
-
-```typescript
-interface ShardingStrategy {
-  getShard(memoryId: string): string {
-    const hash = this.hash(memoryId);
-    return `shard_${hash % this.shardCount}`;
-  }
-  
-  routeQuery(query: string): string[] {
-    // 쿼리를 모든 샤드에 전송
-    return this.shards.map(shard => `${shard}/search`);
-  }
-}
-```
-
-### 2. 캐싱 전략
-
-#### 다층 캐싱
-
-```typescript
-interface MultiLevelCache {
-  async get(key: string): Promise<any> {
-    // L1: 메모리 캐시
-    let value = this.memoryCache.get(key);
-    if (value) return value;
-    
-    // L2: Redis 캐시
-    value = await this.redis.get(key);
-    if (value) {
-      this.memoryCache.set(key, value);
-      return value;
-    }
-    
-    // L3: 데이터베이스
-    value = await this.database.get(key);
-    if (value) {
-      this.memoryCache.set(key, value);
-      await this.redis.setex(key, 3600, value);
-      return value;
-    }
-    
-    return null;
-  }
-}
-```
-
-이 아키텍처 문서는 Memento MCP Server의 전체적인 구조와 설계 원칙을 설명합니다. 각 컴포넌트의 상세한 구현은 개별 개발 문서를 참조하세요.