memento-mcp-server 1.6.0 → 1.7.2

package/.cursor/rules/implementation.mdc

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

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