claude-memory-layer 1.0.27 → 1.0.29

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

@@ -1,1436 +0,0 @@
-
-## 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% 이상 감소
-- [ ] 자동 확장이 적절한 경우에만 동작
-- [ ] 토큰 예산 내에서 최적의 결과 제공