claude-memory-layer 1.0.10 → 1.0.12

package/memory/specs/progressive-disclosure/2026-02-25.md

@@ -0,0 +1,1436 @@
+
+## 2026-02-25T12:31:26.398Z | 1e97bc37-cfdb-41d2-97fe-8adce20db52d
+- type: session_summary
+- session: import:organized
+# Progressive Disclosure Context
+
+> **Version**: 1.0.0
+> **Created**: 2026-02-01
+
+## 1. 배경
+
+### 1.1 claude-mem의 접근 방식
+
+claude-mem은 토큰 효율성을 위해 3-Layer Progressive Disclosure 패턴을 사용:
+
+```
+Layer 1: Search Index (~50-100 tokens per result)
+    ↓ (필터링)
+Layer 2: Timeline (~200 tokens)
+    ↓ (선택)
+Layer 3: Full Details (~500-1000 tokens per result)
+```
+
+**주요 특징**:
+- "필터링 후 상세 조회" 전략
+- 약 10배 토큰 절약
+- 사용자/AI가 필요한 것만 확장
+
+**구현 방식**:
+- MCP 도구로 각 레이어 노출
+- `search` → `timeline` → `get_observations` 순서
+- `__IMPORTANT` 도구로 워크플로우 문서화
+
+### 1.2 현재 code-memory의 상황
+
+현재 검색은 단일 레이어:
+
+```typescript
+// 현재 Retriever.search()
+async search(query: string): Promise<SearchResult[]> {
+  const vectorResults = await this.vectorStore.search(query, { topK: 5 });
+  const events = await this.enrichWithEvents(vectorResults);
+  return events;  // 전체 내용 반환
+}
+```
+
+**문제점**:
+1. 모든 결과의 전체 내용을 가져옴
+2. 컨텍스트 크기가 토큰 제한에 쉽게 도달
+3. 관련성 낮은 내용도 포함됨
+
+### 1.3 토큰 비용 분석
+
+| 시나리오 | 현재 방식 | Progressive 방식 |
+|----------|----------|-----------------|
+| 5개 결과, 1개만 관련 | ~5,000 tokens | ~600 tokens |
+| 10개 결과, 2개만 관련 | ~10,000 tokens | ~1,200 tokens |
+| 20개 결과, 3개만 관련 | ~20,000 tokens | ~2,000 tokens |
+
+**절약 효과**: 평균 80-90% 토큰 감소
+
+## 2. MCP 도구 설계 참고
+
+### 2.1 claude-mem의 MCP 도구
+
+```typescript
+// claude-mem MCP tools (추정)
+{
+  tools: [
+    {
+      name: 'search',
+      description: 'Search memories, returns index only',
+      input_schema: {
+        query: 'string',
+        filters: { type: 'string', date: 'string' }
+      },
+      output: 'SearchIndexItem[]'
+    },
+    {
+      name: 'timeline',
+      description: 'Get timeline context around observations',
+      input_schema: {
+        observation_ids: 'string[]',
+        window_size: 'number'
+      },
+      output: 'TimelineItem[]'
+    },
+    {
+      name: 'get_observations',
+      description: 'Get full observation details by IDs',
+      input_schema: {
+        ids: 'string[]'
+      },
+      output: 'Observation[]'
+    },
+    {
+      name: '__IMPORTANT',
+      description: 'Workflow documentation for Claude',
+      // Claude가 이 도구를 보고 검색 워크플로우를 이해
+    }
+  ]
+}
+```
+
+### 2.2 워크플로우 문서화
+
+```markdown
+# Memory Search Workflow
+
+1. **Always start with `search`** to get compact index
+2. **Review scores** before expanding
+3. **Use `timeline`** if context is needed
+4. **Only call `get_observations`** for selected IDs
+5. **Never** fetch all details at once
+```
+
+## 3. 기존 코드와의 관계
+
+### 3.1 retriever.ts
+
+현재 Retriever 구조:
+
+```typescript
+export class Retriever {
+  async search(query: string): Promise<SearchResult[]> {
+    // 1. 벡터 검색
+    const vectorResults = await this.vectorStore.search(query);
+
+    // 2. 이벤트 enrichment (전체 로드)
+    const enriched = await Promise.all(
+      vectorResults.map(async (r) => {
+        const event = await this.eventStore.findById(r.id);
+        return { ...r, content: event.payload.content };  // 전체 내용
+      })
+    );
+
+    return enriched;
+  }
+}
+```
+
+**수정 방향**:
+- `search()` → `searchIndex()` (Layer 1)
+- `getTimeline()` 추가 (Layer 2)
+- `getDetails()` 추가 (Layer 3)
+- `smartSearch()` 추가 (자동 확장)
+
+### 3.2 matcher.ts
+
+현재 Matcher는 confidence 기반 분류:
+
+```typescript
+export function matchSearchResults(results: SearchResult[]): MatchResult {
+  const high = results.filter(r => r.score >= 0.92);
+  const suggested = results.filter(r => r.score >= 0.75 && r.score < 0.92);
+
+  return { high, suggested, none: [] };
+}
+```
+
+**확장 방향**:
+- 기존 Matcher 로직을 확장 규칙에 통합
+- `high` → 자동 확장 대상
+- `suggested` → Layer 1만 표시
+
+### 3.3 vector-store.ts
+
+현재 VectorStore 검색:
+
+```typescript
+async search(query: string, options: { topK: number }): Promise<VectorSearchResult[]> {
+  const queryVector = await this.embedder.embed(query);
+  return this.db.search(queryVector, options.topK);
+}
+```
+
+**변경 불필요** - 기존 벡터 검색 그대로 사용
+
+### 3.4 event-store.ts
+
+필요한 추가 메서드:
+
+```typescript
+// 주변 이벤트 조회 (타임라인용)
+async findSurrounding(
+  sessionId: string,
+  timestamp: Date,
+  windowSize: number
+): Promise<Event[]> {
+  return this.db.query(`
+    SELECT * FROM events
+    WHERE session_id = ?
+      AND timestamp BETWEEN
+        datetime(?, '-${windowSize} hours') AND
+        datetime(?, '+${windowSize} hours')
+    ORDER BY timestamp
+  `, [sessionId, timestamp, timestamp]);
+}
+```
+
+## 4. 설계 결정 사항
+
+### 4.1 왜 3개 레이어인가?
+
+**대안 1: 2개 레이어 (Index + Detail)**
+- 단점: 시간 맥락 파악 어려움
+- 단점: 모호한 결과 처리 어려움
+
+**대안 2: 4개 이상 레이어**
+- 단점: 복잡도 증가
+- 단점: 실용적 이점 미미
+
+**선택: 3개 레이어**
+- Layer 1: What (무엇이 있는지)
+- Layer 2: When (언제 발생했는지)
+- Layer 3: How (구체적으로 어떻게)
+
+### 4.2 자동 확장 vs 수동 확장
+
+**자동 확장 장점**:
+- 사용자 경험 향상
+- "자세히 알려줘" 명령 불필요
+- 높은 신뢰도 결과 즉시 제공
+
+**자동 확장 단점**:
+- 토큰 예측 어려움
+- 때로는 불필요한 확장
+
+**결론: 하이브리드 접근**
+- 높은 신뢰도 → 자동 확장
+- 중간 신뢰도 → Index만 제공 + 힌트
+- 낮은 신뢰도 → Index만 제공
+
+### 4.3 요약 생성 전략
+
+**Option 1: LLM 요약**
+- 장점: 고품질 요약
+- 단점: 비용, 지연시간
+
+**Option 2: 규칙 기반 추출**
+- 장점: 빠름, 무료
+- 단점: 품질 제한
+
+**선택: 규칙 기반 + 캐싱**
+- 첫 문장 추출
+- 코드 블록 축약
+- 결과 캐싱
+
+### 4.4 토큰 추정 방식
+
+```typescript
+// 간단한 추정 (정확도 ~85%)
+function estimateTokens(text: string): number {
+  return Math.ceil(text.length / 4);
+}
+
+// 또는 정확한 추정 (tiktoken 사용)
+import { encoding_for_model } from 'tiktoken';
+const enc = encoding_for_model('gpt-4');
+function estimateTokens(text: string): number {
+  return enc.encode(text).length;
+}
+```
+
+**결론**: 간단한 추정 사용 (성능 우선)
+
+## 5. 성능 고려사항
+
+### 5.1 검색 지연시간
+
+| 레이어 | 목표 지연시간 | 병목 |
+|--------|-------------|------|
+| Layer 1 | < 100ms | 벡터 검색 |
+| Layer 2 | < 200ms | DB 쿼리 |
+| Layer 3 | < 500ms | 다중 조회 |
+
+**최적화 전략**:
+- Layer 1: 벡터 인덱스 최적화
+- Layer 2: 세션별 인덱스 활용
+- Layer 3: 배치 조회
+
+### 5.2 캐싱 전략
+
+```typescript
+// 레이어별 캐시 TTL
+const CACHE_CONFIG = {
+  layer1: {
+    ttl: 60 * 1000,      // 1분 (검색 결과는 자주 변함)
+    maxSize: 100
+  },
+  layer2: {
+    ttl: 5 * 60 * 1000,  // 5분 (타임라인은 안정적)
+    maxSize: 500
+  },
+  layer3: {
+    ttl: 30 * 60 * 1000, // 30분 (상세 내용은 거의 안 변함)
+    maxSize: 200
+  }
+};
+```
+
+### 5.3 메모리 사용
+
+- Layer 1 캐시: ~10KB per entry × 100 = ~1MB
+- Layer 2 캐시: ~2KB per entry × 500 = ~1MB
+- Layer 3 캐시: ~10KB per entry × 200 = ~2MB
+- **총 메모리**: ~4MB (허용 범위)
+
+## 6. UI/UX 고려사항
+
+### 6.1 CLI 출력 포맷
+
+```
+🔍 Search Results (5 matches)
+
+#1 [mem_abc] DuckDB 스키마 설계 논의 (0.94)
+#2 [mem_def] 타입 시스템 리팩토링 (0.87)
+#3 [mem_ghi] 벡터 저장소 설정 (0.82)
+
+💡 Tip: Use "show mem_abc" for details
+
+---
+
+📅 Timeline (auto-expanded for high confidence)
+
+14:00 → User asked about schema design
+14:05 → **[mem_abc]** Discussed DuckDB approach
+14:15 → Follow-up on indexing
+```
+
+### 6.2 확장 힌트
+
+```typescript
+function formatExpansionHint(result: ProgressiveSearchResult): string {
+  if (result.meta.expandedCount === 0) {
+    return `Use "show [id]" to see details`;
+  }
+  if (result.meta.expansionReason === 'ambiguous_multiple_high') {
+    return `Multiple matches found. Use "show [id]" for specific details`;
+  }
+  return '';
+}
+```
+
+## 7. 참고 자료
+
+- **claude-mem README**: Progressive disclosure pattern, MCP tools
+- **OpenAI Cookbook**: Token counting and optimization
+- **AXIOMMIND**: Principle 7 (Standard JSON) - 포맷 일관성
+- **기존 specs**: retriever.ts, matcher.ts 구현
+
+## 2026-02-25T12:31:26.406Z | 65bf8cff-b5ca-4506-b45b-abb5fc746a5c
+- type: session_summary
+- session: import:organized
+# Progressive Disclosure Implementation Plan
+
+> **Version**: 1.0.0
+> **Status**: Draft
+> **Created**: 2026-02-01
+
+## Phase 1: 타입 및 인터페이스 정의 (P0)
+
+### 1.1 스키마 정의
+
+**파일**: `src/core/types.ts` 수정
+
+```typescript
+// Layer 1: 검색 인덱스
+export const SearchIndexItemSchema = z.object({
+  id: z.string(),
+  summary: z.string().max(100),
+  score: z.number(),
+  type: z.enum(['prompt', 'response', 'tool', 'insight']),
+  timestamp: z.date(),
+  sessionId: z.string()
+});
+
+// Layer 2: 타임라인
+export const TimelineItemSchema = z.object({
+  id: z.string(),
+  timestamp: z.date(),
+  type: z.enum(['prompt', 'response', 'tool', 'insight']),
+  preview: z.string().max(200),
+  isTarget: z.boolean()
+});
+
+// Layer 3: 상세
+export const FullDetailSchema = z.object({
+  id: z.string(),
+  content: z.string(),
+  type: z.enum(['prompt', 'response', 'tool', 'insight']),
+  timestamp: z.date(),
+  sessionId: z.string(),
+  metadata: z.object({
+    tokenCount: z.number(),
+    hasCode: z.boolean(),
+    files: z.array(z.string()).optional(),
+    tools: z.array(z.string()).optional()
+  }),
+  relations: z.object({
+    parentId: z.string().optional(),
+    childIds: z.array(z.string()),
+    relatedIds: z.array(z.string())
+  }).optional()
+});
+```
+
+**작업 항목**:
+- [ ] SearchIndexItemSchema 추가
+- [ ] TimelineItemSchema 추가
+- [ ] FullDetailSchema 추가
+- [ ] ProgressiveSearchResultSchema 추가
+
+### 1.2 설정 스키마 확장
+
+**파일**: `src/core/types.ts` 수정
+
+```typescript
+export const ProgressiveDisclosureConfigSchema = z.object({
+  enabled: z.boolean().default(true),
+  layer1: z.object({
+    topK: z.number().default(10),
+    minScore: z.number().default(0.7)
+  }),
+  autoExpand: z.object({
+    enabled: z.boolean().default(true),
+    highConfidenceThreshold: z.number().default(0.92),
+    scoreGapThreshold: z.number().default(0.1),
+    maxAutoExpandCount: z.number().default(3)
+  }),
+  tokenBudget: z.object({
+    maxTotalTokens: z.number().default(2000),
+    layer1PerItem: z.number().default(50),
+    layer2PerItem: z.number().default(40),
+    layer3PerItem: z.number().default(500)
+  }),
+  cache: z.object({
+    layer1Ttl: z.number().default(60000),
+    layer2Ttl: z.number().default(300000),
+    layer3Ttl: z.number().default(1800000)
+  })
+});
+```
+
+**작업 항목**:
+- [ ] ProgressiveDisclosureConfigSchema 추가
+- [ ] ConfigSchema에 progressiveDisclosure 필드 추가
+
+## Phase 2: ProgressiveRetriever 구현 (P0)
+
+### 2.1 기본 클래스 구조
+
+**파일**: `src/core/progressive-retriever.ts` (신규)
+
+```typescript
+export class ProgressiveRetriever {
+  constructor(
+    private eventStore: EventStore,
+    private vectorStore: VectorStore,
+    private config: ProgressiveDisclosureConfig
+  ) {}
+
+  // Layer 1: 검색 인덱스
+  async searchIndex(
+    query: string,
+    options?: { topK?: number; filter?: SearchFilter }
+  ): Promise<SearchIndexItem[]> {
+    const { topK = this.config.layer1.topK } = options || {};
+
+    // 벡터 검색
+    const vectorResults = await this.vectorStore.search(query, { topK });
+
+    // 요약 생성 및 변환
+    return vectorResults.map(r => ({
+      id: r.id,
+      summary: this.generateSummary(r.content),
+      score: r.score,
+      type: r.metadata.type,
+      timestamp: r.metadata.timestamp,
+      sessionId: r.metadata.sessionId
+    }));
+  }
+
+  // Layer 2: 타임라인
+  async getTimeline(
+    targetIds: string[],
+    options?: { windowSize?: number }
+  ): Promise<TimelineItem[]> {
+    const { windowSize = 3 } = options || {};
+
+    const items: TimelineItem[] = [];
+
+    for (const targetId of targetIds) {
+      const event = await this.eventStore.findById(targetId);
+      if (!event) continue;
+
+      // 주변 이벤트 조회
+      const surrounding = await this.eventStore.findSurrounding(
+        event.sessionId,
+        event.timestamp,
+        windowSize
+      );
+
+      items.push(...surrounding.map(e => ({
+        id: e.eventId,
+        timestamp: e.timestamp,
+        type: e.eventType,
+        preview: this.generatePreview(e.payload),
+        isTarget: e.eventId === targetId
+      })));
+    }
+
+    return this.deduplicateTimeline(items);
+  }
+
+  // Layer 3: 상세 정보
+  async getDetails(ids: string[]): Promise<FullDetail[]> {
+    const details: FullDetail[] = [];
+
+    for (const id of ids) {
+      const event = await this.eventStore.findById(id);
+      if (!event) continue;
+
+      details.push({
+        id: event.eventId,
+        content: event.payload.content,
+        type: event.eventType,
+        timestamp: event.timestamp,
+        sessionId: event.sessionId,
+        metadata: this.extractMetadata(event),
+        relations: await this.getRelations(event)
+      });
+    }
+
+    return details;
+  }
+}
+```
+
+**작업 항목**:
+- [ ] searchIndex 메서드 구현
+- [ ] getTimeline 메서드 구현
+- [ ] getDetails 메서드 구현
+- [ ] generateSummary 헬퍼 구현
+- [ ] generatePreview 헬퍼 구현
+
+### 2.2 스마트 검색 구현
+
+**파일**: `src/core/progressive-retriever.ts` 계속
+
+```typescript
+async smartSearch(
+  query: string,
+  options?: SmartSearchOptions
+): Promise<ProgressiveSearchResult> {
+  const config = { ...this.config, ...options };
+
+  // Layer 1: 항상 실행
+  const index = await this.searchIndex(query, {
+    topK: config.layer1.topK,
+    filter: options?.filter
+  });
+
+  const result: ProgressiveSearchResult = {
+    index,
+    meta: {
+      totalMatches: index.length,
+      expandedCount: 0,
+      estimatedTokens: this.estimateTokens(index, 'layer1')
+    }
+  };
+
+  // 자동 확장 결정
+  if (config.autoExpand.enabled) {
+    const decision = this.shouldAutoExpand(index, config);
+
+    if (decision.expandTimeline && decision.ids) {
+      result.timeline = await this.getTimeline(decision.ids);
+      result.meta.estimatedTokens += this.estimateTokens(result.timeline, 'layer2');
+    }
+
+    if (decision.expandDetails && decision.ids) {
+      // 토큰 예산 체크
+      const remainingBudget = config.tokenBudget.maxTotalTokens - result.meta.estimatedTokens;
+      const idsToExpand = this.selectWithinBudget(decision.ids, remainingBudget);
+
+      result.details = await this.getDetails(idsToExpand);
+      result.meta.expandedCount = idsToExpand.length;
+      result.meta.estimatedTokens += this.estimateTokens(result.details, 'layer3');
+    }
+
+    result.meta.expansionReason = decision.reason;
+  }
+
+  return result;
+}
+```
+
+**작업 항목**:
+- [ ] smartSearch 메서드 구현
+- [ ] shouldAutoExpand 로직 구현
+- [ ] selectWithinBudget 토큰 예산 관리
+
+### 2.3 확장 규칙 엔진
+
+**파일**: `src/core/expansion-rules.ts` (신규)
+
+```typescript
+interface ExpansionDecision {
+  expand: boolean;
+  expandTimeline?: boolean;
+  expandDetails?: boolean;
+  ids?: string[];
+  reason: string;
+}
+
+export function shouldAutoExpand(
+  results: SearchIndexItem[],
+  config: ProgressiveDisclosureConfig
+): ExpansionDecision {
+  if (results.length === 0) {
+    return { expand: false, reason: 'no_results' };
+  }
+
+  const topScore = results[0].score;
+
+  // Rule 1: 높은 신뢰도 단일 결과
+  if (topScore >= config.autoExpand.highConfidenceThreshold && results.length === 1) {
+    return {
+      expand: true,
+      expandTimeline: true,
+      expandDetails: true,
+      ids: [results[0].id],
+      reason: 'high_confidence_single'
+    };
+  }
+
+  // Rule 2: 명확한 1등
+  if (results.length >= 2) {
+    const gap = results[0].score - results[1].score;
+    if (topScore >= 0.85 && gap >= config.autoExpand.scoreGapThreshold) {
+      return {
+        expand: true,
+        expandTimeline: true,
+        expandDetails: true,
+        ids: [results[0].id],
+        reason: 'clear_winner'
+      };
+    }
+  }
+
+  // Rule 3: 모호한 결과 → 타임라인만
+  const highScoreCount = results.filter(r => r.score >= 0.8).length;
+  if (highScoreCount >= 3) {
+    return {
+      expand: true,
+      expandTimeline: true,
+      expandDetails: false,
+      ids: results.slice(0, 3).map(r => r.id),
+      reason: 'ambiguous_multiple_high'
+    };
+  }
+
+  // Rule 4: 낮은 점수
+  return { expand: false, reason: 'low_confidence' };
+}
+```
+
+**작업 항목**:
+- [ ] 확장 규칙 함수 구현
+- [ ] 규칙별 테스트 케이스
+
+## Phase 3: 요약 및 미리보기 생성 (P0)
+
+### 3.1 요약 생성기
+
+**파일**: `src/core/summarizer.ts` (신규)
+
+```typescript
+export function generateSummary(content: string, maxLength: number = 100): string {
+  // 1. 코드 블록 제거
+  const withoutCode = content.replace(/```[\s\S]*?```/g, '[code]');
+
+  // 2. 첫 문장 추출
+  const firstSentence = withoutCode.match(/^[^.!?]+[.!?]/)?.[0] || '';
+
+  // 3. 길이 제한
+  if (firstSentence.length <= maxLength) {
+    return firstSentence.trim();
+  }
+
+  // 4. 단어 경계에서 자르기
+  return withoutCode.slice(0, maxLength).replace(/\s+\S*$/, '') + '...';
+}
+
+export function generatePreview(content: string, maxLength: number = 200): string {
+  // 1. 코드 블록 축약
+  const withCodeSummary = content.replace(
+    /```(\w+)[\s\S]*?```/g,
+    (_, lang) => `[${lang} code]`
+  );
+
+  // 2. 줄바꿈 정리
+  const singleLine = withCodeSummary.replace(/\n+/g, ' ').trim();
+
+  // 3. 길이 제한
+  if (singleLine.length <= maxLength) {
+    return singleLine;
+  }
+
+  return singleLine.slice(0, maxLength).replace(/\s+\S*$/, '') + '...';
+}
+```
+
+**작업 항목**:
+- [ ] generateSummary 함수 구현
+- [ ] generatePreview 함수 구현
+- [ ] 코드 블록 처리 로직
+- [ ] 특수 문자 처리
+
+### 3.2 토큰 추정기
+
+**파일**: `src/core/token-estimator.ts` (신규)
+
+```typescript
+// 간단한 토큰 추정 (GPT tokenizer 근사)
+export function estimateTokens(text: string): number {
+  // 평균적으로 4자 = 1토큰
+  return Math.ceil(text.length / 4);
+}
+
+export function estimateLayerTokens(
+  items: unknown[],
+  layer: 'layer1' | 'layer2' | 'layer3',
+  config: ProgressiveDisclosureConfig
+): number {
+  switch (layer) {
+    case 'layer1':
+      return items.length * config.tokenBudget.layer1PerItem;
+    case 'layer2':
+      return items.length * config.tokenBudget.layer2PerItem;
+    case 'layer3':
+      // Layer 3는 실제 콘텐츠 기반
+      return (items as FullDetail[]).reduce(
+        (sum, item) => sum + estimateTokens(item.content),
+        0
+      );
+  }
+}
+```
+
+**작업 항목**:
+- [ ] estimateTokens 함수 구현
+- [ ] estimateLayerTokens 함수 구현
+
+## Phase 4: 캐싱 (P1)
+
+### 4.1 캐시 매니저
+
+**파일**: `src/core/cache-manager.ts` (신규)
+
+```typescript
+import { LRUCache } from 'lru-cache';
+
+export class ProgressiveCache {
+  private layer1Cache: LRUCache<string, SearchIndexItem[]>;
+  private layer2Cache: LRUCache<string, TimelineItem[]>;
+  private layer3Cache: LRUCache<string, FullDetail>;
+
+  constructor(config: ProgressiveDisclosureConfig) {
+    this.layer1Cache = new LRUCache({
+      max: 100,
+      ttl: config.cache.layer1Ttl
+    });
+
+    this.layer2Cache = new LRUCache({
+      max: 500,
+      ttl: config.cache.layer2Ttl
+    });
+
+    this.layer3Cache = new LRUCache({
+      max: 200,
+      ttl: config.cache.layer3Ttl
+    });
+  }
+
+  // Layer 1 캐시
+  getLayer1(query: string, options: SearchOptions): SearchIndexItem[] | undefined {
+    const key = this.buildLayer1Key(query, options);
+    return this.layer1Cache.get(key);
+  }
+
+  setLayer1(query: string, options: SearchOptions, results: SearchIndexItem[]): void {
+    const key = this.buildLayer1Key(query, options);
+    this.layer1Cache.set(key, results);
+  }
+
+  // ... Layer 2, 3 유사 구현
+}
+```
+
+**작업 항목**:
+- [ ] ProgressiveCache 클래스 구현
+- [ ] Layer별 캐시 키 생성
+- [ ] TTL 및 크기 제한 적용
+
+## Phase 5: 포맷터 (P0)
+
+### 5.1 컨텍스트 포맷터
+
+**파일**: `src/core/context-formatter.ts` (신규)
+
+```typescript
+export class ContextFormatter {
+  formatProgressiveResult(result: ProgressiveSearchResult): string {
+    const parts: string[] = [];
+
+    // Layer 1: 항상 포함
+    parts.push(this.formatLayer1(result.index));
+
+    // Layer 2: 타임라인
+    if (result.timeline) {
+      parts.push(this.formatLayer2(result.timeline));
+    }
+
+    // Layer 3: 상세
+    if (result.details) {
+      parts.push(this.formatLayer3(result.details));
+    }
+
+    // 메타 정보
+    parts.push(this.formatMeta(result.meta));
+
+    return parts.join('\n\n');
+  }
+
+  private formatLayer1(items: SearchIndexItem[]): string {
+    const header = `## Related Memories (${items.length} matches)\n`;
+    const table = items.map((item, i) =>
+      `${i + 1}. [${item.id}] ${item.summary} (score: ${item.score.toFixed(2)})`
+    ).join('\n');
+
+    return header + table;
+  }
+
+  private formatLayer2(items: TimelineItem[]): string {
+    const header = '## Timeline Context\n';
+    const timeline = items.map(item => {
+      const marker = item.isTarget ? '**→**' : '  ';
+      const time = item.timestamp.toLocaleTimeString();
+      return `${marker} ${time}: ${item.preview}`;
+    }).join('\n');
+
+    return header + timeline;
+  }
+
+  private formatLayer3(items: FullDetail[]): string {
+    return items.map(item => {
+      const header = `## Detail: ${item.id}\n`;
+      const meta = `*Session: ${item.sessionId} | ${item.timestamp.toLocaleDateString()}*\n`;
+      return header + meta + '\n' + item.content;
+    }).join('\n\n---\n\n');
+  }
+}
+```
+
+**작업 항목**:
+- [ ] ContextFormatter 클래스 구현
+- [ ] Layer별 포맷 함수
+- [ ] Markdown 출력 최적화
+
+## Phase 6: 통합 (P0)
+
+### 6.1 Retriever 교체
+
+**파일**: `src/core/retriever.ts` 수정
+
+```typescript
+export class Retriever {
+  private progressiveRetriever: ProgressiveRetriever;
+
+  constructor(/* ... */) {
+    this.progressiveRetriever = new ProgressiveRetriever(
+      this.eventStore,
+      this.vectorStore,
+      config.progressiveDisclosure
+    );
+  }
+
+  // 기존 메서드를 progressive로 위임
+  async search(query: string): Promise<SearchResult[]> {
+    if (this.config.progressiveDisclosure?.enabled) {
+      const result = await this.progressiveRetriever.smartSearch(query);
+      return this.convertToLegacyFormat(result);
+    }
+
+    // 기존 로직 유지 (fallback)
+    return this.legacySearch(query);
+  }
+
+  // 새로운 progressive 검색
+  async progressiveSearch(query: string, options?: SmartSearchOptions): Promise<ProgressiveSearchResult> {
+    return this.progressiveRetriever.smartSearch(query, options);
+  }
+}
+```
+
+**작업 항목**:
+- [ ] Retriever에 progressiveRetriever 통합
+- [ ] 기존 API 호환성 유지
+- [ ] 새 API 추가
+
+### 6.2 user-prompt-submit 훅 수정
+
+**파일**: `src/hooks/user-prompt-submit.ts` 수정
+
+```typescript
+async function handleUserPromptSubmit(input: UserPromptInput): Promise<HookOutput> {
+  const memoryService = await MemoryService.getInstance();
+  const config = memoryService.getConfig();
+
+  // Progressive 검색 사용
+  const searchResult = await memoryService.progressiveSearch(input.prompt, {
+    maxTotalTokens: config.retrieval.maxTokens
+  });
+
+  // 포맷팅
+  const formatter = new ContextFormatter();
+  const context = formatter.formatProgressiveResult(searchResult);
+
+  return {
+    context,
+    meta: {
+      matchCount: searchResult.meta.totalMatches,
+      expandedCount: searchResult.meta.expandedCount,
+      estimatedTokens: searchResult.meta.estimatedTokens
+    }
+  };
+}
+```
+
+**작업 항목**:
+- [ ] 훅에서 progressive 검색 사용
+- [ ] 메타 정보 반환
+
+## 파일 목록
+
+### 신규 파일
+```
+src/core/progressive-retriever.ts   # 메인 검색 클래스
+src/core/expansion-rules.ts         # 확장 규칙 엔진
+src/core/summarizer.ts              # 요약/미리보기 생성
+src/core/token-estimator.ts         # 토큰 추정
+src/core/cache-manager.ts           # 캐시 관리
+src/core/context-formatter.ts       # 출력 포맷팅
+```
+
+### 수정 파일
+```
+src/core/types.ts                   # 스키마 추가
+src/core/retriever.ts               # Progressive 통합
+src/hooks/user-prompt-submit.ts     # 검색 방식 변경
+src/services/memory-service.ts      # 서비스 메서드 추가
+```
+
+## 테스트
+
+### 필수 테스트 케이스
+
+1. **Layer 1 검색**
+   ```typescript
+   test('should return index with summaries', async () => {
+     const result = await retriever.searchIndex('DuckDB 스키마');
+     expect(result[0]).toHaveProperty('summary');
+     expect(result[0].summary.length).toBeLessThanOrEqual(100);
+   });
+   ```
+
+2. **자동 확장 규칙**
+   ```typescript
+   test('should expand on high confidence', async () => {
+     const result = await retriever.smartSearch('unique term');
+     expect(result.details).toBeDefined();
+     expect(result.meta.expansionReason).toBe('high_confidence_single');
+   });
+   ```
+
+3. **토큰 예산**
+   ```typescript
+   test('should respect token budget', async () => {
+     const result = await retriever.smartSearch('query', { maxTotalTokens: 500 });
+     expect(result.meta.estimatedTokens).toBeLessThanOrEqual(500);
+   });
+   ```
+
+4. **캐싱**
+   ```typescript
+   test('should use cache on repeat query', async () => {
+     await retriever.searchIndex('test');
+     const start = Date.now();
+     await retriever.searchIndex('test');
+     expect(Date.now() - start).toBeLessThan(10);
+   });
+   ```
+
+## 마일스톤
+
+| 단계 | 완료 기준 |
+|------|----------|
+| M1 | 타입 정의 완료 |
+| M2 | ProgressiveRetriever 기본 구현 |
+| M3 | 확장 규칙 엔진 |
+| M4 | 요약/미리보기 생성 |
+| M5 | 토큰 예산 관리 |
+| M6 | 캐싱 구현 |
+| M7 | 포맷터 및 통합 |
+| M8 | 테스트 통과 |
+
+## 2026-02-25T12:31:26.413Z | 8c526a4e-bfe7-4bdc-86c8-f16fe06f0faf
+- type: session_summary
+- session: import:organized
+# Progressive Disclosure Specification
+
+> **Version**: 1.0.0
+> **Status**: Draft
+> **Created**: 2026-02-01
+> **Reference**: claude-mem (thedotmack/claude-mem)
+
+## 1. 개요
+
+### 1.1 문제 정의
+
+현재 시스템에서 메모리 검색 시 토큰 비효율 발생:
+
+1. **전체 로드 문제**: 검색 결과를 한 번에 모든 내용을 가져옴
+2. **토큰 낭비**: 관련 없는 내용도 컨텍스트에 포함
+3. **컨텍스트 한계**: 대용량 메모리 사용 시 토큰 초과
+
+### 1.2 해결 방향
+
+**3-Layer Progressive Disclosure**:
+- Layer 1: 검색 인덱스 (ID + 요약) - 최소 토큰
+- Layer 2: 타임라인 컨텍스트 - 시간순 맥락
+- Layer 3: 상세 정보 - 선택된 항목만 전체 로드
+
+## 2. 핵심 개념
+
+### 2.1 3-Layer 아키텍처
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    User Query                                │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│  Layer 1: Search Index (~50-100 tokens per result)          │
+│  ┌──────────────────────────────────────────────────────┐  │
+│  │ { id: "mem_1", summary: "파일 구조 설명", score: 0.95 } │  │
+│  │ { id: "mem_2", summary: "타입 정의 논의", score: 0.87 } │  │
+│  │ { id: "mem_3", summary: "버그 수정 방법", score: 0.82 } │  │
+│  └──────────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                    (선택적 확장)
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│  Layer 2: Timeline Context (~200 tokens)                    │
+│  ┌──────────────────────────────────────────────────────┐  │
+│  │ 2026-01-30 14:00: "파일 구조 변경 결정"                 │  │
+│  │ 2026-01-30 14:15: "types.ts 분리" ← mem_1             │  │
+│  │ 2026-01-30 14:30: "테스트 작성"                        │  │
+│  └──────────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                    (필요 시만)
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│  Layer 3: Full Details (~500-1000 tokens per result)        │
+│  ┌──────────────────────────────────────────────────────┐  │
+│  │ mem_1: {                                               │  │
+│  │   content: "전체 대화 내용...",                        │  │
+│  │   metadata: {...},                                     │  │
+│  │   evidence: [...]                                      │  │
+│  │ }                                                      │  │
+│  └──────────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### 2.2 토큰 효율성
+
+| 방식 | 5개 결과 토큰 | 20개 결과 토큰 |
+|------|--------------|---------------|
+| 기존 (전체 로드) | ~5,000 | ~20,000 |
+| Progressive L1 | ~500 | ~2,000 |
+| Progressive L1+L2 | ~700 | ~2,200 |
+| Progressive L1+L2+L3 (2개) | ~1,700 | ~2,200 |
+
+**예상 토큰 절약: ~10배**
+
+### 2.3 확장 트리거
+
+```typescript
+type ExpansionTrigger =
+  | 'high_confidence'     // score ≥ 0.92 → 자동 L3 확장
+  | 'user_request'        // "자세히 알려줘" → L3 확장
+  | 'temporal_proximity'  // 시간적 근접 → L2 확장
+  | 'explicit_id'         // "mem_1 보여줘" → L3 확장
+  | 'ambiguity';          // 여러 유사 결과 → L2 확장
+```
+
+## 3. 데이터 스키마
+
+### 3.1 Layer 1: SearchIndex
+
+```typescript
+const SearchIndexItemSchema = z.object({
+  id: z.string(),                    // 이벤트/메모리 ID
+  summary: z.string().max(100),      // 한 줄 요약
+  score: z.number(),                 // 유사도 점수
+  type: z.enum(['prompt', 'response', 'tool', 'insight']),
+  timestamp: z.date(),
+  sessionId: z.string()
+});
+
+type SearchIndexItem = z.infer<typeof SearchIndexItemSchema>;
+
+// 반환 예시
+{
+  id: "evt_abc123",
+  summary: "DuckDB 스키마 설계 논의",
+  score: 0.94,
+  type: "response",
+  timestamp: "2026-01-30T14:00:00Z",
+  sessionId: "session_xyz"
+}
+```
+
+### 3.2 Layer 2: TimelineContext
+
+```typescript
+const TimelineItemSchema = z.object({
+  id: z.string(),
+  timestamp: z.date(),
+  type: z.enum(['prompt', 'response', 'tool', 'insight']),
+  preview: z.string().max(200),      // 2-3문장 미리보기
+  isTarget: z.boolean()              // 검색 결과에 해당하는지
+});
+
+type TimelineItem = z.infer<typeof TimelineItemSchema>;
+
+// 반환 예시 (target ID 주변 ±3개)
+[
+  { id: "evt_1", preview: "이전 대화...", isTarget: false },
+  { id: "evt_2", preview: "관련 질문...", isTarget: false },
+  { id: "evt_abc123", preview: "DuckDB 스키마...", isTarget: true },  // 타겟
+  { id: "evt_3", preview: "후속 논의...", isTarget: false }
+]
+```
+
+### 3.3 Layer 3: FullDetail
+
+```typescript
+const FullDetailSchema = z.object({
+  id: z.string(),
+  content: z.string(),               // 전체 내용
+  type: z.enum(['prompt', 'response', 'tool', 'insight']),
+  timestamp: z.date(),
+  sessionId: z.string(),
+
+  // 메타데이터
+  metadata: z.object({
+    tokenCount: z.number(),
+    hasCode: z.boolean(),
+    files: z.array(z.string()).optional(),
+    tools: z.array(z.string()).optional()
+  }),
+
+  // 관계 정보
+  relations: z.object({
+    parentId: z.string().optional(),
+    childIds: z.array(z.string()),
+    relatedIds: z.array(z.string())
+  }).optional()
+});
+
+type FullDetail = z.infer<typeof FullDetailSchema>;
+```
+
+## 4. API 인터페이스
+
+### 4.1 ProgressiveRetriever
+
+```typescript
+interface ProgressiveRetriever {
+  // Layer 1: 검색 인덱스 반환
+  searchIndex(
+    query: string,
+    options?: {
+      topK?: number;
+      filter?: SearchFilter;
+    }
+  ): Promise<SearchIndexItem[]>;
+
+  // Layer 2: 타임라인 컨텍스트 반환
+  getTimeline(
+    targetIds: string[],
+    options?: {
+      windowSize?: number;  // 앞뒤로 몇 개씩
+    }
+  ): Promise<TimelineItem[]>;
+
+  // Layer 3: 상세 정보 반환
+  getDetails(ids: string[]): Promise<FullDetail[]>;
+
+  // 편의 메서드: 자동 확장
+  smartSearch(
+    query: string,
+    options?: SmartSearchOptions
+  ): Promise<ProgressiveSearchResult>;
+}
+```
+
+### 4.2 SmartSearch 옵션
+
+```typescript
+interface SmartSearchOptions {
+  // Layer 1 설정
+  topK: number;                       // 기본: 10
+  minScore: number;                   // 기본: 0.7
+
+  // 자동 확장 설정
+  autoExpandTimeline: boolean;        // 기본: true (score gap 클 때)
+  autoExpandDetails: boolean;         // 기본: true (score ≥ 0.92)
+  maxAutoExpandCount: number;         // 기본: 3
+
+  // 토큰 제한
+  maxTotalTokens: number;             // 기본: 2000
+}
+```
+
+### 4.3 ProgressiveSearchResult
+
+```typescript
+interface ProgressiveSearchResult {
+  // Layer 1 (항상 포함)
+  index: SearchIndexItem[];
+
+  // Layer 2 (선택적)
+  timeline?: TimelineItem[];
+
+  // Layer 3 (선택적)
+  details?: FullDetail[];
+
+  // 메타정보
+  meta: {
+    totalMatches: number;
+    expandedCount: number;
+    estimatedTokens: number;
+    expansionReason?: string;
+  };
+}
+```
+
+## 5. 확장 규칙
+
+### 5.1 자동 확장 조건
+
+```typescript
+function shouldAutoExpand(results: SearchIndexItem[]): ExpansionDecision {
+  // Rule 1: 높은 신뢰도 단일 결과
+  if (results[0]?.score >= 0.92 && results.length === 1) {
+    return { expand: true, ids: [results[0].id], reason: 'high_confidence' };
+  }
+
+  // Rule 2: 명확한 1등 (2등과 gap이 큼)
+  if (results.length >= 2) {
+    const gap = results[0].score - results[1].score;
+    if (results[0].score >= 0.85 && gap >= 0.1) {
+      return { expand: true, ids: [results[0].id], reason: 'clear_winner' };
+    }
+  }
+
+  // Rule 3: 모호한 결과 → 타임라인만 확장
+  if (results.length >= 3 && results[2].score >= 0.8) {
+    return {
+      expand: true,
+      expandTimeline: true,
+      expandDetails: false,
+      ids: results.slice(0, 3).map(r => r.id),
+      reason: 'ambiguous_results'
+    };
+  }
+
+  // Rule 4: 낮은 점수 → 확장 안 함
+  return { expand: false, reason: 'low_confidence' };
+}
+```
+
+### 5.2 토큰 예산 관리
+
+```typescript
+function expandWithinBudget(
+  index: SearchIndexItem[],
+  budget: number
+): ProgressiveSearchResult {
+  let usedTokens = estimateTokens(index);  // ~50-100 per item
+  const result: ProgressiveSearchResult = { index, meta: { ... } };
+
+  // 예산 내에서 확장
+  const sortedByScore = [...index].sort((a, b) => b.score - a.score);
+
+  for (const item of sortedByScore) {
+    if (usedTokens >= budget) break;
+
+    // 타임라인 추가 (~200 tokens)
+    if (usedTokens + 200 <= budget && !result.timeline) {
+      result.timeline = await getTimeline([item.id]);
+      usedTokens += estimateTokens(result.timeline);
+    }
+
+    // 상세 추가 (~500-1000 tokens)
+    if (item.score >= 0.85 && usedTokens + 800 <= budget) {
+      const detail = await getDetails([item.id]);
+      result.details = [...(result.details || []), ...detail];
+      usedTokens += estimateTokens(detail);
+    }
+  }
+
+  result.meta.estimatedTokens = usedTokens;
+  return result;
+}
+```
+
+## 6. 컨텍스트 포맷
+
+### 6.1 Layer 1 포맷 (최소)
+
+```markdown
+## Related Memories (5 matches)
+
+| ID | Summary | Score |
+|----|---------|-------|
+| mem_1 | DuckDB 스키마 설계 논의 | 0.94 |
+| mem_2 | 타입 시스템 리팩토링 | 0.87 |
+| mem_3 | 벡터 저장소 설정 | 0.82 |
+| mem_4 | 테스트 코드 작성 | 0.78 |
+| mem_5 | CI/CD 파이프라인 | 0.75 |
+
+*Use "show mem_1" for details*
+```
+
+### 6.2 Layer 2 포맷 (타임라인)
+
+```markdown
+## Related Memories with Timeline
+
+### Context around mem_1 (2026-01-30)
+
+14:00 - User: "DB 스키마를 어떻게 설계할까?"
+14:05 - **[mem_1]** Assistant: "DuckDB를 사용하여 이벤트 소싱 패턴..."
+14:15 - User: "인덱스는 어떻게?"
+14:20 - Assistant: "다음 인덱스들을 추천..."
+```
+
+### 6.3 Layer 3 포맷 (상세)
+
+```markdown
+## Memory Detail: mem_1
+
+**Session**: session_xyz | **Date**: 2026-01-30 14:05
+
+### Content
+DuckDB를 사용하여 이벤트 소싱 패턴을 구현하는 방법을 설명드립니다.
+
+1. events 테이블 생성:
+\`\`\`sql
+CREATE TABLE events (
+  event_id VARCHAR PRIMARY KEY,
+  ...
+);
+\`\`\`
+
+2. 인덱스 설계:
+- event_type별 인덱스
+- session_id별 인덱스
+...
+
+**Related Files**: src/core/event-store.ts, src/core/types.ts
+**Tools Used**: Read, Write
+```
+
+## 7. 캐싱 전략
+
+### 7.1 Layer별 캐싱
+
+```typescript
+interface CacheConfig {
+  layer1: {
+    ttl: 60 * 1000,        // 1분 (검색 결과)
+    maxSize: 100           // 최근 100개 쿼리
+  };
+  layer2: {
+    ttl: 5 * 60 * 1000,    // 5분 (타임라인)
+    maxSize: 500
+  };
+  layer3: {
+    ttl: 30 * 60 * 1000,   // 30분 (상세 정보)
+    maxSize: 200
+  };
+}
+```
+
+### 7.2 캐시 키
+
+```typescript
+function getCacheKey(layer: number, params: unknown): string {
+  switch (layer) {
+    case 1:
+      return `l1:${hash(params.query)}:${params.topK}`;
+    case 2:
+      return `l2:${params.targetIds.sort().join(',')}`;
+    case 3:
+      return `l3:${params.id}`;
+  }
+}
+```
+
+## 8. 성공 기준
+
+- [ ] Layer 1 검색이 100ms 이내 반환
+- [ ] Layer 2 타임라인이 200ms 이내 반환
+- [ ] Layer 3 상세가 500ms 이내 반환
+- [ ] 평균 토큰 사용량이 기존 대비 50% 이상 감소
+- [ ] 자동 확장이 적절한 경우에만 동작
+- [ ] 토큰 예산 내에서 최적의 결과 제공