claude-memory-layer 1.0.24 → 1.0.25

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (40) hide show
  1. package/.claude/settings.local.json +15 -1
  2. package/dist/cli/index.js +152 -969
  3. package/dist/cli/index.js.map +4 -4
  4. package/dist/core/index.js +31 -66
  5. package/dist/core/index.js.map +3 -3
  6. package/dist/hooks/post-tool-use.js +181 -967
  7. package/dist/hooks/post-tool-use.js.map +4 -4
  8. package/dist/hooks/semantic-daemon.js +148 -965
  9. package/dist/hooks/semantic-daemon.js.map +4 -4
  10. package/dist/hooks/session-end.js +148 -965
  11. package/dist/hooks/session-end.js.map +4 -4
  12. package/dist/hooks/session-start.js +150 -965
  13. package/dist/hooks/session-start.js.map +4 -4
  14. package/dist/hooks/stop.js +156 -965
  15. package/dist/hooks/stop.js.map +4 -4
  16. package/dist/hooks/user-prompt-submit.js +150 -967
  17. package/dist/hooks/user-prompt-submit.js.map +4 -4
  18. package/dist/server/api/index.js +148 -965
  19. package/dist/server/api/index.js.map +4 -4
  20. package/dist/server/index.js +148 -965
  21. package/dist/server/index.js.map +4 -4
  22. package/dist/services/memory-service.js +148 -965
  23. package/dist/services/memory-service.js.map +4 -4
  24. package/memory/agent_response/uncategorized/2026-03-04.md +217 -1
  25. package/memory/session_summary/uncategorized/2026-03-04.md +20 -1
  26. package/memory/tool_observation/uncategorized/2026-03-04.md +237 -1
  27. package/memory/user_prompt/uncategorized/2026-03-04.md +185 -1
  28. package/package.json +1 -2
  29. package/specs/memory-utilization-improvements/context.md +145 -0
  30. package/specs/memory-utilization-improvements/plan.md +361 -0
  31. package/specs/memory-utilization-improvements/spec.md +308 -0
  32. package/specs/optional-duckdb/context.md +77 -0
  33. package/specs/optional-duckdb/plan.md +142 -0
  34. package/specs/optional-duckdb/spec.md +35 -0
  35. package/src/core/db-wrapper.ts +18 -73
  36. package/src/core/sqlite-event-store.ts +24 -0
  37. package/src/hooks/post-tool-use.ts +25 -0
  38. package/src/hooks/session-start.ts +4 -0
  39. package/src/hooks/stop.ts +14 -0
  40. package/src/services/memory-service.ts +62 -58
@@ -0,0 +1,361 @@
1
+ # Plan: Memory Utilization Improvements
2
+
3
+ ## 전체 목표
4
+
5
+ f4d5c120 실데이터 분석을 기반으로, 메모리 검색 → Trace 기록 → Graduation → Helpfulness의
6
+ cascade failure를 단계적으로 수정한다.
7
+
8
+ ---
9
+
10
+ ## Phase 1: Critical Fix (1주차)
11
+
12
+ ### Task 1.1 — Retrieval Trace 동기 기록 수정 (IMP-01)
13
+
14
+ **목표**: 검색 실행 시 trace가 항상 DB에 기록되도록
15
+
16
+ **작업 단계**:
17
+
18
+ 1. `src/hooks/user-prompt-submit.ts` 읽기
19
+ - trace 기록 코드 위치 확인
20
+ - stdout 출력과의 순서 관계 파악
21
+
22
+ 2. `src/core/sqlite-event-store.ts` 읽기
23
+ - `recordRetrievalTrace()` 구현 확인
24
+ - async vs sync 여부 확인
25
+
26
+ 3. 수정:
27
+ ```typescript
28
+ // Before (추정):
29
+ const memories = await retrieve(query);
30
+ process.stdout.write(formatOutput(memories));
31
+ await store.recordRetrievalTrace({ ... }); // ← hook 종료 후 실행될 수 있음
32
+
33
+ // After:
34
+ const memories = await retrieve(query);
35
+ store.recordRetrievalTraceSync({ ... }); // ← 동기 실행
36
+ process.stdout.write(formatOutput(memories));
37
+ ```
38
+
39
+ 4. 검증:
40
+ ```bash
41
+ # 세션 시작 후 user_prompt 입력
42
+ # 이후 확인:
43
+ sqlite3 ~/.claude-code/memory/projects/f4d5c120/events.sqlite \
44
+ "SELECT COUNT(*) FROM retrieval_traces WHERE created_at > datetime('now', '-1 hour');"
45
+ ```
46
+
47
+ **완료 조건**: 검색이 실행된 모든 turn에서 trace 레코드 존재
48
+
49
+ ---
50
+
51
+ ### Task 1.2 — Tool Observation 필터링 (IMP-02)
52
+
53
+ **목표**: 저장 이벤트의 tool observation 비율을 93% → 30% 이하로
54
+
55
+ **작업 단계**:
56
+
57
+ 1. `src/hooks/post-tool-use.ts` 읽기
58
+ - 현재 저장 조건 파악
59
+ - 기존 제외 목록 확인 (TodoRead, TodoWrite)
60
+
61
+ 2. `src/core/metadata-extractor.ts` 읽기
62
+ - 중요도 판별 로직 존재 여부 확인
63
+
64
+ 3. 필터 로직 추가:
65
+ ```typescript
66
+ function shouldStoreToolObservation(toolName: string, input: unknown, output: string): boolean {
67
+ // 항상 저장
68
+ if (['Write', 'Edit', 'MultiEdit'].includes(toolName)) return true;
69
+
70
+ // 항상 제외
71
+ if (['Read', 'Glob', 'TodoRead', 'TodoWrite'].includes(toolName)) return false;
72
+
73
+ // Bash: 오류 또는 중요 키워드
74
+ if (toolName === 'Bash') {
75
+ const exitCode = extractExitCode(output);
76
+ if (exitCode !== 0) return true;
77
+ return IMPORTANT_KEYWORDS.some(kw => output.toLowerCase().includes(kw));
78
+ }
79
+
80
+ // Grep: 결과 10줄 초과 시
81
+ if (toolName === 'Grep') {
82
+ return output.split('\n').length > 10;
83
+ }
84
+
85
+ return false;
86
+ }
87
+ ```
88
+
89
+ 4. 기존 L0 데이터는 변경하지 않음 (append-only 원칙 유지)
90
+
91
+ **완료 조건**: 새 세션의 tool observation 비율 < 40%
92
+
93
+ ---
94
+
95
+ ## Phase 2: Quality (2주차)
96
+
97
+ ### Task 2.1 — 세션 요약 신뢰성 (IMP-03)
98
+
99
+ **목표**: 세션 요약 생성률 5% → 80% 이상
100
+
101
+ **작업 단계**:
102
+
103
+ 1. `src/hooks/session-start.ts` 읽기
104
+ - 백필 로직 (`backfillPreviousSession`) 확인
105
+ - 현재 요약 생성 여부 파악
106
+
107
+ 2. `src/hooks/stop.ts` 읽기
108
+ - 요약 생성 로직 위치
109
+ - 실패 시 에러 처리 방식
110
+
111
+ 3. session-start에 규칙 기반 요약 생성 추가:
112
+ ```typescript
113
+ async function generateRuleBasedSummary(sessionId: string): Promise<string> {
114
+ const events = await store.getSessionEvents(sessionId);
115
+ const prompts = events.filter(e => e.eventType === 'user_prompt');
116
+ const tools = [...new Set(events.filter(e => e.eventType === 'tool_observation')
117
+ .map(e => e.metadata?.toolName))];
118
+ const errors = events.filter(e =>
119
+ e.eventType === 'tool_observation' && e.metadata?.exitCode !== 0
120
+ );
121
+
122
+ return [
123
+ `[${formatDate(events[0].timestamp)}] ${prompts.length}턴 세션.`,
124
+ prompts.length > 0 ? `주요 작업: ${prompts[0].content.slice(0, 100)}` : '',
125
+ tools.length > 0 ? `사용 툴: ${tools.join(', ')}` : '',
126
+ errors.length > 0 ? `오류 발생: ${errors.length}건` : '',
127
+ ].filter(Boolean).join(' ');
128
+ }
129
+ ```
130
+
131
+ 4. session-start 백필 시 호출:
132
+ ```typescript
133
+ if (events.length >= 3 && !existingSummary) {
134
+ const summary = await generateRuleBasedSummary(prevSessionId);
135
+ await store.storeEvent({ eventType: 'session_summary', content: summary, ... });
136
+ }
137
+ ```
138
+
139
+ **완료 조건**: 백필 실행 후 기존 세션 중 80% 이상에 요약 생성
140
+
141
+ ---
142
+
143
+ ### Task 2.2 — Graduation Repair CLI (IMP-04)
144
+
145
+ **목표**: 기존 L0 이벤트 중 자격 있는 것들을 L1으로 승격
146
+
147
+ **작업 단계**:
148
+
149
+ 1. `src/core/graduation.ts` 읽기
150
+ - 현재 L0→L1 승격 기준 파악
151
+ - `recordAccess()` 호출 위치
152
+
153
+ 2. 시간 기반 승격 규칙 추가:
154
+ ```typescript
155
+ // 7일 이상 된 user_prompt 이벤트 중 내용이 충분한 것
156
+ const GRADUATION_RULES_L1 = {
157
+ minAge: 7 * 24 * 60 * 60 * 1000, // 7일
158
+ minContentLength: 100,
159
+ eventTypes: ['user_prompt', 'session_summary'],
160
+ };
161
+ ```
162
+
163
+ 3. CLI 커맨드 추가:
164
+ ```
165
+ claude-memory graduation --repair [--project <hash>] [--dry-run]
166
+ ```
167
+ 출력 예시:
168
+ ```
169
+ Analyzing 1587 events...
170
+ Eligible for L1: 43 events (user_prompt: 38, session_summary: 5)
171
+ Eligible for L2: 0 events
172
+ [--dry-run: no changes made]
173
+ Run without --dry-run to apply.
174
+ ```
175
+
176
+ **완료 조건**: `--dry-run` 후 승격 후보 확인, 실제 실행 후 L1 이벤트 발생
177
+
178
+ ---
179
+
180
+ ### Task 2.3 — Embedding 모델 모니터링 (IMP-05)
181
+
182
+ **목표**: 모델 오류 시 자동 폴백 + 대시보드에 상태 표시
183
+
184
+ **작업 단계**:
185
+
186
+ 1. `src/hooks/semantic-daemon.ts` 읽기
187
+ - 현재 모델 로딩/폴백 로직
188
+ - 오류 핸들링 방식
189
+
190
+ 2. 헬스체크 강화:
191
+ ```typescript
192
+ class SemanticDaemon {
193
+ private modelHealth: 'primary' | 'fallback' | 'keyword-only' = 'primary';
194
+
195
+ async embed(text: string): Promise<number[]> {
196
+ try {
197
+ return await this.primaryModel.embed(text);
198
+ } catch (e) {
199
+ if (this.modelHealth === 'primary') {
200
+ this.modelHealth = 'fallback';
201
+ logger.warn('[embedding] switched to fallback model');
202
+ }
203
+ try {
204
+ return await this.fallbackModel.embed(text);
205
+ } catch (e2) {
206
+ this.modelHealth = 'keyword-only';
207
+ return []; // 키워드 전용 모드
208
+ }
209
+ }
210
+ }
211
+ }
212
+ ```
213
+
214
+ 3. `/api/stats` 응답에 모델 상태 추가:
215
+ ```json
216
+ {
217
+ "embeddingModel": {
218
+ "current": "fallback",
219
+ "primaryErrors": 12,
220
+ "fallbackErrors": 0,
221
+ "successRate": 0.99
222
+ }
223
+ }
224
+ ```
225
+
226
+ **완료 조건**: 모델 오류 시 자동 폴백 + 대시보드에 상태 표시
227
+
228
+ ---
229
+
230
+ ## Phase 3: Feedback Loop (3주차)
231
+
232
+ ### Task 3.1 — Helpfulness 자동 평가 (IMP-06)
233
+
234
+ **목표**: sessions_helpfulness 테이블에 실제 데이터 축적 시작
235
+
236
+ **작업 단계**:
237
+
238
+ 1. `src/hooks/stop.ts` 읽기
239
+ - 세션 종료 시 처리 로직
240
+ - agent_response 이벤트 저장 방식
241
+
242
+ 2. 휴리스틱 평가 로직:
243
+ ```typescript
244
+ async function evaluateHelpfulness(sessionId: string) {
245
+ const traces = await store.getSessionRetrievalTraces(sessionId);
246
+ const responses = await store.getSessionEvents(sessionId, 'agent_response');
247
+ const responseText = responses.map(r => r.content).join(' ');
248
+
249
+ for (const trace of traces) {
250
+ for (const eventId of trace.selectedEventIds) {
251
+ const event = await store.getEvent(eventId);
252
+ // canonicalKey나 내용의 핵심 명사가 응답에 포함되는지 확인
253
+ const mentioned = responseText.includes(event.canonicalKey?.split('/').pop() ?? '');
254
+ const score = mentioned ? 0.8 : 0.3;
255
+
256
+ await store.recordHelpfulness({
257
+ sessionId,
258
+ eventId,
259
+ helpfulness: score,
260
+ evaluatedAt: new Date(),
261
+ });
262
+ }
263
+ }
264
+ }
265
+ ```
266
+
267
+ 3. `matcher.ts`에 helpfulness 가중치 추가:
268
+ ```typescript
269
+ const helpfulnessScore = await store.getAvgHelpfulness(eventId) ?? 0.5;
270
+ finalScore = baseScore * 0.9 + helpfulnessScore * 0.1;
271
+ ```
272
+
273
+ **완료 조건**: 각 세션 종료 후 sessions_helpfulness에 레코드 생성
274
+
275
+ ---
276
+
277
+ ### Task 3.2 — 컨텍스트 포맷 개선 (IMP-07)
278
+
279
+ **목표**: Claude가 메모리를 명확하게 인식하고 활용할 수 있는 포맷
280
+
281
+ **작업 단계**:
282
+
283
+ 1. `src/hooks/user-prompt-submit.ts`의 stdout 출력 포맷 확인
284
+
285
+ 2. 새 포맷으로 변경:
286
+ ```
287
+ <memory_context>
288
+ [2026-02-25 | 신뢰도: 높음]
289
+ 주제: LLM function call generalization
290
+ 내용: generalize_with_llm() 함수를 사용해 상품 추천 로직 개선. 응답 속도 40% 향상.
291
+ ---
292
+ [2026-02-26 | 신뢰도: 중간]
293
+ 주제: ONNX embedding 오류 처리
294
+ 내용: RotaryEmbedding 노드 오류 시 fallback 모델로 자동 전환 구현.
295
+ </memory_context>
296
+ ```
297
+
298
+ 3. `suggested` confidence 이벤트는 별도 섹션으로 분리:
299
+ ```
300
+ <memory_hints optional="true">
301
+ (참고) 이전에 유사한 작업을 한 적 있음: ...
302
+ </memory_hints>
303
+ ```
304
+
305
+ **완료 조건**: 메모리 포함 시 Claude 응답에서 메모리 내용 참조 증가 확인
306
+
307
+ ---
308
+
309
+ ## 검증 계획
310
+
311
+ 각 Phase 완료 후 f4d5c120 프로젝트로 아래 지표 확인:
312
+
313
+ ```bash
314
+ # Phase 1 완료 후
315
+ sqlite3 ~/.claude-code/memory/projects/f4d5c120/events.sqlite << 'EOF'
316
+ SELECT
317
+ 'retrieval_traces' as metric,
318
+ COUNT(*) as value
319
+ FROM retrieval_traces
320
+ UNION ALL
321
+ SELECT
322
+ 'tool_obs_ratio',
323
+ ROUND(100.0 * SUM(CASE WHEN event_type='tool_observation' THEN 1 END) / COUNT(*), 1)
324
+ FROM events
325
+ WHERE created_at > datetime('now', '-3 days');
326
+ EOF
327
+
328
+ # Phase 2 완료 후
329
+ SELECT
330
+ 'l0_count', COUNT(*) FROM events WHERE level = 0
331
+ UNION ALL
332
+ SELECT
333
+ 'l1_plus_count', COUNT(*) FROM events WHERE level >= 1
334
+ UNION ALL
335
+ SELECT
336
+ 'session_summary_count', COUNT(*) FROM events WHERE event_type = 'session_summary';
337
+
338
+ # Phase 3 완료 후
339
+ SELECT
340
+ 'helpfulness_records', COUNT(*) FROM sessions_helpfulness
341
+ UNION ALL
342
+ SELECT
343
+ 'avg_helpfulness', ROUND(AVG(helpfulness), 2) FROM sessions_helpfulness;
344
+ ```
345
+
346
+ ---
347
+
348
+ ## 담당 파일 목록
349
+
350
+ | 파일 | 변경 이유 | Phase |
351
+ |------|---------|-------|
352
+ | `src/hooks/user-prompt-submit.ts` | Trace 동기 기록, 컨텍스트 포맷 | 1, 3 |
353
+ | `src/hooks/post-tool-use.ts` | Tool observation 필터링 | 1 |
354
+ | `src/core/sqlite-event-store.ts` | recordRetrievalTraceSync 추가 | 1 |
355
+ | `src/hooks/session-start.ts` | 세션 요약 백필 | 2 |
356
+ | `src/hooks/stop.ts` | Helpfulness 평가 추가 | 2, 3 |
357
+ | `src/core/graduation.ts` | 시간 기반 승격 규칙 | 2 |
358
+ | `src/core/matcher.ts` | Helpfulness 가중치 | 3 |
359
+ | `src/hooks/semantic-daemon.ts` | 모델 헬스체크 강화 | 2 |
360
+ | `src/server/api/stats.ts` | 모델 상태 지표 추가 | 2 |
361
+ | `src/cli/index.ts` | graduation --repair 커맨드 | 2 |
@@ -0,0 +1,308 @@
1
+ # Spec: Memory Utilization Improvements
2
+
3
+ ## 목표
4
+
5
+ f4d5c120 프로젝트 분석을 통해 확인된 메모리 시스템의 cascade failure를 해소하고,
6
+ 저장된 메모리가 실제로 Claude 응답에 기여하는 비율을 높인다.
7
+
8
+ **성공 기준**:
9
+ - Retrieval trace 기록률 > 95% (현재 ~0%)
10
+ - 메모리 Graduation L1+ 비율 > 10% (현재 0%)
11
+ - Tool Observation 중 저장 비율 < 30% (현재 100%)
12
+ - 세션 요약 생성률 > 80% (현재 5%)
13
+
14
+ ---
15
+
16
+ ## 개선 항목 (우선순위 순)
17
+
18
+ ---
19
+
20
+ ### IMP-01: Retrieval Trace 동기 기록
21
+
22
+ **우선순위**: P0 (Blocker)
23
+
24
+ **문제**:
25
+ - `adherence: true` 이벤트가 존재 → 검색은 실행됨
26
+ - 하지만 retrieval_traces 테이블에 단 1건만 기록
27
+ - 비동기 trace INSERT가 hook 프로세스 종료 전에 완료되지 않는 것으로 추정
28
+
29
+ **원인 분석**:
30
+ ```typescript
31
+ // user-prompt-submit.ts 추정 흐름
32
+ async function hook() {
33
+ const memories = await retrieveMemories(query); // 검색 실행
34
+ await writeToStdout(memories); // 결과 출력 (hook 종료)
35
+ await recordTrace(memories); // ← 여기서 프로세스가 이미 종료됨
36
+ }
37
+ ```
38
+
39
+ **해결 방안**:
40
+ 1. `recordTrace()`를 `retrieveMemories()` 직후, stdout 출력 전에 동기적으로 실행
41
+ 2. better-sqlite3의 동기 API 사용 (이미 사용 중) → trace INSERT를 sync로 변경
42
+ 3. trace 기록 실패 시 stderr에 경고 출력
43
+
44
+ **변경 파일**:
45
+ - `src/hooks/user-prompt-submit.ts` — trace 기록 위치를 stdout 출력 전으로 이동
46
+ - `src/core/sqlite-event-store.ts` — `recordRetrievalTrace()`를 동기 메서드로 변경
47
+
48
+ **검증**:
49
+ ```sql
50
+ -- 개선 후: 세션당 retrieval_traces 수 확인
51
+ SELECT session_id, COUNT(*) as trace_count
52
+ FROM retrieval_traces
53
+ GROUP BY session_id
54
+ ORDER BY trace_count DESC;
55
+ ```
56
+
57
+ ---
58
+
59
+ ### IMP-02: Tool Observation 선택적 저장
60
+
61
+ **우선순위**: P0
62
+
63
+ **문제**:
64
+ - 저장 이벤트의 93%가 tool observation
65
+ - 대부분 다음 세션에서 재사용 가치가 없는 ephemeral 데이터
66
+ - FTS5 검색 코퍼스 비대화 → 검색 노이즈 증가
67
+
68
+ **저장 가치 기준**:
69
+
70
+ | Tool | 저장 조건 | 이유 |
71
+ |------|---------|------|
72
+ | Bash | 오류(exit_code≠0), 또는 중요 출력 키워드 포함 | 성공적인 단순 명령은 가치 낮음 |
73
+ | Write | 항상 저장 | 파일 생성/수정은 중요 컨텍스트 |
74
+ | Edit | 항상 저장 | 코드 변경은 추적 필요 |
75
+ | Read | 저장 안 함 (기본값) | 파일 내용은 재현 가능 |
76
+ | Glob | 저장 안 함 | 디렉토리 구조는 변하지 않음 |
77
+ | Grep | 결과 10줄 초과 시만 저장 | 대용량 검색 결과만 의미있음 |
78
+ | TodoRead/Write | 저장 안 함 | 이미 제외됨 |
79
+
80
+ **중요 출력 키워드** (Bash 저장 트리거):
81
+ ```
82
+ error, Error, ERROR, failed, Failed, FAILED,
83
+ warning, Warning, exception, Exception,
84
+ test passed, test failed, coverage,
85
+ successfully deployed, build complete
86
+ ```
87
+
88
+ **변경 파일**:
89
+ - `src/hooks/post-tool-use.ts` — 툴별 저장 조건 필터링 로직 추가
90
+ - `src/core/metadata-extractor.ts` — 중요도 점수 계산 함수 추가
91
+
92
+ **예상 효과**:
93
+ - 저장 이벤트 수 60~70% 감소
94
+ - 검색 정밀도 향상
95
+ - DB/벡터 스토어 용량 절감
96
+
97
+ ---
98
+
99
+ ### IMP-03: 세션 요약 신뢰성 개선
100
+
101
+ **우선순위**: P1
102
+
103
+ **문제**:
104
+ - 40 세션 중 2건만 요약 (5%)
105
+ - Stop hook은 프로세스 강제 종료 시 실행되지 않음
106
+ - Session-start의 백필 로직이 요약을 생성하지 않고 있음
107
+
108
+ **해결 방안**:
109
+
110
+ **A. Session-start 백필에서 요약 생성 추가**:
111
+ ```typescript
112
+ // session-start.ts
113
+ async function backfillPreviousSession(prevSessionId: string) {
114
+ const events = await getSessionEvents(prevSessionId);
115
+ if (events.length > 3 && !hasSummary(prevSessionId)) {
116
+ const summary = await generateSummary(events);
117
+ await storeSummaryEvent(prevSessionId, summary);
118
+ }
119
+ }
120
+ ```
121
+
122
+ **B. LLM 없이 규칙 기반 요약 생성** (빠른 실행):
123
+ ```
124
+ 요약 템플릿:
125
+ "[날짜] [N]턴 세션. 주요 작업: [user_prompt 첫 문장들].
126
+ 사용 툴: [tool 목록]. [오류 있으면: 발생한 오류: ...]"
127
+ ```
128
+
129
+ **C. 주기적 요약 트리거** (선택적):
130
+ - 세션 시작 시 이전 7일간 미요약 세션 최대 3개 백필
131
+
132
+ **변경 파일**:
133
+ - `src/hooks/session-start.ts` — 백필 시 요약 생성 호출 추가
134
+ - `src/core/event-store.ts` — `generateRuleBasedSummary()` 함수 추가
135
+
136
+ ---
137
+
138
+ ### IMP-04: Graduation 수동 트리거 커맨드
139
+
140
+ **우선순위**: P1
141
+
142
+ **문제**:
143
+ - 1,587건 전부 L0에 고착
144
+ - IMP-01로 trace 기록이 정상화되어도 과거 데이터는 L0 유지
145
+ - access_count가 0이면 L1 승격 불가
146
+
147
+ **해결 방안**:
148
+
149
+ **A. 히스토리 기반 access_count 역산**:
150
+ ```sql
151
+ -- 동일 session의 이벤트가 이후 세션에서 재등장한 경우 access로 카운트
152
+ -- user_prompt 이벤트 중 내용이 유사한 것들을 같은 토픽으로 그룹화
153
+ ```
154
+
155
+ **B. CLI 커맨드 추가**:
156
+ ```bash
157
+ claude-memory graduation --repair --project f4d5c120
158
+ # 출력: Analyzed 1587 events, promoted 42 to L1, 8 to L2
159
+ ```
160
+
161
+ **C. 시간 기반 자동 L1 승격** (규칙):
162
+ - 생성 후 7일 이상 지난 user_prompt 이벤트
163
+ - content 길이 > 100자
164
+ - 동일 세션에서 3번 이상 유사 쿼리 존재
165
+
166
+ **변경 파일**:
167
+ - `src/core/graduation.ts` — 시간 기반 승격 규칙 추가
168
+ - `src/cli/index.ts` — `graduation --repair` 서브커맨드 추가
169
+
170
+ ---
171
+
172
+ ### IMP-05: Embedding 모델 상태 모니터링
173
+
174
+ **우선순위**: P1
175
+
176
+ **문제**:
177
+ - "Unknown model class 'eurobert'" 오류 반복
178
+ - "RotaryEmbedding node execution errors" 반복
179
+ - 사용자에게 오류가 노출되지만 자동 대처 없음
180
+
181
+ **해결 방안**:
182
+
183
+ **A. 모델 헬스체크 강화**:
184
+ ```typescript
185
+ // semantic-daemon.ts
186
+ async function checkModelHealth(): Promise<boolean> {
187
+ try {
188
+ await embed("test query");
189
+ return true;
190
+ } catch (e) {
191
+ logger.warn('Primary model failed, switching to fallback');
192
+ await switchToFallbackModel();
193
+ return false;
194
+ }
195
+ }
196
+ ```
197
+
198
+ **B. 대시보드에 모델 상태 표시**:
199
+ - 현재 사용 중인 모델명
200
+ - 최근 임베딩 성공률
201
+ - 오류 로그 최근 5건
202
+
203
+ **C. 임베딩 오류 시 키워드 전용 모드 자동 전환**:
204
+ - `CLAUDE_MEMORY_RETRIEVAL_MODE=keyword` 임시 설정
205
+ - 사용자에게 `<system>` 메시지로 알림
206
+
207
+ **변경 파일**:
208
+ - `src/hooks/semantic-daemon.ts` — 헬스체크 및 자동 폴백 강화
209
+ - `src/server/api/stats.ts` — 모델 상태 지표 추가
210
+
211
+ ---
212
+
213
+ ### IMP-06: Helpfulness 피드백 루프
214
+
215
+ **우선순위**: P2
216
+
217
+ **문제**:
218
+ - `sessions_helpfulness` 테이블 존재하나 데이터 없음
219
+ - 검색된 메모리가 실제로 유용했는지 측정 불가
220
+ - 유용하지 않은 메모리가 계속 상위에 노출될 수 있음
221
+
222
+ **해결 방안**:
223
+
224
+ **A. 휴리스틱 기반 자동 helpfulness 평가**:
225
+ ```
226
+ Stop hook에서:
227
+ 1. 이번 세션에서 검색된 eventId 목록 로드
228
+ 2. agent_response에서 검색된 메모리의 canonicalKey가 언급되었는지 확인
229
+ 3. 언급된 경우 helpfulness = 0.8, 아닌 경우 0.2로 기록
230
+ ```
231
+
232
+ **B. Retrieval Score 가중치에 helpfulness 반영**:
233
+ ```typescript
234
+ // matcher.ts
235
+ score = 0.35 × semanticScore +
236
+ 0.25 × ftsScore +
237
+ 0.20 × recencyBonus +
238
+ 0.10 × statusMultiplier +
239
+ 0.10 × helpfulnessScore; // ← 신규 추가
240
+ ```
241
+
242
+ **C. 낮은 helpfulness 이벤트 강등**:
243
+ - 3회 이상 검색 후 helpfulness 평균 < 0.3이면 min_score 요건 상향
244
+
245
+ **변경 파일**:
246
+ - `src/hooks/stop.ts` — 자동 helpfulness 평가 로직 추가
247
+ - `src/core/matcher.ts` — helpfulness 가중치 추가
248
+ - `src/core/graduation.ts` — helpfulness 기반 강등 규칙 추가
249
+
250
+ ---
251
+
252
+ ### IMP-07: 검색 결과 컨텍스트 포맷 개선
253
+
254
+ **우선순위**: P2
255
+
256
+ **문제**:
257
+ - 검색된 메모리가 Claude에게 전달될 때의 포맷 불명확
258
+ - 메모리 출처(세션 날짜, 프로젝트)가 표시되지 않을 수 있음
259
+ - 100% 선택률 → 품질 필터링 없이 모두 주입
260
+
261
+ **해결 방안**:
262
+
263
+ **A. 메모리 컨텍스트 포맷 구조화**:
264
+ ```
265
+ <memory source="2026-02-25" session="5ef326be" confidence="0.87">
266
+ [쇼핑 어시스턴트 LLM function call 구현 중]
267
+ 이전에 generalize_with_llm() 함수를 사용해서 상품 추천 로직을 개선했음.
268
+ 결과: 응답 속도 40% 향상.
269
+ </memory>
270
+ ```
271
+
272
+ **B. 신뢰도 기준 필터링 강화**:
273
+ - `high` confidence만 자동 주입 (현재 ≥0.92)
274
+ - `suggested` confidence는 optional hint로 분리
275
+ - 100% 선택률 → 선택적 포함으로 변경
276
+
277
+ **변경 파일**:
278
+ - `src/hooks/user-prompt-submit.ts` — 컨텍스트 포맷 템플릿 개선
279
+ - `src/core/retriever.ts` — suggested confidence 분리 출력
280
+
281
+ ---
282
+
283
+ ## 구현 순서
284
+
285
+ ```
286
+ Week 1 (Critical Path):
287
+ IMP-01: Trace 동기 기록 → 즉시 측정 가능
288
+ IMP-02: Tool Observation 필터링 → 노이즈 감소
289
+
290
+ Week 2 (Quality):
291
+ IMP-03: 세션 요약 신뢰성
292
+ IMP-04: Graduation repair CLI
293
+ IMP-05: Embedding 모델 모니터링
294
+
295
+ Week 3 (Feedback Loop):
296
+ IMP-06: Helpfulness 피드백
297
+ IMP-07: 컨텍스트 포맷 개선
298
+ ```
299
+
300
+ ---
301
+
302
+ ## 리스크
303
+
304
+ | 리스크 | 가능성 | 영향 | 대응 |
305
+ |--------|--------|------|------|
306
+ | IMP-02로 중요 tool observation 누락 | 중 | 중 | 키워드 필터 화이트리스트 설정 |
307
+ | IMP-04 graduation repair로 L0 과잉 승격 | 저 | 중 | dry-run 모드 먼저 실행 |
308
+ | IMP-01 sync 변환으로 hook 응답 지연 | 저 | 저 | trace INSERT는 < 1ms (SQLite sync) |