memento-mcp-server 0.1.0

package/docs/ko/embedding-api-reference.md

@@ -0,0 +1,122 @@
+# 임베딩 서비스 API 레퍼런스
+
+## UnifiedEmbeddingService
+
+통합 임베딩 서비스의 메인 클래스입니다.
+
+### 생성자
+
+```typescript
+new UnifiedEmbeddingService()
+```
+
+### 메서드
+
+#### generateEmbedding(text, preferredProvider?)
+
+텍스트를 임베딩 벡터로 변환합니다.
+
+**매개변수:**
+- `text: string` - 변환할 텍스트
+- `preferredProvider?: EmbeddingProvider` - 선호하는 제공자 (선택사항)
+
+**반환값:**
+```typescript
+Promise<EmbeddingResult | null>
+```
+
+**예시:**
+```typescript
+const result = await service.generateEmbedding('안녕하세요');
+console.log(result.embedding); // [0.1, 0.2, ...]
+console.log(result.model); // 'minilm'
+```
+
+#### searchSimilar(query, embeddings, limit?, threshold?)
+
+유사한 임베딩을 검색합니다.
+
+**매개변수:**
+- `query: string` - 검색 쿼리
+- `embeddings: EmbeddingData[]` - 검색할 임베딩 배열
+- `limit?: number` - 결과 개수 제한 (기본값: 10)
+- `threshold?: number` - 유사도 임계값 (기본값: 0.7)
+
+**반환값:**
+```typescript
+Promise<SimilarityResult[]>
+```
+
+**예시:**
+```typescript
+const results = await service.searchSimilar('React', memories, 5, 0.8);
+```
+
+#### isAvailable()
+
+서비스 사용 가능 여부를 확인합니다.
+
+**반환값:**
+```typescript
+boolean
+```
+
+#### getCurrentProviderName()
+
+현재 사용 중인 제공자 이름을 반환합니다.
+
+**반환값:**
+```typescript
+string
+```
+
+#### getModelInfo()
+
+현재 모델 정보를 반환합니다.
+
+**반환값:**
+```typescript
+{ model: string; dimensions: number; maxTokens: number }
+```
+
+## 타입 정의
+
+### EmbeddingResult
+
+```typescript
+interface EmbeddingResult {
+  embedding: number[];
+  model: string;
+  usage: {
+    prompt_tokens: number;
+    total_tokens: number;
+  };
+}
+```
+
+### SimilarityResult
+
+```typescript
+interface SimilarityResult {
+  id: string;
+  content: string;
+  similarity: number;
+  score: number;
+}
+```
+
+### EmbeddingData
+
+```typescript
+interface EmbeddingData {
+  id: string;
+  content: string;
+  embedding: number[];
+}
+```
+
+### EmbeddingProvider
+
+```typescript
+type EmbeddingProvider = 'tfidf' | 'minilm' | 'openai' | 'gemini';
+```

package/docs/ko/embedding-configuration.md

@@ -0,0 +1,62 @@
+# 임베딩 서비스 설정 가이드
+
+## 환경 변수 설정
+
+### 기본 설정
+
+```bash
+# .env 파일
+EMBEDDING_PROVIDER=minilm
+EMBEDDING_DIMENSIONS=384
+```
+
+### 제공자별 설정
+
+#### TF-IDF
+```bash
+EMBEDDING_PROVIDER=tfidf
+EMBEDDING_DIMENSIONS=512
+```
+
+#### MiniLM
+```bash
+EMBEDDING_PROVIDER=minilm
+EMBEDDING_DIMENSIONS=384
+```
+
+#### OpenAI
+```bash
+EMBEDDING_PROVIDER=openai
+OPENAI_API_KEY=your_api_key_here
+OPENAI_MODEL=text-embedding-3-small
+EMBEDDING_DIMENSIONS=1536
+```
+
+#### Gemini
+```bash
+EMBEDDING_PROVIDER=gemini
+GEMINI_API_KEY=your_api_key_here
+GEMINI_MODEL=text-embedding-004
+EMBEDDING_DIMENSIONS=768
+```
+
+## 설정 우선순위
+
+1. 명시적 제공자 지정
+2. 환경 변수 설정
+3. 기본값 (minilm)
+
+## 성능 튜닝
+
+### 메모리 최적화
+```bash
+# Node.js 힙 크기 증가
+NODE_OPTIONS="--max-old-space-size=4096"
+```
+
+### 캐시 설정
+```typescript
+// MiniLM 캐시 크기 조정
+const service = new MiniLMEmbeddingService();
+// 캐시는 자동으로 관리됨
+```

package/docs/ko/embedding-performance-benchmark.md

@@ -0,0 +1,62 @@
+# 임베딩 서비스 성능 벤치마크 결과
+
+## 개요
+
+Memento 프로젝트의 4가지 임베딩 제공자에 대한 성능 벤치마크 결과입니다.
+
+## 벤치마크 환경
+
+- **CPU**: Intel/AMD x64
+- **메모리**: 8GB+
+- **Node.js**: v20+
+- **테스트 데이터**: 10개 텍스트 샘플
+- **측정 항목**: 속도, 메모리 사용량, 성공률
+
+## 성능 결과 요약
+
+| 제공자 | 성공률 | 평균 속도 | 메모리 사용량 | 차원 | 비용 |
+|--------|--------|-----------|---------------|------|------|
+| **TF-IDF** | 100% | 0.82ms | 4.48MB | 512 | 무료 |
+| **MiniLM** | 100% | 56.50ms | 47.07MB | 384 | 무료 |
+| **통합** | 100% | 91.34ms | 25.91MB | 384 | 무료 |
+
+## 상세 분석
+
+### TF-IDF 제공자
+- **속도**: ⚡ 극도로 빠름 (0.82ms)
+- **메모리**: 💾 매우 효율적 (4.48MB)
+- **정확도**: 📊 키워드 기반 매칭
+- **추천 용도**: 대량 처리, 실시간 검색
+
+### MiniLM 제공자
+- **속도**: 🎯 균형잡힌 성능 (56.50ms)
+- **메모리**: 📈 중간 수준 (47.07MB)
+- **정확도**: 🧠 의미 이해 능력
+- **추천 용도**: 일반적인 AI Agent 용도
+
+### 통합 서비스
+- **속도**: 🔄 폴백 처리로 인한 오버헤드
+- **메모리**: 📊 여러 서비스 관리
+- **정확도**: 🎯 최적 제공자 자동 선택
+- **추천 용도**: 프로덕션 환경
+
+## 선택 가이드
+
+### 속도 우선
+**TF-IDF** - 0.82ms로 가장 빠름
+
+### 정확도 우선
+**MiniLM** - 의미 이해 능력과 속도의 균형
+
+### 안정성 우선
+**통합 서비스** - 자동 폴백으로 안정성 보장
+
+## 벤치마크 실행
+
+```bash
+# 전체 벤치마크
+npm run benchmark:embedding
+
+# 특정 서비스만
+npm run test:embedding-benchmark
+```

package/docs/ko/embedding-service-guide.md

@@ -0,0 +1,314 @@
+# 임베딩 서비스 사용 가이드
+
+## 개요
+
+Memento 프로젝트의 임베딩 서비스는 4가지 제공자를 지원하는 통합 시스템입니다:
+- **TF-IDF**: 빠른 속도, 512차원, 무료
+- **MiniLM**: 균형잡힌 성능, 384차원, 무료
+- **OpenAI**: 최고 성능, 1536차원, 유료
+- **Gemini**: 고성능, 768차원, 유료
+
+## 빠른 시작
+
+### 1. 기본 사용법
+
+```typescript
+import { UnifiedEmbeddingService } from './src/services/unified-embedding-service.js';
+
+const embeddingService = new UnifiedEmbeddingService();
+
+// 텍스트 임베딩 생성
+const result = await embeddingService.generateEmbedding('안녕하세요, Memento입니다!');
+console.log('임베딩 차원:', result.embedding.length);
+console.log('사용된 모델:', result.model);
+
+// 유사도 검색
+const memories = [
+  { id: '1', content: 'React Hook 사용법', embedding: [0.1, 0.2, ...] },
+  { id: '2', content: 'TypeScript 타입 정의', embedding: [0.3, 0.4, ...] }
+];
+
+const similar = await embeddingService.searchSimilar('React 관련 질문', memories, 5, 0.7);
+console.log('유사한 메모리:', similar);
+```
+
+### 2. 환경 설정
+
+`.env` 파일에 설정:
+
+```bash
+# 기본 임베딩 제공자 선택
+EMBEDDING_PROVIDER=minilm  # 옵션: tfidf, minilm, openai, gemini
+
+# OpenAI 설정 (선택사항)
+OPENAI_API_KEY=your_openai_api_key_here
+OPENAI_MODEL=text-embedding-3-small
+
+# Gemini 설정 (선택사항)
+GEMINI_API_KEY=your_gemini_api_key_here
+GEMINI_MODEL=text-embedding-004
+
+# 임베딩 차원 (자동 설정됨)
+EMBEDDING_DIMENSIONS=384  # MiniLM 기본값
+```
+
+## 제공자별 상세 가이드
+
+### TF-IDF 제공자
+
+**특징**:
+- ⚡ 극도로 빠른 속도 (0.82ms 평균)
+- 💾 낮은 메모리 사용량 (4.48MB)
+- 🆓 완전 무료
+- 📊 512차원 벡터
+
+**사용 시나리오**:
+- 대량 텍스트 처리
+- 실시간 검색
+- 리소스 제약 환경
+
+```typescript
+import { LightweightEmbeddingService } from './src/services/lightweight-embedding-service.js';
+
+const tfidfService = new LightweightEmbeddingService();
+const result = await tfidfService.generateEmbedding('빠른 처리가 필요한 텍스트');
+```
+
+### MiniLM 제공자
+
+**특징**:
+- 🎯 균형잡힌 성능 (56.50ms 평균)
+- 🧠 의미 이해 능력
+- 🆓 완전 무료
+- 📊 384차원 벡터
+
+**사용 시나리오**:
+- 일반적인 AI Agent 용도
+- 의미 기반 검색
+- 성능과 정확성의 균형
+
+```typescript
+import { MiniLMEmbeddingService } from './src/services/minilm-embedding-service.js';
+
+const minilmService = new MiniLMEmbeddingService();
+const result = await minilmService.generateEmbedding('의미를 이해해야 하는 텍스트');
+```
+
+### OpenAI 제공자
+
+**특징**:
+- 🏆 최고 성능
+- 🧠 뛰어난 의미 이해
+- 💰 유료 (API 비용)
+- 📊 1536차원 벡터
+
+**사용 시나리오**:
+- 고품질 임베딩 필요
+- 복잡한 의미 분석
+- 비용을 감수할 수 있는 경우
+
+```typescript
+// 환경 변수에 OPENAI_API_KEY 설정 필요
+const result = await embeddingService.generateEmbedding('고품질 임베딩이 필요한 텍스트');
+```
+
+### Gemini 제공자
+
+**특징**:
+- 🚀 고성능
+- 🌍 다국어 지원
+- 💰 유료 (API 비용)
+- 📊 768차원 벡터
+
+**사용 시나리오**:
+- 다국어 텍스트 처리
+- Google 생태계 활용
+- 고성능이 필요한 경우
+
+```typescript
+// 환경 변수에 GEMINI_API_KEY 설정 필요
+const result = await embeddingService.generateEmbedding('다국어 텍스트');
+```
+
+## 고급 사용법
+
+### 1. 제공자 직접 선택
+
+```typescript
+// 특정 제공자 강제 사용
+const result = await embeddingService.generateEmbedding(
+  '텍스트', 
+  'minilm'  // 제공자 명시
+);
+```
+
+### 2. 폴백 메커니즘
+
+```typescript
+// 폴백 제공자 설정
+embeddingService.setFallbackProviders(['minilm', 'tfidf']);
+
+// 기본 제공자 실패 시 자동으로 폴백 제공자 시도
+const result = await embeddingService.generateEmbedding('텍스트');
+```
+
+### 3. 서비스 상태 확인
+
+```typescript
+// 사용 가능 여부 확인
+if (embeddingService.isAvailable()) {
+  const result = await embeddingService.generateEmbedding('텍스트');
+}
+
+// 현재 사용 중인 제공자 확인
+const currentProvider = embeddingService.getCurrentProviderName();
+console.log('현재 제공자:', currentProvider);
+
+// 모델 정보 확인
+const modelInfo = embeddingService.getModelInfo();
+console.log('모델 정보:', modelInfo);
+```
+
+## 성능 최적화
+
+### 1. 배치 처리
+
+```typescript
+// 여러 텍스트를 동시에 처리
+const texts = ['텍스트1', '텍스트2', '텍스트3'];
+const results = await Promise.all(
+  texts.map(text => embeddingService.generateEmbedding(text))
+);
+```
+
+### 2. 캐싱 활용
+
+```typescript
+// MiniLM 서비스는 자동으로 캐싱됨
+const result1 = await minilmService.generateEmbedding('같은 텍스트'); // 모델 로딩
+const result2 = await minilmService.generateEmbedding('같은 텍스트'); // 캐시에서 반환
+```
+
+### 3. 메모리 관리
+
+```typescript
+// 대량 처리 시 메모리 정리
+for (const text of largeTextArray) {
+  const result = await embeddingService.generateEmbedding(text);
+  // 결과 처리
+  // 가비지 컬렉션을 위해 참조 해제
+}
+```
+
+## 에러 처리
+
+### 1. 기본 에러 처리
+
+```typescript
+try {
+  const result = await embeddingService.generateEmbedding('텍스트');
+} catch (error) {
+  if (error.message.includes('텍스트가 비어있습니다')) {
+    console.error('입력 텍스트를 확인해주세요');
+  } else if (error.message.includes('사용 가능한 제공자가 없습니다')) {
+    console.error('모든 임베딩 제공자가 사용 불가능합니다');
+  } else {
+    console.error('임베딩 생성 실패:', error.message);
+  }
+}
+```
+
+### 2. 제공자별 에러 처리
+
+```typescript
+try {
+  const result = await embeddingService.generateEmbedding('텍스트');
+} catch (error) {
+  // OpenAI API 에러
+  if (error.status === 429) {
+    console.error('API 할당량 초과');
+  } else if (error.status === 401) {
+    console.error('API 키가 유효하지 않습니다');
+  }
+  
+  // Gemini API 에러
+  if (error.message.includes('quota')) {
+    console.error('Gemini API 할당량 초과');
+  }
+}
+```
+
+## 테스트
+
+### 1. 단위 테스트
+
+```typescript
+import { describe, it, expect } from 'vitest';
+import { UnifiedEmbeddingService } from '../src/services/unified-embedding-service.js';
+
+describe('임베딩 서비스 테스트', () => {
+  it('텍스트 임베딩 생성', async () => {
+    const service = new UnifiedEmbeddingService();
+    const result = await service.generateEmbedding('테스트 텍스트');
+    
+    expect(result).toBeDefined();
+    expect(result.embedding).toBeInstanceOf(Array);
+    expect(result.embedding.length).toBeGreaterThan(0);
+  });
+});
+```
+
+### 2. 성능 벤치마크
+
+```bash
+# 벤치마크 실행
+npm run benchmark:embedding
+
+# 특정 서비스 테스트
+npm run test:embedding-benchmark
+```
+
+## 문제 해결
+
+### 1. 일반적인 문제
+
+**Q: MiniLM 모델 로딩이 느려요**
+A: 첫 번째 호출 시에만 모델을 로딩합니다. 이후 호출은 캐시에서 빠르게 처리됩니다.
+
+**Q: OpenAI API 에러가 발생해요**
+A: API 키가 올바른지, 할당량이 남아있는지 확인해주세요.
+
+**Q: 벡터 차원이 맞지 않아요**
+A: 각 제공자는 다른 차원을 사용합니다. 통합 서비스를 사용하면 자동으로 처리됩니다.
+
+### 2. 성능 문제
+
+**Q: 임베딩 생성이 너무 느려요**
+A: TF-IDF 제공자를 사용하거나, 배치 처리를 고려해보세요.
+
+**Q: 메모리 사용량이 많아요**
+A: MiniLM 모델이 메모리를 많이 사용합니다. TF-IDF를 사용하거나 서버 리소스를 늘려보세요.
+
+## 마이그레이션 가이드
+
+### 기존 코드에서 통합 서비스로 마이그레이션
+
+```typescript
+// 기존 코드
+import { EmbeddingService } from './src/services/embedding-service.js';
+const oldService = new EmbeddingService();
+
+// 새로운 코드
+import { UnifiedEmbeddingService } from './src/services/unified-embedding-service.js';
+const newService = new UnifiedEmbeddingService();
+
+// API는 동일하므로 코드 변경 최소화
+const result = await newService.generateEmbedding('텍스트');
+```
+
+## 추가 리소스
+
+- [성능 벤치마크 결과](./embedding-performance-benchmark.md)
+- [API 레퍼런스](./embedding-api-reference.md)
+- [설정 가이드](./embedding-configuration.md)
+- [문제 해결 FAQ](./embedding-troubleshooting.md)