claude-memory-layer 1.0.31 → 1.0.33

package/specs/progressive-disclosure/spec.md

@@ -1,415 +0,0 @@
-# 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/selective-tool-observation/context.md

@@ -1,100 +0,0 @@
-# Context: Selective Storage (전체 이벤트 타입 분석)
-
-## 실측 데이터 (f4d5c120 / shopping_assistant)
-> SQLite events.sqlite 직접 쿼리 기준 (10,536개)
-
-### 이벤트 구성
-
-| eventType         | count  | 비율   | avg_len |
-|-------------------|--------|--------|---------|
-| tool_observation  | 7,212  | 68.5%  | 4,166   |
-| agent_response    | 2,222  | 21.1%  | 417     |
-| user_prompt       |   948  |  9.0%  | 620     |
-| session_summary   |   154  |  1.5%  | 172     |
-
----
-
-## 1. tool_observation 분석
-
-### 도구별 분포 (전체)
-
-| Tool         | count | avg_len | 저장 가치 |
-|--------------|-------|---------|-----------|
-| Read         | 2,285 | 4,678   | ❌ 낮음 (재현 가능) |
-| Bash         | 2,034 | 2,593   | ✅/⚠️ 조건부 |
-| Grep         | 1,338 | 1,931   | ❌ 낮음 (재현 가능) |
-| Edit         |   737 | 11,034  | ✅ 높음 (변경 기록) |
-| Write        |   323 | 5,042   | ✅ 높음 (생성 기록) |
-| Glob         |   171 | 3,733   | ❌ 낮음 (재현 가능) |
-| ToolSearch   |   133 | 301     | ❌ 낮음 (시스템 내부) |
-| Task         |   114 | 7,592   | ✅ 높음 (서브태스크 결과) |
-| Skill        |    23 | 203     | ❌ 낮음 |
-| ExitPlanMode |    10 | 5,594   | ⚠️ 조건부 |
-| EnterPlanMode|    10 | 275     | ❌ 낮음 |
-| Agent        |     6 | 8,320   | ✅ 높음 |
-| WebFetch     |     2 | 1,868   | ❌ 낮음 (재현 가능) |
-| 기타 MCP     |    ~16| -       | ⚠️ 케이스별 |
-
-### 문제
-- Read/Grep/Glob 합계 **3,794개 (52.6%)** → 모두 재현 가능, 저장 불필요
-- Bash 중 의미 없는 빈 출력 다수 존재 가능
-- 현재 제외 목록: TodoWrite, TodoRead만 (너무 좁음)
-
----
-
-## 2. agent_response 분석
-
-### 길이 분포
-
-| 구간         | count | 비율  | 특성 |
-|--------------|-------|-------|------|
-| < 50 chars   |   608 | 27.4% | 도구 체인 전환 메시지 |
-| 50~200 chars |   587 | 26.4% | 짧은 중간 응답 |
-| 200~1k chars |   758 | 34.1% | 실질적 내용 |
-| > 1k chars   |   269 | 12.1% | 명확히 가치 있음 |
-
-### 실제 저장된 짧은 응답 예시
-
-```
-[15]  "**문제 찾았습니다!** 🎯"
-[20]  "이제 실제로 서버를 시작해보겠습니다:"
-[44]  "code-server 문제를 진단해보겠습니다. 먼저 현재 상태를 확인하겠습니다."
-[50]  "이제 ChatGraph를 수정하여 ManualQuestionService를 통합합니다."
-```
-
-→ Claude가 다음 도구를 호출하기 전에 내뱉는 **전환 문장**. 단독 retrieval 가치 없음.
-
-### 문제
-- 608개 (27%)가 50자 미만 전환 메시지 → 노이즈
-- min-length 150자 적용 시 **~53% (1,195개) 감소** 가능
-
----
-
-## 3. user_prompt 분석
-
-### 문제: import 시 필터 미적용
-
-```
-[1]  '1', '2', '3'    ← 메뉴 번호 선택
-[2]  'go', 'go'       ← 단순 실행 명령
-[2]  '커밋', '커밋'   ← 한글 단어 2자
-[2]  '\x03\x03'       ← Ctrl+C 입력 (!!!)
-```
-
-- 188개가 15자 미만 쓰레기 입력
-- **원인**: 임포터가 shouldStorePrompt() 필터를 적용하지 않아 transcript의 모든 user 메시지 저장
-- Ctrl+C 입력까지 저장되는 것이 결정적 증거
-
----
-
-## 전체 최적화 효과 예측
-
-| 대상 | 현재 | 감소량 | 방법 |
-|------|------|--------|------|
-| tool_obs / Read+Grep+Glob+ToolSearch | 3,927개 | -3,927 | blocklist |
-| tool_obs / Bash (empty output) | ~500개 | -500 | min-output-len |
-| tool_obs / Skill+EnterPlanMode | ~33개 | -33 | blocklist |
-| agent_response < 150자 | ~1,195개 | -1,195 | min-length |
-| user_prompt tiny (import) | 188개 | -188 | importer 필터 |
-| **합계** | **10,536개** | **약 -5,843개** | |
-| **결과** | | **→ 약 4,693개** | **-55% 감소** |

package/specs/selective-tool-observation/plan.md

@@ -1,158 +0,0 @@
-# Plan: Selective Storage Filtering
-
-## 구현 범위
-
-3개 파일 수정, 스키마 변경 없음.
-
----
-
-## Step 1. post-tool-use.ts — blocklist 확장 + output 필터
-
-### 1-1. DEFAULT_CONFIG 업데이트
-
-```ts
-const DEFAULT_CONFIG: Config['toolObservation'] = {
-  enabled: true,
-  excludedTools: [
-    // 기존
-    'TodoWrite', 'TodoRead',
-    // 추가: 재현 가능한 조회 도구
-    'Read', 'Grep', 'Glob',
-    'ToolSearch', 'WebFetch', 'WebSearch', 'NotebookRead',
-    // 추가: 저가치 시스템 도구
-    'Skill', 'EnterPlanMode',
-  ],
-  minOutputLength: parseInt(process.env.CLAUDE_MEMORY_TOOL_MIN_OUTPUT_LEN || '100'),
-  maxOutputLength: 10000,
-  maxOutputLines: 100,
-  storeOnlyOnSuccess: false
-};
-```
-
-### 1-2. 환경변수 오버라이드
-
-```ts
-const envBlocklist = process.env.CLAUDE_MEMORY_TOOL_BLOCKLIST;
-if (envBlocklist) {
-  config.excludedTools = envBlocklist.split(',').map(s => s.trim());
-}
-```
-
-### 1-3. ALWAYS_STORE 집합 + hasSignificantOutput 함수
-
-```ts
-const ALWAYS_STORE_TOOLS = new Set([
-  'Write', 'Edit', 'MultiEdit', 'Agent', 'Task', 'ExitPlanMode'
-]);
-
-function hasSignificantOutput(
-  toolName: string,
-  output: string,
-  response: PostToolUseInput['tool_response'],
-  minLen: number
-): boolean {
-  if (ALWAYS_STORE_TOOLS.has(toolName)) return true;
-  if (response?.stderr && response.stderr.trim().length > 0) return true;
-  return output.trim().length >= minLen;
-}
-```
-
-### 1-4. main() — step 4.5 위치에 output 필터 삽입
-
-```ts
-// 기존 step 4 (success filter) 다음에 추가
-// 4.5. output-level 필터
-if (!hasSignificantOutput(
-  input.tool_name, toolOutput, input.tool_response,
-  config.minOutputLength ?? 100
-)) {
-  console.log(JSON.stringify({}));
-  return;
-}
-```
-
----
-
-## Step 2. stop.ts — agent_response min-length 필터
-
-### 변경 위치: storeAgentResponse 루프 내
-
-```ts
-const MIN_AGENT_RESPONSE_LEN = parseInt(
-  process.env.CLAUDE_MEMORY_AGENT_RESPONSE_MIN_LEN || '150'
-);
-
-// Store each assistant response
-const lastIdx = assistantMessages.length - 1;
-for (let i = 0; i < assistantMessages.length; i++) {
-  const text = assistantMessages[i];
-  const isLast = i === lastIdx;
-
-  // 마지막 메시지는 최종 답변일 수 있으므로 길이 무관 저장
-  if (!isLast && text.trim().length < MIN_AGENT_RESPONSE_LEN) continue;
-
-  // ... 기존 privacy filter, truncate, store 로직
-}
-```
-
----
-
-## Step 3. session-history-importer.ts — shouldStorePrompt 적용
-
-### 변경 위치: user_prompt 저장 전
-
-```ts
-// shouldStorePrompt와 동일한 로직 인라인 적용
-function isWorthStoringPrompt(content: string): boolean {
-  const trimmed = content.trim();
-  if (trimmed.startsWith('/')) return false;
-  if (trimmed.length < 15) return false;
-  if (!/[a-zA-Z가-힣]{2,}/.test(trimmed)) return false;
-  return true;
-}
-
-// importer 루프 내 user role 메시지 처리 시:
-if (message.role === 'user') {
-  const textContent = extractTextContent(message);
-  if (!isWorthStoringPrompt(textContent)) continue; // 추가
-  await service.storeUserPrompt(sessionId, textContent, ...);
-}
-```
-
-> 참고: `shouldStorePrompt`를 `user-prompt-submit.ts`에서 공유 유틸로 추출하면
-> 중복 없이 재사용 가능. 단, 임포터만 수정하는 경우엔 인라인도 무방.
-
----
-
-## 구현 순서
-
-1. `src/hooks/post-tool-use.ts` 수정 (Step 1)
-2. `src/hooks/stop.ts` 수정 (Step 2)
-3. `src/services/session-history-importer.ts` 수정 (Step 3)
-4. `npm run build`
-5. 검증
-
----
-
-## 리스크 및 대응
-
-| 리스크 | 대응 |
-|--------|------|
-| Read 결과가 필요한 경우 | agent_response에 내용이 반영됨. Read 자체보다 해석이 더 가치 있음 |
-| Grep 결과 패턴 필요 | user_prompt + agent_response에 충분한 맥락 있음 |
-| 짧은 agent_response가 중요한 경우 | 마지막 메시지 예외 처리로 커버 |
-| importer 소급 필터 없음 | 신규 import부터 적용, 기존 데이터 유지 |
-| 환경변수로 비활성화 가능 | `CLAUDE_MEMORY_TOOL_BLOCKLIST=""` 로 전체 허용 가능 |
-
----
-
-## 검증 기준
-
-- `npm run build` 성공
-- Read/Grep/Glob 도구 사용 후 tool_observation 미생성 확인
-- Bash 에러 발생 시 tool_observation 생성 확인
-- Write/Edit 실행 시 tool_observation 생성 확인
-- 짧은 agent_response (< 150자) 저장 안 됨 확인
-- 마지막 agent_response는 길이 무관 저장 확인
-- import 시 '1', 'go', Ctrl+C 저장 안 됨 확인
-- dashboard stats tool_observation 비율 감소 추세 확인