claude-memory-layer 1.0.0

package/specs/progressive-disclosure/spec.md

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

package/specs/task-entity-system/context.md

@@ -0,0 +1,297 @@
+# Task Entity System Context
+
+> **Version**: 1.0.0
+> **Created**: 2026-01-31
+
+## 1. 배경
+
+### 1.1 기존 설계의 한계
+
+현재 code-memory 시스템에서 Task는 `entries` 테이블에 저장되는 불변 기록으로 관리됩니다:
+
+```typescript
+// 기존: entries 테이블에 Task를 저장
+{
+  entry_id: "ent_abc123",
+  entry_type: "task",
+  title: "벡터 검색 구현",
+  content_json: { status: "in_progress", ... }
+}
+```
+
+**문제점**:
+
+1. **세션 A**에서 "벡터 검색 구현" Task 생성 → `ent_abc123`
+2. **세션 B**에서 같은 Task 언급 → `ent_def456` (새 entry 생성!)
+3. **세션 C**에서 "완료" 언급 → `ent_ghi789` (또 새 entry!)
+
+결과: 하나의 Task가 3개의 분리된 entry로 존재하며, 상태 추적 불가
+
+### 1.2 해결 방향
+
+**Entry와 Entity 분리**:
+
+| 구분 | Entry | Entity |
+|------|-------|--------|
+| 특성 | 불변 기록 | 상태 변화 개체 |
+| 예시 | Fact, Decision, Insight | Task, Condition, Artifact |
+| 생명주기 | 생성 후 변경 없음 | 이벤트로 상태 변화 |
+| 식별 | UUID | canonical_key |
+
+## 2. Memo.txt 참고 사항
+
+### 2.1 핵심 원칙 (섹션 2)
+
+> **5. Task는 entity**
+> - Task 상태(status/priority/blockers)는 이벤트 fold 결과로 계산
+> - 세션마다 Task entry를 새로 만들지 말고, 기존 task entity를 찾아 업데이트
+
+### 2.2 DB 스키마 (섹션 4.3)
+
+```sql
+CREATE TABLE entities (
+  entity_id      VARCHAR PRIMARY KEY,
+  entity_type    VARCHAR NOT NULL,       -- task|condition|artifact
+  canonical_key  VARCHAR NOT NULL,
+  title          VARCHAR NOT NULL,
+  stage          VARCHAR NOT NULL,
+  status         VARCHAR NOT NULL,
+  current_json   JSON NOT NULL,
+  ...
+);
+```
+
+### 2.3 Task 이벤트 타입 (섹션 7.2)
+
+- `task_created`
+- `task_status_changed`
+- `task_priority_changed`
+- `task_blockers_set` (mode=replace|suggest)
+- `task_transition_rejected`
+
+### 2.4 BlockerResolver 규칙 (섹션 7.3)
+
+1. 강한 ID/URL/키 패턴 → artifact로 get-or-create
+2. 명시 task_id → task로 연결
+3. Task 제목 매칭 실패 → **condition으로 fallback** (스텁 Task 생성 금지)
+
+## 3. Idris2 영감 적용
+
+### 3.1 의존적 타입 개념
+
+**Idris2의 Vector 타입**:
+```idris
+-- 길이가 타입에 인코딩됨
+data Vect : Nat -> Type -> Type where
+  Nil  : Vect 0 a
+  (::) : a -> Vect n a -> Vect (S n) a
+```
+
+**TypeScript 적용**:
+```typescript
+// 상태에 따라 blockers 필드 타입이 달라짐
+type TaskState =
+  | { status: 'blocked'; blockers: BlockerRef[] }  // 필수, 1개 이상
+  | { status: 'done'; blockers?: never };          // 없어야 함
+```
+
+### 3.2 불변식 (Invariants)
+
+**Idris2에서**:
+```idris
+-- 타입 시스템이 강제
+nonEmptyBlockers : (t : Task) -> t.status = Blocked -> NonEmpty t.blockers
+```
+
+**TypeScript + Zod에서**:
+```typescript
+// 런타임 검증
+const BlockedTaskSchema = z.object({
+  status: z.literal('blocked'),
+  blockers: z.array(BlockerRefSchema).min(1)  // 최소 1개 강제
+});
+```
+
+### 3.3 왜 실제 Idris2를 사용하지 않는가?
+
+**Memo.txt 섹션 11**:
+> "지금은 Python 쪽 구현이 핵심이므로, Idris는 Candidate/Verified 래퍼 기반으로만 최소 수정"
+
+**실용적 이유**:
+
+1. **학습 곡선**: 팀원 모두가 Idris2를 학습해야 함
+2. **도구 체인**: idris2 컴파일러 설치/관리 필요
+3. **통합 복잡도**: TypeScript ↔ Idris2 FFI 오버헤드
+4. **디버깅**: 두 언어 간 스택 트레이스 추적 어려움
+
+**TypeScript로 충분한 이유**:
+
+1. **Discriminated Union**: 상태별 타입 분리 가능
+2. **Zod**: 런타임 검증으로 불변식 강제
+3. **타입 가드**: 조건부 타입 narrowing
+4. **생태계**: 풍부한 라이브러리와 도구
+
+## 4. 기존 코드와의 관계
+
+### 4.1 types.ts
+
+현재 정의된 타입 활용:
+
+```typescript
+// 기존
+export type MatchConfidence = 'high' | 'suggested' | 'none';
+export const MATCH_THRESHOLDS = {
+  minCombinedScore: 0.92,
+  minGap: 0.03,
+  suggestionThreshold: 0.75
+};
+
+// 확장
+export type EntityType = 'task' | 'condition' | 'artifact';
+export type TaskStatus = 'pending' | 'in_progress' | 'blocked' | 'done' | 'cancelled';
+```
+
+### 4.2 canonical-key.ts
+
+현재 함수 확장:
+
+```typescript
+// 기존: 이벤트용 canonical key
+export function makeCanonicalKey(title: string, context?: {...}): string;
+
+// 확장: 엔티티 타입별 canonical key
+export function makeEntityCanonicalKey(
+  entityType: EntityType,
+  identifier: string,
+  context?: { project?: string }
+): string {
+  switch (entityType) {
+    case 'task':
+      return `task:${context?.project ?? 'default'}:${normalize(identifier)}`;
+    case 'condition':
+      return `cond:${context?.project ?? 'default'}:${normalize(identifier)}`;
+    case 'artifact':
+      return makeArtifactKey(identifier);
+  }
+}
+```
+
+### 4.3 event-store.ts
+
+현재 EventStore 활용:
+
+```typescript
+// 기존 append 메서드 재활용
+// Task 이벤트도 동일하게 append-only로 저장
+const event = {
+  eventType: 'task_created',
+  sessionId,
+  content: JSON.stringify(payload),
+  ...
+};
+await eventStore.append(event);
+```
+
+### 4.4 matcher.ts
+
+현재 Matcher 로직 확장:
+
+```typescript
+// 기존: 이벤트 매칭
+export class Matcher {
+  matchSearchResults(results: SearchResult[]): MatchResult;
+}
+
+// 확장: Task 매칭에도 동일 로직 적용
+export class TaskMatcher {
+  // MATCH_THRESHOLDS 재활용
+  findSimilar(title: string, project: string): MatchResult;
+}
+```
+
+## 5. 경계 조건
+
+### 5.1 Unknown Blocker 처리
+
+```typescript
+// Task가 blocked인데 blockedBy가 비어있으면
+if (task.status === 'blocked' && blockedByTexts.length === 0) {
+  // 자동으로 placeholder condition 생성
+  const placeholder = await createCondition({
+    text: `Unknown blocker for ${task.title}`,
+    meta: { auto_placeholder: true }
+  });
+  blockers.push({ kind: 'condition', entity_id: placeholder.id });
+}
+```
+
+### 5.2 상태 전이 거부
+
+```typescript
+// pending → done 직접 전이 시
+if (from === 'pending' && to === 'done') {
+  // task_transition_rejected 이벤트 발행
+  await eventStore.append({
+    eventType: 'task_transition_rejected',
+    content: JSON.stringify({
+      task_id: task.id,
+      from_status: 'pending',
+      to_status: 'done',
+      reason: 'Direct transition from pending to done is not allowed'
+    })
+  });
+
+  // in_progress로 보정
+  return 'in_progress';
+}
+```
+
+### 5.3 Condition → Task 해결
+
+```typescript
+// 나중에 "API 키 설정됨" condition이 실제 Task로 식별되면
+await eventStore.append({
+  eventType: 'condition_resolved_to',
+  content: JSON.stringify({
+    condition_id: 'cond_xyz',
+    resolved_to: { kind: 'task', entity_id: 'task_abc' }
+  })
+});
+```
+
+## 6. 성능 고려사항
+
+### 6.1 캐싱
+
+```typescript
+// Entity 조회 캐시 (LRU)
+const entityCache = new LRUCache<string, Entity>({
+  max: 1000,
+  ttl: 1000 * 60 * 5  // 5분
+});
+```
+
+### 6.2 배치 처리
+
+```typescript
+// Projector는 배치로 이벤트 처리
+const BATCH_SIZE = 100;
+const events = await eventStore.fetchSince(offset, { limit: BATCH_SIZE });
+```
+
+### 6.3 인덱스 활용
+
+```sql
+-- FTS 검색용
+CREATE INDEX idx_entities_search ON entities USING GIN(to_tsvector('english', search_text));
+
+-- canonical_key 조회용
+CREATE INDEX idx_entities_type_key ON entities(entity_type, canonical_key);
+```
+
+## 7. 참고 자료
+
+- **Memo.txt**: AxiomMind Memory Graduation Pipeline 지시서
+- **spec.md**: `src/core/types.ts` - 기존 타입 정의
+- **AXIOMMIND 원칙**: Principle 5 - Task는 Entity
+- **Idris2 개념**: Dependent types, Linear types