# memvid-rs v2 Upgrade TODO

memvid 공식 버전이 v2로 업그레이드됨에 따라 memvid-rs도 v2 아키텍처로 포팅 필요.

## 참고 자료
- 공식 memvid v2: https://github.com/memvid/memvid
- PyPI: `memvid-sdk==2.0.144`
- 문서: https://docs.memvid.com

---

## Phase 1: 파일 포맷 변경

### 1.1 단일 .mv2 파일 포맷 설계
- [ ] `.mp4` + `.faiss` + `.json` → 단일 `.mv2` 바이너리 포맷
- [ ] 파일 구조 설계:
  - Header (매직 넘버, 버전, 메타데이터)
  - WAL (Write-Ahead Log)
  - Compressed Segments (데이터)
  - Lexical Index (Tantivy 또는 대안)
  - Vector Index (HNSW)
  - Footer (체크섬)
- [ ] Append-only 쓰기 지원 (기존 데이터 무결성 보장)

### 1.2 Rust 구현
- [ ] `mv2` 파일 읽기/쓰기 모듈 (`src/format/mod.rs`)
- [ ] Frame 기반 아키텍처 (Smart Frames)
- [ ] 압축 알고리즘 선택 (zstd, lz4 등)

---

## Phase 2: 검색 엔진 내장

### 2.1 Lexical Search (Full-text)
- [ ] Tantivy 통합 또는 경량 대안 (BM25)
- [ ] 한국어 토크나이저 지원
- [ ] `.mv2` 파일 내 인덱스 저장

### 2.2 Vector Search
- [ ] HNSW 구현 또는 라이브러리 통합
  - 옵션: `hnsw_rs`, `instant-distance`, 자체 구현
- [ ] 외부 FAISS 의존성 제거
- [ ] 임베딩 모델 내장 또는 선택적 로드

### 2.3 하이브리드 검색
- [ ] Lexical + Vector 결합 (RRF fusion)
- [ ] 검색 모드: `lex`, `vec`, `hybrid`

---

## Phase 3: API 재설계

### 3.1 새로운 Python API
```python
# 목표 API
from memvid_rs import create, use

# 생성
mem = create('archive.mv2')
mem.enable_lex()
mem.put(text='...', title='doc1', tags=['esg'])
mem.seal()
mem.close()

# 검색
mem = use('basic', 'archive.mv2')
results = mem.find('query', k=5)
mem.close()
```

### 3.2 메서드 매핑
| 기존 API | 새 API |
|---------|--------|
| `MemvidEncoder()` | `create(path)` |
| `encoder.add_text()` | `mem.put(text=...)` |
| `encoder.build_video()` | `mem.seal()` + `mem.close()` |
| `MemvidRetriever(video, index)` | `use('basic', path)` |
| `retriever.search()` | `mem.find()` |
| `retriever.get_stats()` | `mem.stats()` |

### 3.3 하위 호환성
- [ ] 기존 `.mp4` + `.faiss` 포맷 읽기 지원 (마이그레이션용)
- [ ] Deprecation 경고 추가

---

## Phase 4: 추가 기능

### 4.1 memvid-sdk v2 기능 패리티
- [ ] `ask()` - RAG 기반 Q&A (LLM 통합)
- [ ] `state()` - 엔티티 상태 조회
- [ ] `timeline()` - 시간순 조회
- [ ] `session_*()` - 세션 관리
- [ ] 암호화 지원

### 4.2 성능 최적화
- [ ] Sub-5ms 검색 목표
- [ ] Predictive caching
- [ ] 병렬 인덱싱

---

## Phase 5: 릴리스

### 5.1 버전 전략
- [ ] v1.x: 현재 API 유지 (deprecated)
- [ ] v2.0: 새 `.mv2` 포맷 + 새 API

### 5.2 문서화
- [ ] README.md 업데이트
- [ ] 마이그레이션 가이드 작성
- [ ] API 레퍼런스 문서

### 5.3 PyPI 배포
- [ ] `memvid-rs>=2.0.0` 릴리스
- [ ] GitHub Release 생성

---

## 우선순위

1. **High**: Phase 1 (파일 포맷) + Phase 3 (API 재설계)
2. **Medium**: Phase 2 (검색 엔진 내장)
3. **Low**: Phase 4 (추가 기능)

---

## 기술 결정 필요

- [ ] QR 코드 인코딩 유지 vs Frame 기반 바이너리?
- [ ] Tantivy vs 경량 BM25 구현?
- [ ] HNSW 라이브러리 선택?
- [ ] 임베딩 모델 내장 방식?

---

*생성일: 2026-01-05*
*memvid-sdk v2.0.144 기준*
