# Claude Memory MCP Server

Claude의 제한된 메모리를 보완하는 영구 저장소 MCP 서버입니다.

## 주요 기능

### 🎯 핵심 기능
- **저장/로드**: 카테고리별로 메모리 저장 및 로드
- **검색**: 키워드, 카테고리, 태그로 최적화된 검색
- **버전 관리**: 수정 시 자동 버전 백업 (최근 5개 유지)
- **자동 백업**: 전체 메모리 백업 및 복원

### ✨ 개선된 기능
- **태그 정규화**: 자동으로 소문자 변환 및 중복 제거
- **인덱스 복구**: index.json 손상 시 자동 재구성
- **검색 최적화**: 2단계 검색으로 성능 향상
- **통계 기능**: 메모리 사용 현황 분석
- **Export/Import**: JSON 형식으로 백업 이동
- **메모리 병합**: 중복 메모리 통합
- **크기 제한**: 메모리당 최대 1MB 제한
- **에러 복구**: 강화된 에러 처리 및 로깅

## 설치

```bash
cd C:\Users\admin\Documents\ClaudeMCP
npm install
npm run build
```

## Claude Desktop 설정

`%APPDATA%\Claude\claude_desktop_config.json` 파일을 편집:

```json
{
  "mcpServers": {
    "memory": {
      "command": "node",
      "args": [
        "C:\\Users\\admin\\Documents\\ClaudeMCP\\build\\index.js"
      ]
    }
  }
}
```

Claude Desktop을 재시작하면 MCP 서버가 활성화됩니다.

## 사용 가능한 도구

### 📝 기본 작업

#### 1. save_memory
새로운 메모리 저장

```typescript
{
  category: string;    // 예: "UE5_Rendering", "PCG", "ProjectGray"
  title: string;       // 짧은 제목
  content: string;     // 전체 내용 (최대 1MB)
  tags?: string[];     // 선택적 태그 (자동 정규화)
}
```

**특징:**
- 태그는 자동으로 소문자 변환 및 중복 제거
- 내용 크기는 1MB로 제한

#### 2. get_memory
ID로 특정 메모리 로드

```typescript
{
  id: string;  // 메모리 ID
}
```

#### 3. update_memory
기존 메모리 수정

```typescript
{
  id: string;
  title?: string;      // 선택적
  content?: string;    // 선택적 (최대 1MB)
  tags?: string[];     // 선택적 (자동 정규화)
}
```

**특징:**
- 이전 버전 자동 백업 (v1, v2, ...)
- 최근 5개 버전만 유지 (오래된 버전 자동 삭제)

### 🔍 검색 및 조회

#### 4. search_memory
메모리 검색 (최적화된 2단계 검색)

```typescript
{
  query?: string;      // 텍스트 검색
  category?: string;   // 카테고리 필터
  tags?: string[];     // 태그 필터 (대소문자 무시)
  limit?: number;      // 결과 개수 제한
}
```

**성능 최적화:**
- 1단계: 인덱스 기반 빠른 필터링
- 2단계: 필요한 메모리만 로드

#### 5. list_categories
모든 카테고리 목록 조회

#### 6. get_statistics
통계 정보 조회

**반환 정보:**
- 전체 메모리 수
- 카테고리별 개수
- 태그별 사용 빈도
- 가장 오래된/최신 메모리
- 총 저장 용량

### 🔧 유지보수 도구

#### 7. rebuild_index
인덱스 재구성

**사용 시기:**
- index.json 파일 손상 시
- 인덱스와 실제 파일 불일치 시
- 수동 파일 조작 후

#### 8. merge_memories
여러 메모리 병합

```typescript
{
  ids: string[];  // 병합할 메모리 ID 배열 (최소 2개)
}
```

**동작:**
- 모든 내용을 구분자로 연결
- 태그 통합 및 정규화
- 원본 메모리 삭제

#### 9. delete_memory
메모리 삭제

```typescript
{
  id: string;
}
```

**특징:**
- 메모리와 모든 버전 백업 함께 삭제

### 📦 백업 및 이동

#### 10. create_backup
전체 메모리 백업 생성

**백업 위치:**
```
C:\Users\admin\Documents\ClaudeMCP\memories\backups\backup_{timestamp}\
```

#### 11. list_backups
모든 백업 목록 조회

#### 12. restore_backup
백업에서 복원

```typescript
{
  timestamp: string;  // 백업 타임스탬프
}
```

**⚠️ 경고:** 현재 모든 메모리가 삭제됩니다!

#### 13. export_memories
JSON 파일로 내보내기

```typescript
{
  category?: string;    // 선택적 (특정 카테고리만)
  output_path: string;  // 저장 경로
}
```

**사용 예:**
```typescript
{
  category: "UE5_Rendering",
  output_path: "C:\\backup\\ue5_memories.json"
}
```

#### 14. import_memories
JSON 파일에서 가져오기

```typescript
{
  input_path: string;   // 파일 경로
  overwrite?: boolean;  // 기존 메모리 덮어쓰기 (기본: false)
}
```

## 사용 시나리오

### 시나리오 1: 학습 내용 저장
```
User: "RDG에서 FRDGBuilder 사용법 기억해줘. 
       FRDGBuilder로 리소스 생성하고, AddPass로 패스 추가하고..."

Claude: [save_memory 내부 호출]
{
  category: "UE5_Rendering",
  title: "RDG FRDGBuilder 사용법",
  content: "...",
  tags: ["rdg", "frdgbuilder", "rendering"]  // 자동 정규화
}
→ "✅ Memory saved! ID: mem_xxx..."
```

### 시나리오 2: 작업 시작 시 기억 로드
```
User: "RDG + SceneViewExtension 작업 시작할건데, 관련 기억 불러와"

Claude: [search_memory 내부 호출]
{
  query: "RDG SceneViewExtension",
  category: "UE5_Rendering"
}
→ 검색 결과 3개:
   1. RDG Best Practices
   2. SceneViewExtension 구조
   3. RDG Pass 추가 방법
```

### 시나리오 3: 자동 컨텍스트 인식
```
User: "ColorCorrectRegions처럼 PostProcess 구현하고 싶어"

Claude: [자동으로 search_memory 호출]
→ "ColorCorrectRegions 분석" 메모리 로드
→ 저장된 아키텍처 기반으로 구체적 답변
```

### 시나리오 4: 중복 메모리 정리
```
User: "RDG 관련 메모리가 여러 개인데 하나로 합쳐줘"

Claude: [search_memory로 찾고 merge_memories 호출]
{
  ids: ["mem_123", "mem_456", "mem_789"]
}
→ 하나의 통합된 메모리 생성
```

### 시나리오 5: 백업 및 이동
```
User: "메모리 백업하고 다른 컴퓨터로 옮기고 싶어"

Claude: 
1. [export_memories 호출]
   → ue5_memories.json 파일 생성
2. 파일을 USB나 클라우드로 복사
3. 다른 컴퓨터에서 [import_memories 호출]
```

### 시나리오 6: 인덱스 복구
```
User: "검색이 이상해, 메모리는 있는데 안 나와"

Claude: [rebuild_index 호출]
→ "✅ Index rebuilt! 50 memories indexed"
```

## 파일 구조

```
ClaudeMCP/
├── memories/
│   ├── index.json                    # 검색용 인덱스 (메타데이터)
│   │
│   ├── UE5_Rendering/               # 카테고리별 폴더
│   │   ├── mem_xxx.json             # 메모리 본체
│   │   ├── mem_xxx_v1.json          # 버전 1 백업
│   │   ├── mem_xxx_v2.json          # 버전 2 백업
│   │   └── mem_yyy.json
│   │
│   ├── PCG/
│   │   ├── mem_zzz.json
│   │   └── mem_zzz_v1.json
│   │
│   └── backups/                      # 전체 백업
│       ├── backup_2025-01-08T10-30-00-000Z/
│       │   ├── metadata.json
│       │   ├── index.json
│       │   ├── UE5_Rendering/
│       │   └── PCG/
│       └── backup_2025-01-09T15-20-00-000Z/
│
└── src/
    ├── index.ts                      # 메인 서버 (1200+ lines)
    └── types.ts                      # TypeScript 타입 정의
```

## 설정

### CONFIG (src/index.ts)
```typescript
const CONFIG = {
  DATA_DIR: path.join(__dirname, "..", "memories"),
  MAX_VERSIONS: 5,           // 버전 백업 최대 개수
  MAX_CONTENT_SIZE: 1048576, // 1MB per memory
};
```

## 개발

```bash
# TypeScript 컴파일 (watch mode)
npm run watch

# 빌드
npm run build

# 로그 확인 (stderr로 출력)
# Claude Desktop의 로그 파일 확인
```

## 에러 처리

### 자동 복구
- **인덱스 손상**: `rebuild_index` 자동 제안
- **파일 없음**: 경고 로그 후 계속 진행
- **크기 초과**: 명확한 에러 메시지

### 로깅
모든 작업은 stderr로 로그 출력:
```
[2025-01-08T10:30:00.000Z] [INFO] Memory saved: mem_xxx (UE5_Rendering/RDG Best Practices)
[2025-01-08T10:35:00.000Z] [WARN] Failed to read memory file: corrupted.json
[2025-01-08T10:40:00.000Z] [ERROR] Failed to save memory
```

## 성능 최적화

### 검색 최적화
1. **인덱스 기반 필터링** (빠름)
   - 카테고리, 태그 필터
   - 제목/태그에서 키워드 검색
   
2. **전체 로드** (필요시만)
   - 내용에서 키워드 검색

### 버전 관리
- 자동으로 오래된 버전 삭제 (5개 유지)
- 버전 파일: `{id}_v{version}.json`

### 태그 정규화
```typescript
["RDG", "rdg", " RDG "] → ["rdg"]  // 자동 정규화
```

## 제한 사항

1. **메모리 크기**: 1MB per memory
2. **버전 백업**: 최근 5개만 유지
3. **동시성**: 단일 프로세스만 안전
4. **검색**: 정규식 미지원 (단순 문자열 검색)

## 문제 해결

### 검색이 안 됨
```
→ rebuild_index 실행
```

### 파일 손상
```
→ list_backups 확인
→ restore_backup 실행
```

### 태그 중복
```
자동으로 정규화되므로 문제 없음
["RDG", "rdg"] → ["rdg"]
```

### 버전 파일 너무 많음
```
자동으로 5개만 유지됨 (MAX_VERSIONS 설정)
```

## 보안 고려사항

1. **로컬 저장**: 모든 데이터는 로컬에만 저장
2. **암호화 없음**: 민감한 정보 저장 주의
3. **접근 제어**: 파일 시스템 권한에 의존

## 향후 개선 계획

- [ ] 암호화 옵션
- [ ] 자동 백업 스케줄러
- [ ] 전문 검색 (정규식, fuzzy)
- [ ] 메모리 압축
- [ ] 동시성 제어 (락)
- [ ] 웹 인터페이스

## 라이선스

MIT

## 기여

버그 리포트나 기능 제안은 환영합니다!