# 메모리 시스템 강화 스펙 (Memory Enhancement Specification)

## 개요

제이회장님의 핵심 고민: "메모리에 저장해도 안 읽으면 뭐해"
→ 저장이 아닌 CLAUDE.md 규칙화가 답. 검색 안 해도 매 세션 자동 로드.

## 전체 로드맵

### Phase 1: claude-diary 패턴 도입 (현재)

- /diary + /reflect 커맨드 → Shell 스크립트 + settings.json 훅
- Generative Agents 논문 영감: Observation → Reflection → Retrieval
- 참조: https://github.com/rlancemartin/claude-diary

### Phase 2: SQLite FTS5 인덱싱 (완료, task-1478.1)

- diary + 아누 메모리 파일을 SQLite FTS5로 인덱싱 (27개 문서 초기 인덱싱 완료)
- FTS5 MATCH + LIKE fallback으로 한국어 검색 지원
- SHA256 해시 기반 증분 인덱싱 (skipped/updated/indexed)
- Phase 1 frontmatter 메타데이터를 인덱스 키로 활용
- 산출물:
  - `/home/jay/workspace/utils/memory_indexer.py` — MemoryIndexer 클래스
  - `/home/jay/workspace/utils/memory_search.py` — CLI 검색 도구
  - DB: `/home/jay/.claude/memory/memory_index.db`
- /diary 연동: diary 생성 후 자동 reindex
- /reflect 연동: FTS5 검색으로 관련 diary 빠른 탐색 지원
- Phase 3 연결 포인트: `search()` 메서드에 `summary_only` 파라미터 추가하면 Progressive Disclosure 구현 가능

### Phase 3: Progressive Disclosure (완료, task-1480.1)

- claude-mem(45.2K stars) 스타일 3-Layer Progressive Disclosure 패턴 적용
- Layer 1 (Index): id, title, type, score만 반환 (~50-100 토큰)
- Layer 2 (Summary): + snippet 50자 (~200-300 토큰)
- Layer 3 (Full): 선택한 ID의 전체 내용 조회 (~500-1000 토큰)
- 토큰 절감: 기존 5건 전체 ~5000토큰 → Layer1→2→3 선택 = ~1400토큰 (약 3.5배 절감)
- 산출물:
  - `memory_indexer.py` — `search(layer=)` 파라미터 + `get_by_ids()` 메서드 추가
  - `memory_search.py` — `--layer` CLI 옵션 + `get` 서브커맨드 추가
  - `dispatch.py` — `_check_memory_before_dispatch()`에 FTS5 Layer 1 연동
  - `whisper-compile.py` — 브리핑에 최근 diary Layer 2 요약 포함
- 테스트: TC13~TC20 (8개 TC) + 기존 TC01~TC12 회귀 없음 = 20/20 PASS

---

## Phase 1 상세 설계

### 아키텍처

3단계 워크플로우:

```
1. Observation  →  /diary 실행
                   세션에서 수행한 작업, 받은 피드백, 설계 결정, 실수를 구조화된
                   Markdown 파일로 저장. frontmatter에 메타데이터 포함.

2. Reflection   →  /reflect 실행
                   누적된 diary 엔트리를 분석하여 반복 패턴 추출.
                   강력 패턴(3회+)은 CLAUDE.md 규칙화 후보로 제안.

3. Rule         →  CLAUDE.md 업데이트 (사용자 승인 후)
                   패턴이 규칙으로 전환되어 매 세션 자동 로드.
                   검색 없이도 컨텍스트가 유지됨.
```

### 커맨드 정의

**`/diary`**
- 역할: 현재 세션 분석 → diary 엔트리 생성
- 저장 위치: `/home/jay/.claude/memory/diary/YYYY-MM-DD-session-NN.md`
- frontmatter: date, session, team_id, task_id, tags, auto_generated
- 본문 섹션: 수행한 작업 / 피드백 및 수정 지시 / 설계 결정 및 이유 / 실수 및 원인 / 반복 패턴

**`/reflect`**
- 역할: 누적된 diary 패턴 추출 → CLAUDE.md 업데이트 제안
- 분석 범위: processed.log에 없는 미분석 diary 엔트리
- 출력: 6개 카테고리별 패턴 분석 + 규칙화 권고
- 승인 흐름: 사용자 확인 후에만 CLAUDE.md 수정

### PreCompact 훅

- Compact 도구 호출 시 자동으로 diary 엔트리 생성
- 기존 `pre-compact-backup.sh`와 독립적으로 동작 (충돌 없음)
- CLI 호출 제약으로 인해 최소 메타데이터만 저장 (`auto_generated: true`)
- 수동 `/diary`보다 내용이 최소화되지만 세션 연속성 보장

### 멀티봇 시스템 특화

- 8팀 체제에 맞게 diary 저장 시 `team_id`, `task_id` 메타데이터 포함
- `/reflect` 실행 시 팀별 패턴 분리 분석 가능
- 규칙 반영 대상: 아누(실장)의 CLAUDE.md에만 적용 (팀별 CLAUDE.md는 별도 관리)

### 파일 구조

```
/home/jay/.claude/
├── commands/
│   ├── diary.md          # /diary 커맨드 정의
│   └── reflect.md        # /reflect 커맨드 정의
├── memory/
│   └── diary/
│       ├── YYYY-MM-DD-session-NN.md  # diary 엔트리 (수동 + 자동)
│       └── processed.log             # reflect 중복 방지 로그
└── settings.json         # PreCompact 훅 등록

/home/jay/workspace/hooks/
└── pre-compact-diary.sh  # PreCompact 자동 diary 훅 스크립트
```

### diary 엔트리 데이터 구조 (Phase 2 연결 포인트)

```yaml
---
date: "YYYY-MM-DD"
session: N
team_id: "팀-식별자"
task_id: "task-XXXX.X"
tags: [태그1, 태그2, ...]
auto_generated: false  # PreCompact 훅 생성 시 true
---
```

- Phase 2에서 frontmatter 필드가 SQLite FTS5 인덱스 키로 직접 활용됨
- `tags` 필드는 FTS5 전문 검색 대상
- `team_id` + `task_id` 조합으로 멀티봇 환경에서 출처 추적 가능
- 현재 구조 변경 없이 Phase 2로 자연스럽게 마이그레이션 가능

### 의존성

- 외부 라이브러리 의존성 없음 (순수 Shell + Markdown)
- Claude Code CLI의 `/command` 기능에 의존
- `jq` 선택적 사용 (없으면 `grep` fallback으로 동작)
- SQLite는 Phase 2에서 추가 (현재는 불필요)