memento-mcp-server 0.1.0

package/.cursor/rules/implementation.mdc

@@ -0,0 +1,369 @@
+---
+globs: *.ts,*.js
+description: 실제 구현된 기능들에 대한 개발 규칙
+---
+
+# 실제 구현 규칙
+
+## 📋 현재 구현 상태
+
+### ✅ 구현 완료된 기능들
+
+#### 1. MCP 서버 (`src/server/index.ts`)
+- **파일 크기**: 432줄
+- **구현된 Tools**:
+  - `remember`: 기억 저장 (Zod 스키마 검증 포함)
+  - `recall`: 기억 검색 (필터링 지원)
+  - `forget`: 기억 삭제 (소프트/하드)
+  - `pin`/`unpin`: 기억 고정/해제
+- **에러 처리**: 구조화된 에러 응답
+- **로깅**: 상세한 로그 출력
+
+#### 2. 검색 엔진 (`src/algorithms/search-engine.ts`)
+- **파일 크기**: 233줄
+- **구현된 기능**:
+  - FTS5 텍스트 검색
+  - 검색 랭킹 알고리즘
+  - 필터링 시스템
+  - 결과 정렬 및 제한
+- **성능 최적화**: 인덱스 활용
+
+#### 3. 검색 랭킹 (`src/algorithms/search-ranking.ts`)
+- **구현된 알고리즘**:
+  - 관련성 계산
+  - 최근성 계산
+  - 중요도 계산
+  - 사용성 계산
+  - 중복 패널티 계산
+
+#### 4. 데이터베이스 (`src/database/init.ts`)
+- **파일 크기**: 102줄
+- **구현된 기능**:
+  - better-sqlite3 데이터베이스 초기화
+  - 스키마 생성
+  - 인덱스 설정
+  - 연결 관리
+
+#### 5. 클라이언트 (`src/client/index.ts`)
+- **구현된 기능**:
+  - MCP 서버 연결
+  - 기억 관리 API
+  - 에러 처리
+
+#### 6. 하이브리드 검색 엔진 (`src/algorithms/hybrid-search-engine.ts` - 200줄)
+- **FTS5 + 벡터 검색 결합**: 텍스트 검색과 벡터 검색을 결합한 하이브리드 검색
+- **가중치 조정**: 벡터 검색 60%, 텍스트 검색 40% (기본값)
+- **하이브리드 점수**: 텍스트 점수와 벡터 점수를 결합한 최종 점수
+
+#### 7. 임베딩 서비스 (`src/services/embedding-service.ts` - 196줄)
+- **OpenAI API 연동**: `text-embedding-3-small` 모델 사용
+- **벡터 변환**: 텍스트를 1536차원 벡터로 변환
+- **유사도 검색**: 코사인 유사도 기반 검색
+
+#### 8. 메모리 임베딩 서비스 (`src/services/memory-embedding-service.ts` - 237줄)
+- **임베딩 저장**: 메모리와 임베딩을 데이터베이스에 저장
+- **벡터 검색**: 저장된 임베딩을 활용한 유사도 검색
+- **자동 임베딩 생성**: 메모리 저장 시 자동으로 임베딩 생성
+
+#### 9. 망각 알고리즘 (`src/algorithms/forgetting-algorithm.ts` - 244줄)
+- **망각 점수 계산**: Memento-Goals.md의 망각 공식 구현
+- **특징 기반 망각**: 최근성, 사용성, 중복 비율, 중요도, 고정 여부 고려
+- **가중치 시스템**: U1-U5 계수를 사용한 망각 점수 계산
+
+#### 10. 간격 반복 알고리즘 (`src/algorithms/spaced-repetition.ts` - 239줄)
+- **간격 반복 스케줄링**: 중요도와 사용성 기반 리뷰 간격 계산
+- **리콜 확률 계산**: 시간 경과에 따른 기억 강도 측정
+- **동적 간격 조정**: 피드백에 따른 간격 배수 조정
+
+#### 11. 망각 정책 서비스 (`src/services/forgetting-policy-service.ts` - 335줄)
+- **통합 메모리 관리**: 망각 알고리즘과 간격 반복 통합
+- **TTL 기반 정책**: 타입별 수명 관리 (working, episodic, semantic, procedural)
+- **소프트/하드 삭제**: 단계적 삭제 정책
+
+#### 12. HTTP 서버 (`src/server/http-server.ts` - 551줄)
+- **Express 기반**: RESTful API 및 WebSocket 서버
+- **WebSocket 지원**: 실시간 통신을 위한 WebSocket 서버
+- **CORS 설정**: 웹 클라이언트 지원
+- **콘솔 로그 충돌 해결**: MCP 프로토콜과의 호환성 개선
+
+#### 13. 성능 최적화 서비스들
+- **비동기 처리 최적화** (`src/services/async-optimizer.ts` - 447줄):
+  - 워커 풀 관리 및 병렬 처리
+  - 우선순위 기반 작업 큐
+  - 배치 처리 및 재시도 로직
+  - 성능 최적화된 비동기 작업 처리
+
+- **캐시 서비스** (`src/services/cache-service.ts` - 352줄):
+  - LRU 캐시 구현 및 TTL 관리
+  - 검색 결과 캐싱 및 임베딩 캐싱
+  - 캐시 통계 수집 및 성능 모니터링
+  - 메모리 효율적인 캐시 관리
+
+- **데이터베이스 최적화** (`src/services/database-optimizer.ts` - 442줄):
+  - 자동 인덱스 추천 및 생성
+  - 쿼리 성능 분석 및 최적화
+  - 데이터베이스 성능 튜닝
+  - 통계 수집 및 성능 개선
+
+- **성능 모니터링** (`src/services/performance-monitor.ts` - 367줄):
+  - 실시간 메트릭 수집 및 분석
+  - 임계값 모니터링 및 알림
+  - 성능 리포트 생성 및 트렌드 분석
+  - 시스템 상태 모니터링
+
+- **경량 하이브리드 임베딩** (`src/services/lightweight-embedding-service.ts` - 321줄):
+  - TF-IDF + 키워드 매칭 기반 벡터화
+  - OpenAI API 없이 사용 가능한 fallback 솔루션
+  - 512차원 고정 벡터 생성
+  - 한국어/영어 불용어 제거 및 텍스트 전처리
+  - 코사인 유사도 기반 검색
+
+#### 14. 성능 벤치마크 및 테스트
+- **성능 벤치마크** (`src/test/performance-benchmark.ts` - 497줄):
+  - 종합 성능 벤치마크 시스템
+  - 메모리 저장, 검색, 캐시 성능 테스트
+  - 동시성 및 부하 테스트
+  - 메모리 사용량 및 성능 분석
+
+- **성능 모니터링 테스트** (`src/test-performance-monitoring.ts` - 172줄):
+  - 모니터링 도구 기능 검증
+  - 실시간 성능 지표 확인
+  - 통합 모니터링 시스템 테스트
+
+#### 15. 테스트 파일들
+- **`test-client.ts`**: 클라이언트 테스트 (152줄)
+- **`test-search.ts`**: 검색 기능 테스트 (152줄)
+- **`test-embedding.ts`**: 임베딩 기능 테스트 (154줄)
+- **`test-forgetting.ts`**: 망각 정책 테스트 (163줄)
+- **`test-performance-monitoring.ts`**: 성능 모니터링 테스트 (172줄)
+
+## 🏗️ 실제 아키텍처
+
+### 현재 구현된 구조
+```
+src/
+├── algorithms/        # 검색 알고리즘
+│   ├── search-engine.ts    # 메인 검색 엔진
+│   └── search-ranking.ts   # 랭킹 알고리즘
+├── client/           # MCP 클라이언트
+│   └── index.ts      # 클라이언트 구현
+├── config/           # 설정 관리
+│   └── index.ts      # 설정 파일
+├── database/         # 데이터베이스
+│   ├── init.ts       # 초기화 로직
+│   └── schema.sql    # SQLite 스키마
+├── server/           # MCP 서버
+│   ├── index.ts      # 서버 메인 (521줄)
+│   └── http-server.ts # HTTP/WebSocket 서버 (551줄)
+├── services/         # 서비스 레이어 (신규)
+│   ├── embedding-service.ts        # OpenAI 임베딩 서비스 (196줄)
+│   ├── memory-embedding-service.ts # 메모리 임베딩 서비스 (237줄)
+│   ├── forgetting-policy-service.ts # 망각 정책 서비스 (335줄)
+│   ├── async-optimizer.ts          # 비동기 처리 최적화 (447줄)
+│   ├── cache-service.ts            # 캐시 서비스 (352줄)
+│   ├── database-optimizer.ts       # 데이터베이스 최적화 (442줄)
+│   └── performance-monitor.ts      # 성능 모니터링 (367줄)
+├── types/            # 타입 정의
+│   └── index.ts      # 공통 타입
+├── utils/            # 유틸리티
+│   └── database.ts   # DB 유틸리티
+├── test/              # 테스트 디렉토리 (신규)
+│   └── performance-benchmark.ts # 성능 벤치마크 (497줄)
+├── test-client.ts    # 클라이언트 테스트
+├── test-search.ts    # 검색 테스트
+├── test-embedding.ts # 임베딩 테스트
+├── test-forgetting.ts # 망각 정책 테스트
+└── test-performance-monitoring.ts # 성능 모니터링 테스트 (172줄)
+```
+
+## 🔧 실제 사용 가능한 명령어
+
+### 개발 명령어
+```bash
+# 개발 서버 실행 (핫 리로드)
+npm run dev
+
+# 빌드 (TypeScript 컴파일 + 에셋 복사)
+npm run build
+
+# 프로덕션 실행
+npm run start
+
+# 타입 체크
+npm run type-check
+
+# 린트 검사
+npm run lint
+```
+
+### 테스트 명령어
+```bash
+# Vitest 테스트 실행
+npm run test
+
+# 클라이언트 테스트
+npm run test:client
+
+# 검색 기능 테스트
+npm run test:search
+
+# 임베딩 기능 테스트
+npm run test:embedding
+
+# 망각 정책 테스트
+npm run test:forgetting
+
+# 성능 모니터링 테스트
+npm run test:performance
+```
+
+### 데이터베이스 명령어
+```bash
+# 데이터베이스 초기화
+npm run db:init
+
+# 데이터베이스 마이그레이션
+npm run db:migrate
+```
+
+## 📦 실제 의존성
+
+### 프로덕션 의존성
+```json
+{
+  "@modelcontextprotocol/sdk": "^0.5.0",
+  "axios": "^1.12.2",
+  "better-sqlite3": "^12.4.1",
+  "cors": "^2.8.5",
+  "dotenv": "^16.3.1",
+  "express": "^5.1.0",
+  "openai": "^4.20.1",
+  "uuid": "^9.0.1",
+  "ws": "^8.18.3",
+  "zod": "^3.22.4"
+}
+```
+
+### 개발 의존성
+```json
+{
+  "@types/better-sqlite3": "^7.6.13",
+  "@types/cors": "^2.8.19",
+  "@types/express": "^5.0.3",
+  "@types/node": "^20.10.0",
+  "@types/uuid": "^9.0.7",
+  "@types/ws": "^8.18.1",
+  "@typescript-eslint/eslint-plugin": "^6.13.0",
+  "@typescript-eslint/parser": "^6.13.0",
+  "eslint": "^8.54.0",
+  "tsx": "^4.6.0",
+  "typescript": "^5.3.0",
+  "vitest": "^1.0.0"
+}
+```
+
+## 🧪 실제 테스트 구조
+
+### 테스트 파일들
+- **`test-client.ts`**: MCP 클라이언트 통합 테스트
+- **`test-search.ts`**: 검색 기능 상세 테스트
+- **Vitest 설정**: `vitest.config.ts`
+
+### 테스트 실행 방법
+```bash
+# 모든 테스트 실행 (Vitest)
+npm run test
+
+# 특정 테스트 실행
+npm run test:client
+npm run test:search
+npm run test:embedding
+npm run test:lightweight-embedding
+npm run test:forgetting
+npm run test:performance
+npm run test:monitoring
+
+# 테스트 감시 모드
+npm run test -- --watch
+```
+
+## 🔍 실제 검색 구현
+
+### 검색 엔진 특징
+- **FTS5 활용**: SQLite의 Full-Text Search
+- **랭킹 알고리즘**: 관련성, 최근성, 중요도, 사용성 종합
+- **필터링**: 타입, 태그, 시간 범위, 고정 여부
+- **성능 최적화**: 인덱스 기반 검색
+
+### 검색 쿼리 예시
+```typescript
+// 기본 검색
+const results = await searchEngine.search(db, {
+  query: "React Hook",
+  limit: 10
+});
+
+// 필터링된 검색
+const filteredResults = await searchEngine.search(db, {
+  query: "TypeScript",
+  filters: {
+    type: ['episodic', 'semantic'],
+    tags: ['programming'],
+    pinned: false
+  },
+  limit: 5
+});
+```
+
+## 🗄️ 실제 데이터베이스 구조
+
+### better-sqlite3 스키마
+- **`memory_item`**: 기억 아이템 테이블
+- **`memory_embedding`**: 임베딩 테이블
+- **`memory_tag`**: 태그 테이블
+- **`memory_item_tag`**: 기억-태그 관계 테이블
+- **`memory_link`**: 기억 간 관계 테이블
+- **`feedback_event`**: 피드백 이벤트 테이블
+- **`wm_buffer`**: 작업기억 버퍼 테이블
+
+### 인덱스
+- **FTS5**: 텍스트 검색용
+- **일반 인덱스**: 타입, 생성일, 중요도, 고정 여부
+- **복합 인덱스**: 사용자별, 프로젝트별 검색 최적화
+
+## 🚀 실제 배포 상태
+
+### 빌드 결과물
+- **`dist/`**: TypeScript 컴파일 결과
+- **소스맵**: `.js.map` 파일들
+- **타입 정의**: `.d.ts` 파일들
+- **에셋 복사**: `schema.sql` 등
+
+### 환경 설정
+- **`env.example`**: 환경 변수 예시
+- **`mcp.json`**: MCP 설정 파일
+- **`tsconfig.json`**: TypeScript 설정
+- **`vitest.config.ts`**: 테스트 설정
+
+## 📋 개발 가이드라인
+
+### 코드 작성 규칙
+1. **TypeScript 엄격 모드**: 모든 타입 명시
+2. **Zod 스키마**: 입력 검증 필수
+3. **에러 처리**: 구조화된 에러 응답
+4. **로깅**: 상세한 로그 출력
+5. **테스트**: 각 기능별 테스트 작성
+
+### 파일 구조 규칙
+1. **모듈 분리**: 기능별 파일 분리
+2. **타입 정의**: `types/index.ts`에 집중
+3. **유틸리티**: `utils/` 폴더에 공통 함수
+4. **설정**: `config/` 폴더에 설정 관리
+5. **테스트**: `test-*.ts` 형식으로 테스트 파일
+
+### 성능 고려사항
+1. **인덱스 활용**: 데이터베이스 쿼리 최적화
+2. **캐싱**: 검색 결과 캐싱 고려
+3. **배치 처리**: 대량 데이터 처리 시 배치 사용
+4. **메모리 관리**: 연결 풀 관리
+5. **에러 복구**: 데이터베이스 연결 실패 시 재시도

package/.cursor/rules/lightweight-embedding.mdc

@@ -0,0 +1,178 @@
+---
+globs: *lightweight-embedding*
+description: Memento 프로젝트의 경량 하이브리드 임베딩 서비스 개발 규칙입니다. TF-IDF + 키워드 매칭 기반 벡터화를 통해 OpenAI 없이도 임베딩 기능을 제공하는 fallback 솔루션의 가이드라인을 제공합니다.
+---
+
+# 경량 하이브리드 임베딩 서비스 개발 규칙
+
+## 🎯 개요
+
+경량 하이브리드 임베딩 서비스는 OpenAI API가 없을 때 사용하는 fallback 솔루션입니다. TF-IDF + 키워드 매칭 기반으로 512차원 고정 벡터를 생성하여 의미적 검색을 제공합니다.
+
+## 📁 파일 구조
+
+```
+src/services/
+├── lightweight-embedding-service.ts    # 메인 서비스 (321줄)
+└── test-lightweight-embedding.ts       # 테스트 파일
+```
+
+## 🔧 핵심 기능
+
+### 1. TF-IDF 벡터화
+- **차원**: 512차원 고정 벡터
+- **토큰화**: 한국어/영어 불용어 제거
+- **정규화**: 코사인 정규화 적용
+- **캐싱**: 24시간 TTL로 결과 캐싱
+
+### 2. 키워드 매칭
+- **BM25 스코어**: 키워드 가중치 계산
+- **태그 매칭**: 메타데이터 기반 보정
+- **타이틀 히트**: 제목 매칭 보너스
+
+### 3. 하이브리드 점수 계산
+```typescript
+finalScore = (tfidfScore * 0.6) + (keywordScore * 0.4)
+```
+
+## 🛠️ 개발 가이드라인
+
+### 서비스 인터페이스
+```typescript
+interface LightweightEmbeddingService {
+  // 임베딩 생성
+  generateEmbedding(text: string): Promise<number[]>;
+  
+  // 유사도 계산
+  calculateSimilarity(embedding1: number[], embedding2: number[]): number;
+  
+  // 검색 점수 계산
+  calculateSearchScore(query: string, content: string, tags?: string[]): number;
+}
+```
+
+### 텍스트 전처리
+```typescript
+// 한국어/영어 불용어 제거
+const stopWords = ['의', '을', '를', '이', '가', '은', '는', 'the', 'a', 'an', 'and', 'or'];
+
+// 토큰화 및 정규화
+const tokens = text
+  .toLowerCase()
+  .replace(/[^\w\s가-힣]/g, ' ')
+  .split(/\s+/)
+  .filter(token => token.length > 1 && !stopWords.includes(token));
+```
+
+### 벡터 생성
+```typescript
+// TF-IDF 계산
+const tf = calculateTermFrequency(tokens);
+const idf = calculateInverseDocumentFrequency(tokens, corpus);
+const tfidf = tf.map((freq, index) => freq * idf[index]);
+
+// 512차원으로 패딩/트런케이트
+const vector = padOrTruncate(tfidf, 512);
+
+// 코사인 정규화
+const normalizedVector = cosineNormalize(vector);
+```
+
+## 📊 성능 최적화
+
+### 1. 캐싱 전략
+- **임베딩 캐시**: 24시간 TTL
+- **IDF 캐시**: 7일 TTL
+- **어휘 캐시**: 30일 TTL
+
+### 2. 메모리 관리
+- **벡터 풀**: 재사용 가능한 벡터 배열
+- **가비지 컬렉션**: 주기적 메모리 정리
+- **스트리밍**: 대용량 텍스트 처리
+
+### 3. 병렬 처리
+- **워커 스레드**: CPU 집약적 작업 분리
+- **배치 처리**: 여러 텍스트 동시 처리
+- **비동기 처리**: 논블로킹 I/O
+
+## 🧪 테스트 가이드라인
+
+### 단위 테스트
+```typescript
+describe('LightweightEmbeddingService', () => {
+  it('should generate consistent embeddings', async () => {
+    const service = new LightweightEmbeddingService();
+    const text = 'React Hook 사용법';
+    
+    const embedding1 = await service.generateEmbedding(text);
+    const embedding2 = await service.generateEmbedding(text);
+    
+    expect(embedding1).toEqual(embedding2);
+  });
+  
+  it('should calculate similarity correctly', async () => {
+    const service = new LightweightEmbeddingService();
+    const text1 = 'React Hook 사용법';
+    const text2 = 'React Hook 활용 방법';
+    
+    const embedding1 = await service.generateEmbedding(text1);
+    const embedding2 = await service.generateEmbedding(text2);
+    const similarity = service.calculateSimilarity(embedding1, embedding2);
+    
+    expect(similarity).toBeGreaterThan(0.7);
+  });
+});
+```
+
+### 통합 테스트
+```typescript
+describe('LightweightEmbedding Integration', () => {
+  it('should work as fallback for OpenAI', async () => {
+    // OpenAI API 실패 시나리오
+    const embeddingService = new EmbeddingService();
+    const lightweightService = new LightweightEmbeddingService();
+    
+    // 자동 fallback 테스트
+    const result = await embeddingService.generateEmbedding('test text');
+    expect(result).toBeDefined();
+  });
+});
+```
+
+## 🔍 디버깅 가이드
+
+### 로그 레벨
+- **DEBUG**: 벡터 생성 과정
+- **INFO**: 캐시 히트/미스
+- **WARN**: 성능 저하 경고
+- **ERROR**: 임베딩 생성 실패
+
+### 성능 메트릭
+- **처리 시간**: 평균 임베딩 생성 시간
+- **메모리 사용량**: 벡터 저장소 크기
+- **캐시 히트율**: 캐시 효율성
+- **정확도**: 검색 결과 품질
+
+## 🚀 배포 고려사항
+
+### 환경 변수
+```bash
+# 경량 임베딩 설정
+LIGHTWEIGHT_EMBEDDING_ENABLED=true
+LIGHTWEIGHT_EMBEDDING_DIMENSION=512
+LIGHTWEIGHT_EMBEDDING_CACHE_TTL=86400
+LIGHTWEIGHT_EMBEDDING_WORKER_THREADS=4
+```
+
+### 모니터링
+- **CPU 사용률**: 벡터 계산 부하
+- **메모리 사용량**: 캐시 크기 모니터링
+- **응답 시간**: 임베딩 생성 지연
+- **에러율**: 처리 실패 비율
+
+## 📚 참고 자료
+
+- [TF-IDF 알고리즘](https://en.wikipedia.org/wiki/Tf%E2%80%93idf)
+- [BM25 랭킹 함수](https://en.wikipedia.org/wiki/Okapi_BM25)
+- [코사인 유사도](https://en.wikipedia.org/wiki/Cosine_similarity)
+- [Node.js Worker Threads](https://nodejs.org/api/worker_threads.html)