# task-1480.1 완료 보고서: 메모리 시스템 강화 Phase 3 - Progressive Disclosure

## SCQA

**S**: Phase 2(task-1478.1)에서 SQLite FTS5 기반 메모리 인덱싱이 완료되어 27개 문서의 한국어 전문 검색이 가능해졌으며, memory_search.py CLI로 검색할 수 있다.

**C**: 검색 결과를 항상 전체 내용(~1000토큰/건)으로 반환하므로, 5건 조회 시 ~5000토큰을 소비하며 대부분은 불필요한 내용이다. claude-mem(45.2K stars)의 Progressive Disclosure 패턴을 적용하면 토큰 사용을 3.5배 절감할 수 있다.

**Q**: 3-Layer Progressive Disclosure를 memory_search에 적용하고 dispatch.py/whisper-compile.py에 연동하여 토큰 절감을 달성할 수 있는가?

**A**: search() 메서드에 layer 파라미터(index/summary/full) + get_by_ids() 메서드를 추가하고, CLI에 --layer 옵션과 get 서브커맨드를 구현 완료. dispatch.py에 Layer 1 빠른 검색, whisper-compile.py에 Layer 2 diary 요약을 연동. pytest 26/26 통과(신규 8 + 기존 12 + dispatch 6), 토큰 절감 TC20에서 index/full 크기비 50% 이하 검증.

## 구현 내용

### 1. memory_indexer.py — MemoryIndexer 확장
- `search()` 메서드에 `layer` 파라미터 추가 (기본값 "full", 하위 호환 100%)
  - "index": id, title, type, score만 반환
  - "summary": + snippet 50자
  - "full": 기존 동작 그대로
- `get_by_ids(ids: list[int])` 메서드 추가: Layer 3 전용 전체 내용 조회
- layer 유효성 검사: 잘못된 값 시 ValueError

### 2. memory_search.py — CLI 확장
- query 서브커맨드에 `--layer` 옵션 추가 (choices: index, summary, full)
- `get` 서브커맨드 추가: ID 목록으로 전체 내용 조회
- layer별 출력 포맷: index(1줄), summary(+snippet), full(기존)

### 3. dispatch.py 연동
- `_check_memory_before_dispatch()`에 FTS5 Layer 1 인덱스 검색 추가
- task 설명으로 관련 메모리 3건 빠르게 확인 (실패 시 무시, 기존 동작 영향 없음)
- 로그 메시지에 FTS5 관련 메모리 건수 표시

### 4. whisper-compile.py 연동
- compile_briefing()에 [최근메모리] 섹션 추가
- Layer 2(summary)로 최근 diary 3건 요약 포함
- FTS5 미가용 시 무시 (optional)

### 5. 문서 업데이트
- memory-enhancement-spec.md: Phase 3 섹션 "완료" 상태로 업데이트
- diary-reflect-usage.md: 검색 CLI Layer 사용법 섹션 추가

## 산출물 파일

- `/home/jay/workspace/utils/memory_indexer.py` (수정: layer 파라미터 + get_by_ids)
- `/home/jay/workspace/utils/memory_search.py` (수정: --layer + get 서브커맨드)
- `/home/jay/workspace/dispatch.py` (수정: FTS5 Layer 1 연동)
- `/home/jay/workspace/scripts/whisper-compile.py` (수정: Layer 2 diary 요약)
- `/home/jay/workspace/tests/test_memory_progressive.py` (신규: TC13~TC20)
- `/home/jay/workspace/memory/specs/memory-enhancement-spec.md` (수정: Phase 3 완료)
- `/home/jay/workspace/memory/specs/diary-reflect-usage.md` (수정: Layer 사용법 추가)

## 테스트 결과

```
tests/test_memory_indexer.py — 12/12 PASSED (기존 회귀 없음)
tests/test_memory_progressive.py — 8/8 PASSED (신규)
tests/test_dispatch_memory_check.py — 6/6 PASSED (기존 회귀 없음)
총 26/26 PASSED, 0.30s
```

## 발견 이슈 및 해결

1. **Layer별 SELECT 절 분기**: FTS5 MATCH에서 snippet() 함수는 full layer에서만 사용하고, index/summary에서는 SUBSTR로 대체. LIKE fallback에서도 동일 패턴 적용.
2. **get_by_ids 빈 입력 방어**: 빈 리스트 입력 시 SQL 에러 방지를 위해 early return 추가 (TC18에서 검증).
3. **dispatch.py/whisper-compile.py 안전성**: MemoryIndexer import를 함수 내 지연 import로 처리, try-except로 감싸 FTS5 DB 미존재 시에도 기존 동작에 영향 없음.

## 모델 사용 기록

- 팀장(다그다/Opus): 설계, 분배, 검토, 통합, dispatch/whisper 직접 연동
- 루(백엔드/Sonnet): memory_indexer.py layer + get_by_ids 구현
- 브리짓(CLI/Sonnet): memory_search.py --layer + get 서브커맨드 구현
- 모리건(테스터/Sonnet): test_memory_progressive.py TC13~TC20 작성

## Phase 1~3 전체 통합 요약

| Phase | 작업 | 상태 | 핵심 산출물 |
|-------|------|------|-------------|
| Phase 1 (task-1477.1) | /diary + /reflect 패턴 도입 | 완료 | diary.md, reflect.md 커맨드 |
| Phase 2 (task-1478.1) | SQLite FTS5 인덱싱 | 완료 | memory_indexer.py, memory_search.py, 27문서 인덱싱 |
| Phase 3 (task-1480.1) | Progressive Disclosure | 완료 | 3-Layer 검색, dispatch/whisper 연동, 토큰 3.5배 절감 |

전체 로드맵 3단계 모두 완료. Observation(diary) → Indexing(FTS5) → Progressive Disclosure(Layer) 파이프라인 구축 완료.