memento-mcp-server 1.6.0 → 1.7.2

package/docs/ko/developer-guide.md

@@ -1,1006 +0,0 @@
-# 개발자 가이드
-
-## 개요
-
-이 가이드는 Memento MCP Server의 개발 환경 설정, 아키텍처 이해, 기여 방법을 설명합니다.
-
-## 목차
-
-1. [개발 환경 설정](#개발-환경-설정)
-2. [프로젝트 구조](#프로젝트-구조)
-3. [아키텍처 이해](#아키텍처-이해)
-4. [개발 워크플로우](#개발-워크플로우)
-5. [테스트 작성](#테스트-작성)
-6. [기여 방법](#기여-방법)
-
-## 개발 환경 설정
-
-### 필수 요구사항
-
-- **Node.js**: 20.0.0 이상 (package.json 기준)
-- **npm**: 10.0.0 이상
-
-### 저장소 가이드라인 (`AGENTS.md`)
-
-프로젝트에는 개발자 가이드라인이 포함되어 있습니다:
-
-- **프로젝트 구조**: `src/` 하위 모듈별 조직화
-- **빌드/테스트 명령어**: `npm run dev`, `npm run build`, `npm run test` 등
-- **코딩 스타일**: Node.js ≥ 20, TypeScript ES 모듈, 2칸 들여쓰기
-- **테스트 가이드라인**: Vitest 기반, `src/test/` 또는 `*.spec.ts` 파일
-- **커밋/PR 가이드라인**: Conventional Commits, 한국어 컨텍스트 포함
-- **환경/데이터베이스**: `.env` 설정, `data/` 폴더 관리
-- **TypeScript**: 5.3.0 (실제 구현 기준)
-- **Git**: 2.30.0 이상
-
-### 개발 도구
-
-- **IDE**: VS Code (권장)
-- **확장 프로그램**:
-  - TypeScript and JavaScript Language Features
-  - ESLint
-  - Prettier
-  - Vitest (실제 사용)
-  - GitLens
-
-### 환경 설정
-
-#### 1. 저장소 클론
-
-```bash
-git clone https://github.com/your-org/memento.git
-cd memento
-```
-
-#### 2. 의존성 설치
-
-```bash
-# 모든 의존성 설치 (package.json 기준)
-npm install
-
-# 실제 사용된 의존성들:
-# - @modelcontextprotocol/sdk: ^0.5.0
-# - better-sqlite3: ^12.4.1
-# - express: ^5.1.0
-# - cors: ^2.8.5
-# - ws: ^8.18.3
-# - zod: ^3.22.4
-# - uuid: ^9.0.1
-# - openai: ^4.20.1
-# - dotenv: ^16.3.1
-# - vitest: ^1.0.0 (테스트)
-# - tsx: ^4.6.0 (개발)
-```
-
-#### 3. 환경 변수 설정
-
-```bash
-# 환경 변수 파일 복사
-cp .env.example .env
-
-# 환경 변수 편집
-# .env 파일을 편집하여 필요한 설정을 입력하세요
-```
-
-#### 4. 데이터베이스 초기화
-
-```bash
-# better-sqlite3 데이터베이스 초기화
-npm run db:init
-
-# 데이터베이스 마이그레이션
-npm run db:migrate
-```
-
-#### 5. 개발 서버 시작
-
-```bash
-# MCP 서버 개발 모드 (핫 리로드)
-npm run dev
-
-# HTTP/WebSocket 서버 개발 모드
-npm run dev:http
-
-# 별도 터미널에서 테스트 실행
-npm run test -- --watch
-```
-
-### VS Code 설정
-
-#### .vscode/settings.json
-
-```json
-{
-  "typescript.preferences.importModuleSpecifier": "relative",
-  "editor.formatOnSave": true,
-  "editor.codeActionsOnSave": {
-    "source.fixAll.eslint": true
-  },
-  "vitest.commandLine": "npm run test",
-  "vitest.autoRun": "watch"
-}
-```
-
-#### .vscode/launch.json
-
-```json
-{
-  "version": "0.2.0",
-  "configurations": [
-    {
-      "name": "Debug MCP Server",
-      "type": "node",
-      "request": "launch",
-      "program": "${workspaceFolder}/src/server/index.ts",
-      "outFiles": ["${workspaceFolder}/dist/**/*.js"],
-      "env": {
-        "NODE_ENV": "development"
-      },
-      "console": "integratedTerminal"
-    },
-    {
-      "name": "Debug Tests",
-      "type": "node",
-      "request": "launch",
-      "program": "${workspaceFolder}/node_modules/.bin/vitest",
-      "args": ["--run"],
-      "console": "integratedTerminal",
-      "internalConsoleOptions": "neverOpen"
-    }
-  ]
-}
-```
-
-## 프로젝트 구조
-
-### 새로운 서비스 레이어 (`src/services/`)
-
-Memento는 새로운 서비스 레이어를 도입하여 외부 API 연동과 복잡한 비즈니스 로직을 분리했습니다.
-
-```
-src/services/
-├── embedding-service.ts              # OpenAI 임베딩 서비스 (196줄)
-├── memory-embedding-service.ts       # 메모리 임베딩 서비스 (237줄)
-├── lightweight-embedding-service.ts  # 경량 하이브리드 임베딩 서비스 (321줄)
-├── forgetting-policy-service.ts      # 망각 정책 서비스 (335줄)
-├── async-optimizer.ts                # 비동기 처리 최적화 (447줄)
-├── cache-service.ts                  # 캐시 서비스 (352줄)
-├── database-optimizer.ts             # 데이터베이스 최적화 (442줄)
-└── performance-monitor.ts            # 성능 모니터링 (367줄)
-```
-
-**서비스 레이어의 역할**:
-- **외부 API 연동**: OpenAI API, 데이터베이스 연동
-- **비즈니스 로직**: 임베딩 생성, 벡터 검색, 유사도 계산
-- **에러 처리**: API 호출 실패, 재시도 로직
-- **캐싱**: 임베딩 결과 캐싱, 성능 최적화
-- **Fallback 솔루션**: 경량 하이브리드 임베딩 서비스로 OpenAI API 대체
-- **성능 최적화**: 비동기 처리, 캐시 관리, 데이터베이스 최적화
-- **모니터링**: 실시간 성능 메트릭 수집 및 분석
-
-### 하이브리드 검색 엔진 (`src/algorithms/hybrid-search-engine.ts`)
-
-기존 검색 엔진에 하이브리드 검색 기능이 추가되었습니다.
-
-```
-src/algorithms/
-├── search-engine.ts        # 기본 검색 엔진 (233줄)
-├── hybrid-search-engine.ts # 하이브리드 검색 엔진 (200줄)
-└── search-ranking.ts       # 검색 랭킹 알고리즘
-```
-
-**하이브리드 검색의 특징**:
-- **FTS5 + 벡터 검색**: 텍스트 검색과 벡터 검색 결합
-- **가중치 조정**: 벡터 60%, 텍스트 40% (기본값)
-- **점수 정규화**: 0-1 범위로 점수 정규화
-- **결과 결합**: 두 검색 결과를 통합한 최종 점수
-
-### 전체 프로젝트 구조
-
-```
-memento/
-├── src/                          # 소스 코드
-│   ├── server/                   # MCP 서버
-│   │   ├── index.ts             # 서버 진입점 (521줄)
-│   │   ├── tools/               # MCP Tools 구현
-│   │   │   ├── remember.ts      # remember 도구
-│   │   │   ├── recall.ts        # recall 도구
-│   │   │   ├── pin.ts           # pin/unpin 도구
-│   │   │   ├── forget.ts        # forget 도구
-│   │   │   ├── summarize-thread.ts
-│   │   │   ├── link.ts          # link 도구
-│   │   │   ├── export.ts        # export 도구
-│   │   │   ├── feedback.ts      # feedback 도구
-│   │   │   └── index.ts         # 도구 내보내기
-│   │   ├── resources/           # MCP Resources 구현
-│   │   │   ├── memory.ts        # memory/{id} 리소스
-│   │   │   ├── search.ts        # memory/search 리소스
-│   │   │   └── index.ts
-│   │   ├── prompts/             # MCP Prompts 구현
-│   │   │   ├── memory-injection.ts
-│   │   │   └── index.ts
-│   │   ├── database/            # 데이터베이스 관련
-│   │   │   ├── sqlite.ts        # SQLite 구현
-│   │   │   ├── postgres.ts      # PostgreSQL 구현
-│   │   │   ├── migrations/      # 마이그레이션
-│   │   │   └── index.ts
-│   │   └── middleware/          # 미들웨어
-│   │       ├── auth.ts          # 인증 미들웨어
-│   │       ├── logging.ts       # 로깅 미들웨어
-│   │       └── error.ts         # 에러 처리 미들웨어
-│   ├── client/                  # MCP 클라이언트
-│   │   ├── index.ts             # 클라이언트 진입점
-│   │   ├── memory-manager.ts    # 메모리 관리자
-│   │   ├── mcp-client.ts        # MCP 클라이언트 래퍼
-│   │   └── types.ts             # 클라이언트 타입
-│   ├── algorithms/              # 검색 및 망각 알고리즘
-│   │   ├── search-ranking.ts    # 검색 랭킹 알고리즘
-│   │   ├── forgetting.ts        # 망각 알고리즘
-│   │   ├── spaced-review.ts     # 간격 반복 알고리즘
-│   │   └── index.ts
-│   └── shared/                  # 공통 유틸리티
-│       ├── types.ts             # 공통 타입 정의
-│       ├── utils.ts             # 유틸리티 함수
-│       ├── constants.ts         # 상수 정의
-│       └── validation.ts        # 검증 함수
-├── src/                         # 소스 코드
-│   ├── algorithms/             # 알고리즘 모듈
-│   │   ├── search-engine.ts
-│   │   ├── search-engine.spec.ts    # 단위 테스트
-│   │   ├── forgetting-algorithm.ts
-│   │   └── forgetting-algorithm.spec.ts  # 단위 테스트
-│   ├── services/               # 서비스 모듈
-│   │   ├── embedding-service.ts
-│   │   └── forgetting-policy-service.spec.ts  # 단위 테스트
-│   ├── test/                   # E2E 테스트
-│   │   ├── test-client.ts      # 클라이언트 E2E 테스트
-│   │   ├── test-search.ts      # 검색 E2E 테스트
-│   │   └── test-embedding.ts   # 임베딩 E2E 테스트
-│   └── fixtures/               # 테스트 데이터 (필요시)
-│       └── test-data.json      # 샘플 테스트 데이터
-├── docs/                       # 문서
-├── scripts/                    # 빌드 및 배포 스크립트
-│   ├── build.js               # 빌드 스크립트
-│   ├── deploy.js              # 배포 스크립트
-│   └── db-migrate.js          # 데이터베이스 마이그레이션
-├── docker/                     # Docker 관련 파일
-│   ├── Dockerfile             # M1 Dockerfile
-│   ├── Dockerfile.m3          # M3 Dockerfile
-│   ├── docker-compose.dev.yml # 개발 환경
-│   ├── docker-compose.team.yml # 팀 환경
-│   └── docker-compose.org.yml # 조직 환경
-├── .cursor/rules/              # Cursor 개발 규칙
-├── .github/                    # GitHub Actions
-│   └── workflows/
-│       ├── ci.yml             # CI 파이프라인
-│       ├── test.yml           # 테스트 파이프라인
-│       └── deploy.yml         # 배포 파이프라인
-├── package.json               # 프로젝트 설정
-├── tsconfig.json              # TypeScript 설정
-├── jest.config.js             # Jest 설정
-├── .eslintrc.js               # ESLint 설정
-├── .prettierrc                # Prettier 설정
-└── README.md                  # 프로젝트 문서
-```
-
-## 아키텍처 이해
-
-### 전체 아키텍처
-
-```mermaid
-graph TB
-    subgraph "AI Agent Layer"
-        A[Claude Desktop] --> B[MCP Client]
-        C[ChatGPT] --> B
-        D[Cursor] --> B
-    end
-    
-    subgraph "MCP Protocol Layer"
-        B --> E[MCP Memory Server]
-    end
-    
-    subgraph "Memory Management Layer"
-        E --> F[Memory Manager]
-        E --> G[Search Engine]
-        E --> H[Forgetting Policy]
-    end
-    
-    subgraph "Storage Layer"
-        F --> I[SQLite M1]
-        F --> J[PostgreSQL M3+]
-        G --> K[Vector Search]
-        G --> L[Text Search]
-    end
-```
-
-### 핵심 컴포넌트
-
-#### 1. MCP 서버 (`src/server/`)
-
-MCP 프로토콜을 구현하는 핵심 서버입니다.
-
-**주요 파일**:
-- `index.ts`: 서버 진입점, MCP 서버 초기화
-- `tools/`: MCP Tools 구현
-- `resources/`: MCP Resources 구현
-- `prompts/`: MCP Prompts 구현
-
-**예시 코드**:
-```typescript
-// src/server/index.ts
-import { Server } from '@modelcontextprotocol/sdk/server';
-import { rememberTool } from './tools/remember';
-import { recallTool } from './tools/recall';
-
-const server = new Server({
-  name: 'memento-memory-server',
-  version: '0.1.0'
-});
-
-// Tools 등록
-server.tool('remember', rememberTool);
-server.tool('recall', recallTool);
-
-// 서버 시작
-server.start();
-```
-
-#### 2. 검색 엔진 (`src/algorithms/`)
-
-기억 검색을 위한 알고리즘을 구현합니다.
-
-**주요 파일**:
-- `search-ranking.ts`: 검색 랭킹 알고리즘
-- `forgetting.ts`: 망각 알고리즘
-- `spaced-review.ts`: 간격 반복 알고리즘
-
-**예시 코드**:
-```typescript
-// src/algorithms/search-ranking.ts
-export class SearchRanking {
-  calculateFinalScore(features: SearchFeatures): number {
-    return this.ALPHA * features.relevance +
-           this.BETA * features.recency +
-           this.GAMMA * features.importance +
-           this.DELTA * features.usage -
-           this.EPSILON * features.duplication_penalty;
-  }
-}
-```
-
-#### 3. 데이터베이스 레이어 (`src/server/database/`)
-
-데이터 저장 및 검색을 담당합니다.
-
-**주요 파일**:
-- `sqlite.ts`: SQLite 구현 (M1)
-- `postgres.ts`: PostgreSQL 구현 (M3+)
-- `migrations/`: 데이터베이스 마이그레이션
-
-### 데이터 플로우
-
-#### 1. 기억 저장 플로우
-
-```
-AI Agent → MCP Client → MCP Server → Memory Manager → Database
-```
-
-#### 2. 기억 검색 플로우
-
-```
-AI Agent → MCP Client → MCP Server → Search Engine → Database → Ranking → Results
-```
-
-## 개발 워크플로우
-
-### 1. 기능 개발
-
-#### 브랜치 생성
-
-```bash
-# 기능 브랜치 생성
-git checkout -b feature/new-tool
-
-# 또는 버그 수정 브랜치
-git checkout -b fix/memory-leak
-```
-
-#### 개발 진행
-
-```bash
-# 개발 서버 시작
-npm run dev
-
-# 테스트 실행 (별도 터미널)
-npm run test:watch
-
-# 코드 포맷팅
-npm run format
-
-# 린트 검사
-npm run lint
-```
-
-#### 커밋
-
-```bash
-# 변경사항 스테이징
-git add .
-
-# 커밋 (컨벤셔널 커밋 형식)
-git commit -m "feat: add new summarize_thread tool"
-
-# 푸시
-git push origin feature/new-tool
-```
-
-### 2. 테스트 작성
-
-#### 단위 테스트
-
-```typescript
-// tests/unit/tools/remember.test.ts
-import { RememberTool } from '@/server/tools/remember';
-import { MockDatabase } from '@/tests/mocks/database.mock';
-
-describe('RememberTool', () => {
-  let rememberTool: RememberTool;
-  let mockDatabase: MockDatabase;
-
-  beforeEach(() => {
-    mockDatabase = new MockDatabase();
-    rememberTool = new RememberTool(mockDatabase);
-  });
-
-  it('should create memory with valid parameters', async () => {
-    // Given
-    const params = {
-      content: 'Test memory',
-      type: 'episodic',
-      importance: 0.8
-    };
-
-    // When
-    const result = await rememberTool.execute(params);
-
-    // Then
-    expect(result.memory_id).toBeDefined();
-    expect(mockDatabase.createMemory).toHaveBeenCalledWith(
-      expect.objectContaining({
-        content: 'Test memory',
-        type: 'episodic',
-        importance: 0.8
-      })
-    );
-  });
-});
-```
-
-#### 통합 테스트
-
-```typescript
-// tests/integration/mcp-server.test.ts
-import { MCPClient } from '@modelcontextprotocol/sdk';
-import { MCPServer } from '@/server';
-
-describe('MCP Server Integration', () => {
-  let server: MCPServer;
-  let client: MCPClient;
-
-  beforeAll(async () => {
-    server = new MCPServer();
-    await server.start();
-    
-    client = new MCPClient({
-      name: 'test-client',
-      version: '1.0.0'
-    });
-    await client.connect({
-      command: 'node',
-      args: ['dist/server/index.js']
-    });
-  });
-
-  afterAll(async () => {
-    await client.close();
-    await server.stop();
-  });
-
-  it('should handle remember and recall workflow', async () => {
-    // Remember
-    const rememberResult = await client.callTool('remember', {
-      content: 'Integration test memory'
-    });
-
-    expect(rememberResult.memory_id).toBeDefined();
-
-    // Recall
-    const recallResult = await client.callTool('recall', {
-      query: 'integration test'
-    });
-
-    expect(recallResult.items).toHaveLength(1);
-    expect(recallResult.items[0].content).toContain('Integration test memory');
-  });
-});
-```
-
-### 3. 코드 리뷰
-
-#### Pull Request 생성
-
-1. GitHub에서 Pull Request 생성
-2. 변경사항 설명 작성
-3. 관련 이슈 연결
-4. 리뷰어 지정
-
-#### 리뷰 체크리스트
-
-- [ ] 코드가 프로젝트 스타일 가이드를 따르는가?
-- [ ] 테스트가 충분히 작성되었는가?
-- [ ] 문서가 업데이트되었는가?
-- [ ] 성능에 영향을 주는가?
-- [ ] 보안 취약점이 없는가?
-
-## 테스트 작성
-
-### 테스트 전략
-
-#### 1. 단위 테스트 (Unit Tests) - `.spec.ts`
-
-- **목적**: 개별 함수/클래스의 동작 검증
-- **범위**: 모든 public 메서드
-- **도구**: Vitest
-- **위치**: 각 모듈 폴더 내부
-- **예시**: 
-  - `src/algorithms/search-engine.spec.ts`
-  - `src/services/forgetting-policy-service.spec.ts`
-  - `src/utils/database.spec.ts`
-
-#### 2. E2E 테스트 (End-to-End Tests) - `test-*.ts`
-
-- **목적**: 전체 워크플로우 검증
-- **범위**: 실제 MCP 서버와의 통신
-- **도구**: tsx + MCP 클라이언트
-- **위치**: `src/test/` 폴더
-- **예시**:
-  - `src/test/test-client.ts`
-  - `src/test/test-search.ts`
-  - `src/test/test-embedding.ts`
-
-### 4. 에러 로깅 테스트
-
-- **목적**: 에러 로깅 시스템의 정상 동작 검증
-- **범위**: ErrorLoggingService, 에러 통계, 에러 해결
-- **도구**: tsx + 직접 서비스 테스트
-- **위치**: `src/test-error-logging.ts`
-
-### 5. 성능 알림 테스트
-
-- **목적**: 성능 알림 시스템의 정상 동작 검증
-- **범위**: PerformanceAlertService, 실시간 모니터링, 알림 관리
-- **도구**: tsx + 직접 서비스 테스트
-- **위치**: `src/test-performance-alerts.ts`
-
-### 테스트 작성 가이드
-
-#### 1. 테스트 구조 (AAA 패턴)
-
-```typescript
-describe('ComponentName', () => {
-  describe('methodName', () => {
-    it('should do something when condition', async () => {
-      // Arrange (준비)
-      const input = createTestInput();
-      const expected = createExpectedOutput();
-      
-      // Act (실행)
-      const result = await component.method(input);
-      
-      // Assert (검증)
-      expect(result).toEqual(expected);
-    });
-  });
-});
-```
-
-#### 2. Mock 사용
-
-```typescript
-// Mock 객체 생성
-const mockDatabase = {
-  createMemory: jest.fn(),
-  getMemory: jest.fn(),
-  searchMemories: jest.fn()
-};
-
-// Mock 설정
-mockDatabase.createMemory.mockResolvedValue('memory-123');
-
-// Mock 검증
-expect(mockDatabase.createMemory).toHaveBeenCalledWith(expectedParams);
-```
-
-#### 3. 테스트 데이터 관리
-
-```typescript
-// tests/fixtures/memories.json
-{
-  "episodic": [
-    {
-      "id": "memory-1",
-      "content": "Test episodic memory",
-      "type": "episodic",
-      "importance": 0.8
-    }
-  ],
-  "semantic": [
-    {
-      "id": "memory-2",
-      "content": "Test semantic memory",
-      "type": "semantic",
-      "importance": 0.9
-    }
-  ]
-}
-```
-
-### 테스트 실행
-
-```bash
-# 모든 테스트 실행 (Vitest)
-npm 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:error-logging
-npm run test:performance-alerts
-
-# 커버리지 포함 테스트
-npm run test -- --coverage
-
-# 감시 모드
-npm run test -- --watch
-```
-
-## 기여 방법
-
-### 1. 이슈 생성
-
-#### 버그 리포트
-
-```markdown
-**버그 설명**
-간단명료한 버그 설명
-
-**재현 단계**
-1. '...'로 이동
-2. '...' 클릭
-3. '...' 입력
-4. 오류 발생
-
-**예상 동작**
-어떤 일이 일어나야 하는지
-
-**실제 동작**
-실제로 일어난 일
-
-**환경**
-- OS: [예: Windows 10]
-- Node.js: [예: 20.0.0]
-- Memento: [예: 0.1.0]
-```
-
-#### 기능 요청
-
-```markdown
-**기능 설명**
-원하는 기능에 대한 간단명료한 설명
-
-**사용 사례**
-이 기능이 왜 필요한지, 어떤 문제를 해결하는지
-
-**제안하는 해결책**
-구체적인 구현 방안 (있는 경우)
-
-**대안**
-고려한 다른 해결책들
-```
-
-### 2. 코드 기여
-
-#### 1단계: 저장소 포크
-
-1. GitHub에서 저장소 포크
-2. 로컬에 클론
-
-```bash
-git clone https://github.com/your-username/memento.git
-cd memento
-```
-
-#### 2단계: 개발 환경 설정
-
-```bash
-# 원본 저장소 추가
-git remote add upstream https://github.com/your-org/memento.git
-
-# 의존성 설치
-npm install
-
-# 개발 서버 시작
-npm run dev
-```
-
-#### 3단계: 기능 개발
-
-```bash
-# 새 브랜치 생성
-git checkout -b feature/your-feature
-
-# 개발 진행
-# ... 코드 작성 ...
-
-# 테스트 작성
-npm run test
-
-# 커밋
-git add .
-git commit -m "feat: add your feature"
-```
-
-#### 4단계: Pull Request 생성
-
-1. 변경사항 푸시
-```bash
-git push origin feature/your-feature
-```
-
-2. GitHub에서 Pull Request 생성
-3. 템플릿에 따라 설명 작성
-4. 리뷰어 지정
-
-### 3. 문서 기여
-
-#### 문서 작성 가이드
-
-- **언어**: 한국어 (기술 용어는 영어 병기)
-- **형식**: Markdown
-- **구조**: 명확한 목차와 섹션 구분
-- **예시**: 실제 사용 가능한 코드 예시
-
-#### 문서 업데이트
-
-1. 관련 문서 파일 수정
-2. 변경사항 설명
-3. 리뷰 요청
-
-### 4. 커밋 메시지 규칙
-
-#### 컨벤셔널 커밋 형식
-
-```
-<type>(<scope>): <description>
-
-[optional body]
-
-[optional footer(s)]
-```
-
-#### 타입
-
-- `feat`: 새로운 기능
-- `fix`: 버그 수정
-- `docs`: 문서 변경
-- `style`: 코드 포맷팅
-- `refactor`: 코드 리팩토링
-- `test`: 테스트 추가/수정
-- `chore`: 빌드 프로세스 또는 보조 도구 변경
-
-#### 예시
-
-```bash
-feat(tools): add summarize_thread tool
-fix(database): resolve memory leak in SQLite connection
-docs(api): update remember tool documentation
-test(integration): add MCP server integration tests
-```
-
-## 에러 로깅 및 성능 모니터링 개발 가이드
-
-### 에러 로깅 시스템
-
-#### 1. 에러 로깅 서비스 사용
-
-```typescript
-import { ErrorLoggingService, ErrorSeverity, ErrorCategory } from '../services/error-logging-service.js';
-
-// 에러 로깅 서비스 초기화
-const errorLoggingService = new ErrorLoggingService();
-
-// 에러 로깅
-try {
-  // 위험한 작업 수행
-  await riskyOperation();
-} catch (error) {
-  errorLoggingService.logError(
-    error instanceof Error ? error : new Error(String(error)),
-    ErrorSeverity.HIGH,
-    ErrorCategory.TOOL_EXECUTION,
-    {
-      operation: 'risky_operation',
-      userId: 'user123',
-      timestamp: new Date().toISOString()
-    }
-  );
-}
-```
-
-#### 2. 에러 통계 조회
-
-```typescript
-// 기본 에러 통계
-const stats = await errorLoggingService.getErrorStats();
-
-// 필터링된 에러 통계
-const highErrors = await errorLoggingService.getErrorStats({
-  severity: ErrorSeverity.HIGH,
-  hours: 24
-});
-
-// 데이터베이스 관련 에러만 조회
-const dbErrors = await errorLoggingService.getErrorStats({
-  category: ErrorCategory.DATABASE,
-  limit: 10
-});
-```
-
-#### 3. 에러 해결 처리
-
-```typescript
-// 에러 해결
-const resolved = await errorLoggingService.resolveError(
-  'error-123',
-  'admin',
-  '데이터베이스 연결 문제 해결됨'
-);
-```
-
-### 성능 알림 시스템
-
-#### 1. 성능 알림 서비스 사용
-
-```typescript
-import { PerformanceAlertService, AlertLevel, AlertType } from '../services/performance-alert-service.js';
-
-// 성능 알림 서비스 초기화
-const alertService = new PerformanceAlertService('./logs');
-
-// 알림 생성
-const alert = alertService.createAlert(
-  AlertLevel.WARNING,
-  AlertType.RESPONSE_TIME,
-  '평균 응답시간',
-  150,
-  100,
-  '🟡 응답시간이 임계값을 초과했습니다',
-  { component: 'search_engine', operation: 'search' }
-);
-
-// 알림 해결
-const resolvedAlert = alertService.resolveAlert(
-  alert.id,
-  'admin',
-  '성능 최적화 완료'
-);
-```
-
-#### 2. 실시간 모니터링 설정
-
-```typescript
-import { PerformanceMonitoringIntegration } from '../services/performance-monitoring-integration.js';
-
-// 모니터링 통합 서비스 초기화
-const monitoringIntegration = new PerformanceMonitoringIntegration(
-  db,
-  alertService,
-  {
-    enableRealTimeMonitoring: true,
-    monitoringInterval: 30000, // 30초마다 체크
-    alertThresholds: {
-      responseTime: { warning: 100, critical: 500 },
-      memoryUsage: { warning: 100, critical: 200 },
-      errorRate: { warning: 5, critical: 10 },
-      throughput: { warning: 10, critical: 5 }
-    }
-  }
-);
-
-// 실시간 모니터링 시작
-monitoringIntegration.startRealTimeMonitoring();
-```
-
-### 테스트 작성
-
-#### 1. 에러 로깅 테스트
-
-```typescript
-// src/test-error-logging.ts
-import { ErrorLoggingService, ErrorSeverity, ErrorCategory } from './services/error-logging-service.js';
-
-async function testErrorLogging() {
-  const errorService = new ErrorLoggingService();
-  
-  // 에러 로깅 테스트
-  errorService.logError(
-    new Error('Test error'),
-    ErrorSeverity.HIGH,
-    ErrorCategory.SYSTEM,
-    { test: true }
-  );
-  
-  // 통계 조회 테스트
-  const stats = errorService.getErrorStats();
-  console.log('Error stats:', stats);
-  
-  // 에러 해결 테스트
-  const errors = errorService.searchErrors({ limit: 1 });
-  if (errors.length > 0) {
-    const resolved = errorService.resolveError(
-      errors[0].id,
-      'test_user',
-      'Test resolution'
-    );
-    console.log('Error resolved:', resolved);
-  }
-}
-```
-
-#### 2. 성능 알림 테스트
-
-```typescript
-// src/test-performance-alerts.ts
-import { PerformanceAlertService, AlertLevel, AlertType } from './services/performance-alert-service.js';
-
-async function testPerformanceAlerts() {
-  const alertService = new PerformanceAlertService('./logs');
-  
-  // 알림 생성 테스트
-  const alert = alertService.createAlert(
-    AlertLevel.WARNING,
-    AlertType.MEMORY_USAGE,
-    '메모리 사용량',
-    150,
-    100,
-    '🟡 메모리 사용량 초과'
-  );
-  
-  // 알림 통계 조회
-  const stats = alertService.getStats();
-  console.log('Alert stats:', stats);
-  
-  // 알림 해결 테스트
-  const resolved = alertService.resolveAlert(
-    alert.id,
-    'test_user',
-    'Test resolution'
-  );
-  console.log('Alert resolved:', resolved);
-}
-```
-
-## 추가 리소스
-
-- [API 참조 문서](api-reference.md)
-- [사용자 매뉴얼](user-manual.md)
-- [아키텍처 문서](architecture.md)
-- [테스트 가이드](testing-guide.md)
-- [Cursor Rules](../.cursor/rules/)
-- [GitHub 저장소](https://github.com/your-org/memento)
-- [커뮤니티 포럼](https://github.com/your-org/memento/discussions)