memento-mcp-server 0.1.0

package/.cursor/rules/project-structure.mdc

@@ -0,0 +1,310 @@
+---
+globs: *.ts,*.js,*.json
+description: 프로젝트 구조 및 파일 명명 규칙
+---
+
+# 프로젝트 구조 규칙
+
+## 📁 디렉토리 구조
+
+```
+memento/
+├── src/                    # 소스 코드
+│   ├── algorithms/        # 검색 및 망각 알고리즘
+│   │   ├── search-engine.ts        # 기본 검색 엔진 (233줄)
+│   │   ├── hybrid-search-engine.ts # 하이브리드 검색 엔진 (200줄)
+│   │   ├── search-ranking.ts       # 검색 랭킹 알고리즘
+│   │   ├── forgetting-algorithm.ts # 망각 알고리즘 (244줄)
+│   │   └── spaced-repetition.ts    # 간격 반복 알고리즘 (239줄)
+│   ├── client/            # MCP 클라이언트
+│   │   └── index.ts       # 클라이언트 진입점
+│   ├── config/            # 설정 관리
+│   │   └── index.ts       # 설정 파일
+│   ├── database/          # 데이터베이스 관련
+│   │   ├── init.ts        # 데이터베이스 초기화 (102줄)
+│   │   └── 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줄)
+│   │   ├── lightweight-embedding-service.ts # 경량 하이브리드 임베딩 서비스 (321줄)
+│   │   ├── gemini-embedding-service.ts # Gemini 임베딩 서비스
+│   │   ├── forgetting-policy-service.ts # 망각 정책 서비스 (335줄)
+│   │   ├── async-optimizer.ts          # 비동기 처리 최적화 (447줄)
+│   │   ├── cache-service.ts            # 캐시 서비스 (352줄)
+│   │   ├── database-optimizer.ts       # 데이터베이스 최적화 (442줄)
+│   │   ├── performance-monitor.ts      # 성능 모니터링 (367줄)
+│   │   ├── performance-alert-service.ts # 성능 알림 서비스
+│   │   ├── performance-monitoring-integration.ts # 성능 모니터링 통합
+│   │   └── error-logging-service.ts    # 에러 로깅 서비스
+│   ├── tools/             # MCP Tools 구현
+│   │   ├── base-tool.ts   # 기본 도구 클래스
+│   │   ├── remember-tool.ts # remember 도구
+│   │   ├── recall-tool.ts # recall 도구
+│   │   ├── pin-tool.ts    # pin 도구
+│   │   ├── unpin-tool.ts  # unpin 도구
+│   │   ├── forget-tool.ts # forget 도구
+│   │   ├── cleanup-memory-tool.ts # 메모리 정리 도구
+│   │   ├── database-optimize-tool.ts # 데이터베이스 최적화 도구
+│   │   ├── performance-stats-tool.ts # 성능 통계 도구
+│   │   ├── performance-alerts.ts # 성능 알림 도구
+│   │   ├── error-stats.ts # 에러 통계 도구
+│   │   ├── resolve-error.ts # 에러 해결 도구
+│   │   ├── forgetting-stats-tool.ts # 망각 통계 도구
+│   │   ├── tool-registry.ts # 도구 등록
+│   │   ├── types.ts       # 도구 타입 정의
+│   │   └── index.ts       # 도구 내보내기
+│   ├── types/             # TypeScript 타입 정의
+│   │   └── index.ts       # 공통 타입 정의
+│   ├── utils/             # 유틸리티 함수
+│   │   └── database.ts    # 데이터베이스 유틸리티
+│   ├── test/              # 테스트 디렉토리 (신규)
+│   │   └── performance-benchmark.ts # 성능 벤치마크 (497줄)
+│   ├── test-client.ts     # 클라이언트 테스트 (152줄)
+│   ├── test-search.ts     # 검색 테스트 (152줄)
+│   ├── test-embedding.ts  # 임베딩 테스트 (154줄)
+│   ├── test-lightweight-embedding.ts # 경량 임베딩 테스트
+│   ├── test-gemini-embedding.ts # Gemini 임베딩 테스트
+│   ├── test-forgetting.ts # 망각 정책 테스트 (163줄)
+│   ├── test-performance-monitoring.ts # 성능 모니터링 테스트 (172줄)
+│   ├── test-performance-alerts.ts # 성능 알림 테스트
+│   ├── test-error-logging.ts # 에러 로깅 테스트
+│   ├── test-simple-alerts.ts # 간단한 알림 테스트
+│   └── test-alerts-direct.ts # 직접 알림 테스트
+├── dist/                  # 빌드 결과물
+│   ├── algorithms/        # 컴파일된 알고리즘
+│   ├── client/           # 컴파일된 클라이언트
+│   ├── config/           # 컴파일된 설정
+│   ├── database/         # 컴파일된 데이터베이스
+│   ├── server/           # 컴파일된 서버
+│   ├── services/         # 컴파일된 서비스 (신규)
+│   ├── types/            # 컴파일된 타입
+│   └── utils/            # 컴파일된 유틸리티
+├── data/                 # 데이터 파일
+│   ├── memory.db         # SQLite 데이터베이스
+│   ├── memory.db-shm     # SQLite 공유 메모리
+│   └── memory.db-wal     # SQLite WAL 파일
+├── docs/                 # 문서
+├── .cursor/rules/        # Cursor 개발 규칙
+├── package.json          # 프로젝트 설정
+├── tsconfig.json         # TypeScript 설정
+├── vitest.config.ts      # Vitest 설정
+└── env.example           # 환경 변수 예시
+```
+
+## 📝 파일 명명 규칙
+
+### TypeScript 파일
+- **컴포넌트**: PascalCase (예: `MemoryManager.ts`)
+- **유틸리티**: kebab-case (예: `search-ranking.ts`)
+- **타입 정의**: `types.ts` 또는 `interfaces.ts`
+- **상수**: `constants.ts` 또는 `config.ts`
+
+### 테스트 파일
+- **단위 테스트**: `*.test.ts`
+- **통합 테스트**: `*.integration.test.ts`
+- **E2E 테스트**: `*.e2e.test.ts`
+- **픽스처**: `*.fixture.ts`
+- **테스트 스크립트**: `test-*.ts` (예: `test-client.ts`, `test-search.ts`)
+
+### 설정 파일
+- **환경별**: `.env.development`, `.env.production`
+- **빌드**: `webpack.config.js`, `tsconfig.json`
+- **Docker**: `Dockerfile`, `docker-compose.yml`
+
+## 🏗️ 모듈 구조
+
+### MCP 서버 모듈
+```typescript
+// src/server/tools/remember.ts
+export class RememberTool {
+  async execute(params: RememberParams): Promise<RememberResult> {
+    // 구현
+  }
+}
+
+// src/server/tools/index.ts
+export { RememberTool } from './remember';
+export { RecallTool } from './recall';
+// ... 다른 도구들
+```
+
+### 클라이언트 모듈
+```typescript
+// src/client/memory-manager.ts
+export class MemoryManager {
+  constructor(private client: MCPClient) {}
+  
+  async remember(content: string, options?: RememberOptions): Promise<string> {
+    // 구현
+  }
+}
+```
+
+### 알고리즘 모듈
+```typescript
+// src/algorithms/search-ranking.ts
+export class SearchRanking {
+  calculateScore(features: SearchFeatures): number {
+    // 구현
+  }
+}
+```
+
+## 🔗 의존성 관리
+
+### 내부 의존성
+- **서버 → 공통**: `src/server` → `src/shared`
+- **클라이언트 → 공통**: `src/client` → `src/shared`
+- **알고리즘 → 공통**: `src/algorithms` → `src/shared`
+
+### 외부 의존성
+- **MCP SDK**: `@modelcontextprotocol/sdk`
+- **데이터베이스**: `better-sqlite3` (M1), `pg` (M3+)
+- **벡터 검색**: `sqlite-vec` (M1), `pgvector` (M3+)
+- **테스트**: `jest`, `@types/jest`
+
+## 📦 패키지 구조
+
+### package.json 스크립트
+```json
+{
+  "scripts": {
+    "dev": "tsx watch src/server/index.ts",
+    "build": "tsc && npm run copy:assets",
+    "copy:assets": "powershell -Command \"if (!(Test-Path 'dist/database')) { New-Item -ItemType Directory -Path 'dist/database' -Force }; Copy-Item 'src/database/schema.sql' 'dist/database/' -Force\"",
+    "start": "node dist/server/index.js",
+    "test": "vitest",
+    "lint": "eslint src/**/*.ts",
+    "type-check": "tsc --noEmit",
+    "db:init": "tsx src/database/init.ts",
+    "db:migrate": "tsx src/database/migrate.ts",
+    "test:client": "tsx src/test-client.ts",
+    "test:search": "tsx src/test-search.ts"
+  }
+}
+```
+
+### TypeScript 설정
+```json
+{
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["src/*"],
+      "@/server/*": ["src/server/*"],
+      "@/client/*": ["src/client/*"],
+      "@/shared/*": ["src/shared/*"]
+    }
+  }
+}
+```
+
+## 🧪 테스트 구조
+
+### 단위 테스트
+```typescript
+// tests/unit/memory-manager.test.ts
+import { MemoryManager } from '@/client/memory-manager';
+
+describe('MemoryManager', () => {
+  let memoryManager: MemoryManager;
+  
+  beforeEach(() => {
+    // 테스트 설정
+  });
+  
+  it('should remember content', async () => {
+    // 테스트 구현
+  });
+});
+```
+
+### 통합 테스트
+```typescript
+// tests/integration/mcp-server.test.ts
+import { MCPClient } from '@modelcontextprotocol/sdk';
+
+describe('MCP Server Integration', () => {
+  let client: MCPClient;
+  
+  beforeAll(async () => {
+    // 서버 시작
+  });
+  
+  afterAll(async () => {
+    // 서버 종료
+  });
+});
+```
+
+## 🐳 Docker 구조
+
+### Dockerfile
+```dockerfile
+FROM node:20-alpine
+
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci --only=production
+
+COPY dist/ ./dist/
+EXPOSE 8080
+
+CMD ["node", "dist/server/index.js"]
+```
+
+### docker-compose.yml
+```yaml
+version: '3.8'
+services:
+  memento-server:
+    build: .
+    ports:
+      - "8080:8080"
+    environment:
+      - NODE_ENV=production
+    volumes:
+      - ./data:/app/data
+```
+
+## 📋 코드 조직 원칙
+
+### 1. 단일 책임 원칙
+- 각 모듈은 하나의 명확한 책임을 가져야 함
+- MCP Tools는 각각 독립적인 파일로 분리
+
+### 2. 의존성 역전
+- 구체적인 구현보다는 추상화에 의존
+- 인터페이스를 통한 느슨한 결합
+
+### 3. 설정 분리
+- 환경별 설정은 별도 파일로 관리
+- 하드코딩된 값은 상수로 분리
+
+### 4. 에러 처리
+- 각 레이어에서 적절한 에러 처리
+- 사용자 친화적인 에러 메시지
+
+### 5. 로깅
+- 구조화된 로깅 사용
+- 민감한 정보는 마스킹
+
+## 🔄 마이그레이션 가이드
+
+### M1 → M2
+- SQLite 서버 모드 전환
+- API Key 인증 추가
+- Docker 컨테이너화
+
+### M2 → M3
+- PostgreSQL 마이그레이션
+- JWT 인증 시스템
+- Docker Compose 구성
+
+### M3 → M4
+- 고가용성 구성
+- Kubernetes 배포
+- 모니터링 시스템