claude-memory-layer 1.0.23 → 1.0.25

package/specs/memory-utilization-improvements/context.md

@@ -0,0 +1,145 @@
+# Context: Memory Utilization Improvements
+
+## 분석 대상
+
+- **프로젝트**: shopping_assistant
+- **프로젝트 키**: f4d5c120
+- **분석 일자**: 2026-03-04
+- **데이터 기간**: 2026-02-25 ~ 2026-03-04
+
+---
+
+## 실제 측정 데이터
+
+### 전체 지표
+
+| 지표 | 값 | 상태 |
+|------|-----|------|
+| 총 이벤트 수 | 1,587 | - |
+| L0 이벤트 | **1,587 (100%)** | 🔴 심각 |
+| L1+ 이벤트 | **0** | 🔴 심각 |
+| 총 세션 수 | 40 (f4d5c120) / 55 (전체) | - |
+| 벡터 수 | 1,586 | - |
+| Retrieval Trace | **1건** | 🔴 심각 |
+| 세션 요약 | **2건** | 🔴 심각 |
+| 검색 후보 선택률 | 100% (5/5) | ⚠️ 경고 |
+
+### 이벤트 유형 분포
+
+```
+Tool Observation:  1,475건  (92.9%)  ← 노이즈 지배적
+User Prompt:          94건   (5.9%)
+Agent Response:       16건   (1.0%)
+Session Summary:       2건   (0.1%)
+```
+
+### 활동 타임라인
+
+- 2026-02-25: 521건 (피크)
+- 2026-02-26: 478건 (피크)
+- 2026-03-04: 40건 (당일)
+- 7일 누적: 1,039건
+
+### 주요 세션 샘플
+
+| 세션 ID | 이벤트 수 | 지속 시간 | 날짜 |
+|---------|---------|---------|------|
+| 5ef326be | 82 | 11분 | 02-25 |
+| 790b37f6 | 53 | 2시간 | 02-25 |
+| 7302c0af | 69 | - | 02-25 |
+| 49653e19 | 31 | 24분 | 03-04 |
+
+---
+
+## 핵심 발견: 실제 증거
+
+### 발견 1: 검색은 실행되나 Trace가 기록되지 않음
+
+User Prompt 이벤트의 metadata를 보면:
+
+```json
+// Turn 1 (첫 번째 턴)
+{ "adherence": true, "reason": "first-turn" }
+
+// Turn 3
+{ "adherence": false, "reason": "skip" }
+
+// Turn 4
+{ "adherence": false, "reason": "skip" }
+
+// Turn 5
+{ "adherence": true, "reason": "interval-based" }
+```
+
+**결론**: `adherence: true`인 경우 검색이 실행됨 → 검색 자체는 작동함.
+그러나 DB에 기록된 retrieval trace는 단 1건.
+**검색 실행 ≠ Trace 기록 성공** → trace INSERT가 실패하거나 비동기 타이밍 문제.
+
+### 발견 2: Embedding 모델 반복 오류
+
+세션 로그에서 확인된 오류들:
+
+```
+"RotaryEmbedding node execution errors"
+"Unknown model class 'eurobert'"
+"8389 tokens exceeding limits"
+"Processing embeddings... ONNX Runtime errors"
+```
+
+전체 이벤트 1,587건 중 벡터 1,586개 생성 → 거의 임베딩은 됨.
+하지만 모델 오류가 지속적으로 발생 중이며 사용자에게 오류가 노출되고 있음.
+
+### 발견 3: Cascade Failure 구조
+
+```
+Trace 기록 실패
+    ↓
+access_count 미증가
+    ↓
+Graduation 미발생 (L0 고착)
+    ↓
+고품질 메모리 없음
+    ↓
+검색 품질 저하
+    ↓
+Helpfulness 측정 불가
+    ↓
+개선 피드백 루프 단절
+```
+
+### 발견 4: Tool Observation 과잉 저장
+
+93%가 tool observation이며 내용은 주로:
+- 일상적인 bash 명령 결과 (ls, grep 출력)
+- 파일 읽기 내용 (반복적)
+- Glob 검색 결과
+
+이 데이터들은 다음 세션에서 재사용 가치가 낮음.
+오히려 FTS5 검색 코퍼스를 비대화시켜 검색 노이즈 증가.
+
+### 발견 5: Stop Hook 미작동
+
+40 세션 중 세션 요약 2건 → 95%의 세션에서 Stop Hook이 발생하지 않음.
+Session-start의 백필 메커니즘도 요약을 생성하지 못하고 있음.
+
+---
+
+## 시스템 환경
+
+- **OS**: Linux 5.15 (Ubuntu)
+- **런타임**: Node.js (TSX)
+- **DB**: SQLite (better-sqlite3)
+- **벡터 DB**: LanceDB
+- **임베딩 모델**: jinaai/jina-embeddings-v5-text-nano-text-matching
+- **대체 모델**: onnx-community/embeddinggemma-300m-ONNX
+- **Heap**: 116MB / 135MB (86% 사용)
+
+---
+
+## 관련 기존 스펙
+
+- `specs/20260207-dashboard-upgrade/` - 대시보드 개선
+- `specs/vector-outbox-v2/` - 벡터 임베딩 파이프라인
+- `specs/endless-mode/` - 세션 연속성
+- `specs/entity-edge-model/` - 엔티티 추적
+- `specs/selective-tool-observation/` - Tool observation 선택적 저장 (부분 설계됨)

package/specs/memory-utilization-improvements/plan.md

@@ -0,0 +1,361 @@
+# Plan: Memory Utilization Improvements
+
+## 전체 목표
+
+f4d5c120 실데이터 분석을 기반으로, 메모리 검색 → Trace 기록 → Graduation → Helpfulness의
+cascade failure를 단계적으로 수정한다.
+
+---
+
+## Phase 1: Critical Fix (1주차)
+
+### Task 1.1 — Retrieval Trace 동기 기록 수정 (IMP-01)
+
+**목표**: 검색 실행 시 trace가 항상 DB에 기록되도록
+
+**작업 단계**:
+
+1. `src/hooks/user-prompt-submit.ts` 읽기
+   - trace 기록 코드 위치 확인
+   - stdout 출력과의 순서 관계 파악
+
+2. `src/core/sqlite-event-store.ts` 읽기
+   - `recordRetrievalTrace()` 구현 확인
+   - async vs sync 여부 확인
+
+3. 수정:
+   ```typescript
+   // Before (추정):
+   const memories = await retrieve(query);
+   process.stdout.write(formatOutput(memories));
+   await store.recordRetrievalTrace({ ... }); // ← hook 종료 후 실행될 수 있음
+
+   // After:
+   const memories = await retrieve(query);
+   store.recordRetrievalTraceSync({ ... }); // ← 동기 실행
+   process.stdout.write(formatOutput(memories));
+   ```
+
+4. 검증:
+   ```bash
+   # 세션 시작 후 user_prompt 입력
+   # 이후 확인:
+   sqlite3 ~/.claude-code/memory/projects/f4d5c120/events.sqlite \
+     "SELECT COUNT(*) FROM retrieval_traces WHERE created_at > datetime('now', '-1 hour');"
+   ```
+
+**완료 조건**: 검색이 실행된 모든 turn에서 trace 레코드 존재
+
+---
+
+### Task 1.2 — Tool Observation 필터링 (IMP-02)
+
+**목표**: 저장 이벤트의 tool observation 비율을 93% → 30% 이하로
+
+**작업 단계**:
+
+1. `src/hooks/post-tool-use.ts` 읽기
+   - 현재 저장 조건 파악
+   - 기존 제외 목록 확인 (TodoRead, TodoWrite)
+
+2. `src/core/metadata-extractor.ts` 읽기
+   - 중요도 판별 로직 존재 여부 확인
+
+3. 필터 로직 추가:
+   ```typescript
+   function shouldStoreToolObservation(toolName: string, input: unknown, output: string): boolean {
+     // 항상 저장
+     if (['Write', 'Edit', 'MultiEdit'].includes(toolName)) return true;
+
+     // 항상 제외
+     if (['Read', 'Glob', 'TodoRead', 'TodoWrite'].includes(toolName)) return false;
+
+     // Bash: 오류 또는 중요 키워드
+     if (toolName === 'Bash') {
+       const exitCode = extractExitCode(output);
+       if (exitCode !== 0) return true;
+       return IMPORTANT_KEYWORDS.some(kw => output.toLowerCase().includes(kw));
+     }
+
+     // Grep: 결과 10줄 초과 시
+     if (toolName === 'Grep') {
+       return output.split('\n').length > 10;
+     }
+
+     return false;
+   }
+   ```
+
+4. 기존 L0 데이터는 변경하지 않음 (append-only 원칙 유지)
+
+**완료 조건**: 새 세션의 tool observation 비율 < 40%
+
+---
+
+## Phase 2: Quality (2주차)
+
+### Task 2.1 — 세션 요약 신뢰성 (IMP-03)
+
+**목표**: 세션 요약 생성률 5% → 80% 이상
+
+**작업 단계**:
+
+1. `src/hooks/session-start.ts` 읽기
+   - 백필 로직 (`backfillPreviousSession`) 확인
+   - 현재 요약 생성 여부 파악
+
+2. `src/hooks/stop.ts` 읽기
+   - 요약 생성 로직 위치
+   - 실패 시 에러 처리 방식
+
+3. session-start에 규칙 기반 요약 생성 추가:
+   ```typescript
+   async function generateRuleBasedSummary(sessionId: string): Promise<string> {
+     const events = await store.getSessionEvents(sessionId);
+     const prompts = events.filter(e => e.eventType === 'user_prompt');
+     const tools = [...new Set(events.filter(e => e.eventType === 'tool_observation')
+       .map(e => e.metadata?.toolName))];
+     const errors = events.filter(e =>
+       e.eventType === 'tool_observation' && e.metadata?.exitCode !== 0
+     );
+
+     return [
+       `[${formatDate(events[0].timestamp)}] ${prompts.length}턴 세션.`,
+       prompts.length > 0 ? `주요 작업: ${prompts[0].content.slice(0, 100)}` : '',
+       tools.length > 0 ? `사용 툴: ${tools.join(', ')}` : '',
+       errors.length > 0 ? `오류 발생: ${errors.length}건` : '',
+     ].filter(Boolean).join(' ');
+   }
+   ```
+
+4. session-start 백필 시 호출:
+   ```typescript
+   if (events.length >= 3 && !existingSummary) {
+     const summary = await generateRuleBasedSummary(prevSessionId);
+     await store.storeEvent({ eventType: 'session_summary', content: summary, ... });
+   }
+   ```
+
+**완료 조건**: 백필 실행 후 기존 세션 중 80% 이상에 요약 생성
+
+---
+
+### Task 2.2 — Graduation Repair CLI (IMP-04)
+
+**목표**: 기존 L0 이벤트 중 자격 있는 것들을 L1으로 승격
+
+**작업 단계**:
+
+1. `src/core/graduation.ts` 읽기
+   - 현재 L0→L1 승격 기준 파악
+   - `recordAccess()` 호출 위치
+
+2. 시간 기반 승격 규칙 추가:
+   ```typescript
+   // 7일 이상 된 user_prompt 이벤트 중 내용이 충분한 것
+   const GRADUATION_RULES_L1 = {
+     minAge: 7 * 24 * 60 * 60 * 1000,  // 7일
+     minContentLength: 100,
+     eventTypes: ['user_prompt', 'session_summary'],
+   };
+   ```
+
+3. CLI 커맨드 추가:
+   ```
+   claude-memory graduation --repair [--project <hash>] [--dry-run]
+   ```
+   출력 예시:
+   ```
+   Analyzing 1587 events...
+   Eligible for L1: 43 events (user_prompt: 38, session_summary: 5)
+   Eligible for L2: 0 events
+   [--dry-run: no changes made]
+   Run without --dry-run to apply.
+   ```
+
+**완료 조건**: `--dry-run` 후 승격 후보 확인, 실제 실행 후 L1 이벤트 발생
+
+---
+
+### Task 2.3 — Embedding 모델 모니터링 (IMP-05)
+
+**목표**: 모델 오류 시 자동 폴백 + 대시보드에 상태 표시
+
+**작업 단계**:
+
+1. `src/hooks/semantic-daemon.ts` 읽기
+   - 현재 모델 로딩/폴백 로직
+   - 오류 핸들링 방식
+
+2. 헬스체크 강화:
+   ```typescript
+   class SemanticDaemon {
+     private modelHealth: 'primary' | 'fallback' | 'keyword-only' = 'primary';
+
+     async embed(text: string): Promise<number[]> {
+       try {
+         return await this.primaryModel.embed(text);
+       } catch (e) {
+         if (this.modelHealth === 'primary') {
+           this.modelHealth = 'fallback';
+           logger.warn('[embedding] switched to fallback model');
+         }
+         try {
+           return await this.fallbackModel.embed(text);
+         } catch (e2) {
+           this.modelHealth = 'keyword-only';
+           return []; // 키워드 전용 모드
+         }
+       }
+     }
+   }
+   ```
+
+3. `/api/stats` 응답에 모델 상태 추가:
+   ```json
+   {
+     "embeddingModel": {
+       "current": "fallback",
+       "primaryErrors": 12,
+       "fallbackErrors": 0,
+       "successRate": 0.99
+     }
+   }
+   ```
+
+**완료 조건**: 모델 오류 시 자동 폴백 + 대시보드에 상태 표시
+
+---
+
+## Phase 3: Feedback Loop (3주차)
+
+### Task 3.1 — Helpfulness 자동 평가 (IMP-06)
+
+**목표**: sessions_helpfulness 테이블에 실제 데이터 축적 시작
+
+**작업 단계**:
+
+1. `src/hooks/stop.ts` 읽기
+   - 세션 종료 시 처리 로직
+   - agent_response 이벤트 저장 방식
+
+2. 휴리스틱 평가 로직:
+   ```typescript
+   async function evaluateHelpfulness(sessionId: string) {
+     const traces = await store.getSessionRetrievalTraces(sessionId);
+     const responses = await store.getSessionEvents(sessionId, 'agent_response');
+     const responseText = responses.map(r => r.content).join(' ');
+
+     for (const trace of traces) {
+       for (const eventId of trace.selectedEventIds) {
+         const event = await store.getEvent(eventId);
+         // canonicalKey나 내용의 핵심 명사가 응답에 포함되는지 확인
+         const mentioned = responseText.includes(event.canonicalKey?.split('/').pop() ?? '');
+         const score = mentioned ? 0.8 : 0.3;
+
+         await store.recordHelpfulness({
+           sessionId,
+           eventId,
+           helpfulness: score,
+           evaluatedAt: new Date(),
+         });
+       }
+     }
+   }
+   ```
+
+3. `matcher.ts`에 helpfulness 가중치 추가:
+   ```typescript
+   const helpfulnessScore = await store.getAvgHelpfulness(eventId) ?? 0.5;
+   finalScore = baseScore * 0.9 + helpfulnessScore * 0.1;
+   ```
+
+**완료 조건**: 각 세션 종료 후 sessions_helpfulness에 레코드 생성
+
+---
+
+### Task 3.2 — 컨텍스트 포맷 개선 (IMP-07)
+
+**목표**: Claude가 메모리를 명확하게 인식하고 활용할 수 있는 포맷
+
+**작업 단계**:
+
+1. `src/hooks/user-prompt-submit.ts`의 stdout 출력 포맷 확인
+
+2. 새 포맷으로 변경:
+   ```
+   <memory_context>
+   [2026-02-25 | 신뢰도: 높음]
+   주제: LLM function call generalization
+   내용: generalize_with_llm() 함수를 사용해 상품 추천 로직 개선. 응답 속도 40% 향상.
+   ---
+   [2026-02-26 | 신뢰도: 중간]
+   주제: ONNX embedding 오류 처리
+   내용: RotaryEmbedding 노드 오류 시 fallback 모델로 자동 전환 구현.
+   </memory_context>
+   ```
+
+3. `suggested` confidence 이벤트는 별도 섹션으로 분리:
+   ```
+   <memory_hints optional="true">
+   (참고) 이전에 유사한 작업을 한 적 있음: ...
+   </memory_hints>
+   ```
+
+**완료 조건**: 메모리 포함 시 Claude 응답에서 메모리 내용 참조 증가 확인
+
+---
+
+## 검증 계획
+
+각 Phase 완료 후 f4d5c120 프로젝트로 아래 지표 확인:
+
+```bash
+# Phase 1 완료 후
+sqlite3 ~/.claude-code/memory/projects/f4d5c120/events.sqlite << 'EOF'
+SELECT
+  'retrieval_traces' as metric,
+  COUNT(*) as value
+FROM retrieval_traces
+UNION ALL
+SELECT
+  'tool_obs_ratio',
+  ROUND(100.0 * SUM(CASE WHEN event_type='tool_observation' THEN 1 END) / COUNT(*), 1)
+FROM events
+WHERE created_at > datetime('now', '-3 days');
+EOF
+
+# Phase 2 완료 후
+SELECT
+  'l0_count', COUNT(*) FROM events WHERE level = 0
+UNION ALL
+SELECT
+  'l1_plus_count', COUNT(*) FROM events WHERE level >= 1
+UNION ALL
+SELECT
+  'session_summary_count', COUNT(*) FROM events WHERE event_type = 'session_summary';
+
+# Phase 3 완료 후
+SELECT
+  'helpfulness_records', COUNT(*) FROM sessions_helpfulness
+UNION ALL
+SELECT
+  'avg_helpfulness', ROUND(AVG(helpfulness), 2) FROM sessions_helpfulness;
+```
+
+---
+
+## 담당 파일 목록
+
+| 파일 | 변경 이유 | Phase |
+|------|---------|-------|
+| `src/hooks/user-prompt-submit.ts` | Trace 동기 기록, 컨텍스트 포맷 | 1, 3 |
+| `src/hooks/post-tool-use.ts` | Tool observation 필터링 | 1 |
+| `src/core/sqlite-event-store.ts` | recordRetrievalTraceSync 추가 | 1 |
+| `src/hooks/session-start.ts` | 세션 요약 백필 | 2 |
+| `src/hooks/stop.ts` | Helpfulness 평가 추가 | 2, 3 |
+| `src/core/graduation.ts` | 시간 기반 승격 규칙 | 2 |
+| `src/core/matcher.ts` | Helpfulness 가중치 | 3 |
+| `src/hooks/semantic-daemon.ts` | 모델 헬스체크 강화 | 2 |
+| `src/server/api/stats.ts` | 모델 상태 지표 추가 | 2 |
+| `src/cli/index.ts` | graduation --repair 커맨드 | 2 |