claude-memory-layer 1.0.31 → 1.0.32

package/specs/web-viewer-ui/spec.md

@@ -1,516 +0,0 @@
-# Web Viewer UI Specification
-
-> **Version**: 1.0.0
-> **Status**: Draft
-> **Created**: 2026-02-01
-> **Reference**: claude-mem (thedotmack/claude-mem)
-
-## 1. 개요
-
-### 1.1 문제 정의
-
-현재 시스템에서 메모리 상태 시각화가 어려움:
-
-1. **CLI 한계**: 대량 데이터 탐색 불편
-2. **실시간 모니터링 없음**: 세션 진행 중 메모리 변화 확인 불가
-3. **디버깅 어려움**: 메모리 저장/검색 과정 추적 어려움
-
-### 1.2 해결 방향
-
-**Web Viewer UI**:
-- HTTP API 서버 (localhost:37777)
-- 실시간 메모리 스트림 대시보드
-- 세션/프로젝트별 탐색 인터페이스
-
-## 2. 핵심 개념
-
-### 2.1 시스템 아키텍처
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                     Claude Code                              │
-│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐        │
-│  │ Hooks   │  │ CLI     │  │ Memory  │  │ Web     │        │
-│  │         │  │         │  │ Service │  │ Server  │        │
-│  └────┬────┘  └────┬────┘  └────┬────┘  └────┬────┘        │
-│       │            │            │            │              │
-│       └────────────┴────────────┴────────────┘              │
-│                          │                                   │
-└──────────────────────────┼───────────────────────────────────┘
-                           │
-                           ▼
-┌─────────────────────────────────────────────────────────────┐
-│                    Web Server (Bun)                          │
-│                    localhost:37777                           │
-│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
-│  │ REST API    │  │ WebSocket   │  │ Static      │         │
-│  │ /api/*      │  │ /ws         │  │ /           │         │
-│  └─────────────┘  └─────────────┘  └─────────────┘         │
-└─────────────────────────────────────────────────────────────┘
-                           │
-                           ▼
-┌─────────────────────────────────────────────────────────────┐
-│                    Web Browser                               │
-│  ┌─────────────────────────────────────────────────────┐   │
-│  │  Memory Dashboard                                    │   │
-│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐          │   │
-│  │  │ Sessions │  │ Timeline │  │ Search   │          │   │
-│  │  └──────────┘  └──────────┘  └──────────┘          │   │
-│  └─────────────────────────────────────────────────────┘   │
-└─────────────────────────────────────────────────────────────┘
-```
-
-### 2.2 주요 기능
-
-| 기능 | 설명 |
-|------|------|
-| **Session Browser** | 세션 목록, 세션별 이벤트 탐색 |
-| **Memory Timeline** | 시간순 메모리 스트림 (실시간) |
-| **Search Interface** | 벡터 검색 + 필터링 |
-| **Stats Dashboard** | 저장소 통계, 사용량 |
-| **Debug View** | Outbox 상태, 임베딩 진행률 |
-| **Settings** | 설정 조회/수정 |
-
-### 2.3 포트 및 경로
-
-```
-http://localhost:37777
-├── /                    # 대시보드 메인
-├── /sessions            # 세션 목록
-├── /sessions/:id        # 세션 상세
-├── /timeline            # 실시간 타임라인
-├── /search              # 검색 인터페이스
-├── /stats               # 통계
-├── /settings            # 설정
-└── /api                 # REST API
-    ├── /api/sessions
-    ├── /api/events
-    ├── /api/search
-    ├── /api/stats
-    └── /api/config
-```
-
-## 3. REST API 스키마
-
-### 3.1 Sessions API
-
-```typescript
-// GET /api/sessions
-interface SessionsResponse {
-  sessions: {
-    sessionId: string;
-    projectPath: string;
-    startedAt: Date;
-    endedAt?: Date;
-    eventCount: number;
-    status: 'active' | 'ended';
-  }[];
-  total: number;
-  page: number;
-  pageSize: number;
-}
-
-// GET /api/sessions/:id
-interface SessionDetailResponse {
-  session: {
-    sessionId: string;
-    projectPath: string;
-    startedAt: Date;
-    endedAt?: Date;
-    summary?: string;
-  };
-  events: Event[];
-  stats: {
-    promptCount: number;
-    responseCount: number;
-    toolCount: number;
-    totalTokens: number;
-  };
-}
-```
-
-### 3.2 Events API
-
-```typescript
-// GET /api/events?sessionId=xxx&type=xxx&limit=100
-interface EventsResponse {
-  events: {
-    eventId: string;
-    eventType: string;
-    timestamp: Date;
-    sessionId: string;
-    preview: string;        // 100자 미리보기
-    metadata: {
-      tokenCount?: number;
-      hasCode?: boolean;
-    };
-  }[];
-  total: number;
-}
-
-// GET /api/events/:id
-interface EventDetailResponse {
-  event: {
-    eventId: string;
-    eventType: string;
-    timestamp: Date;
-    sessionId: string;
-    payload: unknown;       // 전체 페이로드
-  };
-  related: {
-    previous?: string;
-    next?: string;
-  };
-}
-```
-
-### 3.3 Search API
-
-```typescript
-// POST /api/search
-interface SearchRequest {
-  query: string;
-  filters?: {
-    sessionId?: string;
-    eventType?: string[];
-    dateFrom?: Date;
-    dateTo?: Date;
-  };
-  options?: {
-    topK?: number;
-    minScore?: number;
-    progressive?: boolean;
-  };
-}
-
-interface SearchResponse {
-  results: {
-    id: string;
-    score: number;
-    type: string;
-    timestamp: Date;
-    sessionId: string;
-    preview: string;
-    highlight?: string;     // 매칭된 부분 강조
-  }[];
-  meta: {
-    totalMatches: number;
-    searchTime: number;
-    mode: 'vector' | 'fts' | 'hybrid';
-  };
-}
-```
-
-### 3.4 Stats API
-
-```typescript
-// GET /api/stats
-interface StatsResponse {
-  storage: {
-    eventCount: number;
-    vectorCount: number;
-    dbSizeMB: number;
-    vectorSizeMB: number;
-  };
-  sessions: {
-    total: number;
-    active: number;
-    thisWeek: number;
-  };
-  embeddings: {
-    pending: number;
-    processed: number;
-    failed: number;
-    avgProcessTime: number;
-  };
-  memory: {
-    heapUsed: number;
-    heapTotal: number;
-  };
-}
-
-// GET /api/stats/timeline
-interface TimelineStatsResponse {
-  daily: {
-    date: string;
-    eventCount: number;
-    sessionCount: number;
-  }[];
-}
-```
-
-### 3.5 Config API
-
-```typescript
-// GET /api/config
-interface ConfigResponse {
-  config: MemoryConfig;
-  editable: string[];      // 수정 가능한 필드 목록
-}
-
-// PATCH /api/config
-interface ConfigUpdateRequest {
-  updates: Partial<MemoryConfig>;
-}
-
-interface ConfigUpdateResponse {
-  success: boolean;
-  config: MemoryConfig;
-  restartRequired?: boolean;
-}
-```
-
-## 4. WebSocket 인터페이스
-
-### 4.1 실시간 이벤트 스트림
-
-```typescript
-// 연결: ws://localhost:37777/ws
-
-// 클라이언트 → 서버 메시지
-interface WSClientMessage {
-  type: 'subscribe' | 'unsubscribe';
-  channels: ('events' | 'stats' | 'outbox')[];
-  filters?: {
-    sessionId?: string;
-    eventType?: string[];
-  };
-}
-
-// 서버 → 클라이언트 메시지
-interface WSServerMessage {
-  channel: 'events' | 'stats' | 'outbox';
-  data: EventMessage | StatsMessage | OutboxMessage;
-}
-
-interface EventMessage {
-  type: 'new_event';
-  event: {
-    eventId: string;
-    eventType: string;
-    timestamp: Date;
-    sessionId: string;
-    preview: string;
-  };
-}
-
-interface OutboxMessage {
-  type: 'outbox_update';
-  pending: number;
-  processing: string[];
-  completed: string[];
-  failed: string[];
-}
-```
-
-### 4.2 연결 예시
-
-```typescript
-// 클라이언트 코드
-const ws = new WebSocket('ws://localhost:37777/ws');
-
-ws.onopen = () => {
-  ws.send(JSON.stringify({
-    type: 'subscribe',
-    channels: ['events', 'outbox']
-  }));
-};
-
-ws.onmessage = (event) => {
-  const msg = JSON.parse(event.data);
-  if (msg.channel === 'events') {
-    addToTimeline(msg.data.event);
-  } else if (msg.channel === 'outbox') {
-    updateOutboxStatus(msg.data);
-  }
-};
-```
-
-## 5. UI 컴포넌트
-
-### 5.1 대시보드 레이아웃
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│  🧠 Code Memory                           [Search] [Settings]│
-├─────────────────────────────────────────────────────────────┤
-│  ┌─────────────┐  ┌───────────────────────────────────────┐ │
-│  │             │  │                                       │ │
-│  │  Sessions   │  │           Main Content Area           │ │
-│  │  ─────────  │  │                                       │ │
-│  │  > session1 │  │   - Timeline View                     │ │
-│  │    session2 │  │   - Search Results                    │ │
-│  │    session3 │  │   - Session Details                   │ │
-│  │    ...      │  │   - Stats Dashboard                   │ │
-│  │             │  │                                       │ │
-│  │  ─────────  │  │                                       │ │
-│  │  Projects   │  │                                       │ │
-│  │  > project1 │  │                                       │ │
-│  │    project2 │  │                                       │ │
-│  │             │  │                                       │ │
-│  └─────────────┘  └───────────────────────────────────────┘ │
-├─────────────────────────────────────────────────────────────┤
-│  Events: 1,234  │  Vectors: 987  │  Outbox: 5 pending      │
-└─────────────────────────────────────────────────────────────┘
-```
-
-### 5.2 Timeline View
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│  📅 Timeline                    [Filter ▼] [Live ●]         │
-├─────────────────────────────────────────────────────────────┤
-│                                                              │
-│  ○─── 14:35 ───────────────────────────────────────────────│
-│  │                                                          │
-│  │  💬 User Prompt                                          │
-│  │  "DuckDB 스키마를 어떻게 설계할까요?"                      │
-│  │                                                          │
-│  ○─── 14:36 ───────────────────────────────────────────────│
-│  │                                                          │
-│  │  🛠️ Tool: Read                                           │
-│  │  /src/core/event-store.ts                               │
-│  │                                                          │
-│  ○─── 14:37 ───────────────────────────────────────────────│
-│  │                                                          │
-│  │  🤖 Assistant Response                                   │
-│  │  "DuckDB를 사용하여 이벤트 소싱 패턴을..."               │
-│  │  [Show Full] [Copy]                                      │
-│  │                                                          │
-│  ○─── 14:40 ───────────────────────────────────────────────│
-│                                                              │
-└─────────────────────────────────────────────────────────────┘
-```
-
-### 5.3 Search View
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│  🔍 Search                                                   │
-├─────────────────────────────────────────────────────────────┤
-│  ┌─────────────────────────────────────────────────────┐   │
-│  │  Type to search memories...                          │   │
-│  └─────────────────────────────────────────────────────┘   │
-│                                                              │
-│  Filters: [All Types ▼] [All Sessions ▼] [Date Range ▼]    │
-│                                                              │
-│  ─────────────────────────────────────────────────────────  │
-│                                                              │
-│  📄 Result 1 (score: 0.94)                                  │
-│  Session: abc123 │ 2026-01-30 14:05                         │
-│  "DuckDB를 사용하여 이벤트 소싱 패턴을 구현하는 방법을..."   │
-│  [View] [Timeline] [Copy ID]                                │
-│                                                              │
-│  📄 Result 2 (score: 0.87)                                  │
-│  Session: def456 │ 2026-01-29 10:20                         │
-│  "타입 시스템 리팩토링 시 고려할 점..."                      │
-│  [View] [Timeline] [Copy ID]                                │
-│                                                              │
-└─────────────────────────────────────────────────────────────┘
-```
-
-### 5.4 Stats Dashboard
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│  📊 Statistics                           [Refresh] [Export] │
-├─────────────────────────────────────────────────────────────┤
-│                                                              │
-│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
-│  │   Events     │  │   Vectors    │  │   Sessions   │      │
-│  │    1,234     │  │     987      │  │      45      │      │
-│  │   ↑12 today  │  │   ↑8 today   │  │   3 active   │      │
-│  └──────────────┘  └──────────────┘  └──────────────┘      │
-│                                                              │
-│  Storage                                                     │
-│  ┌─────────────────────────────────────────────────────┐   │
-│  │ DuckDB  [████████░░] 156 MB / 500 MB               │   │
-│  │ LanceDB [███░░░░░░░]  45 MB / 500 MB               │   │
-│  └─────────────────────────────────────────────────────┘   │
-│                                                              │
-│  Embedding Pipeline                                          │
-│  ┌─────────────────────────────────────────────────────┐   │
-│  │ Pending: 5  │  Processing: 2  │  Failed: 0          │   │
-│  │ Avg Time: 125ms                                      │   │
-│  └─────────────────────────────────────────────────────┘   │
-│                                                              │
-│  Activity (Last 7 Days)                                      │
-│  ┌─────────────────────────────────────────────────────┐   │
-│  │     ▂▄█▆▃▂▄                                          │   │
-│  │    Mon Tue Wed Thu Fri Sat Sun                       │   │
-│  └─────────────────────────────────────────────────────┘   │
-│                                                              │
-└─────────────────────────────────────────────────────────────┘
-```
-
-## 6. 기술 스택
-
-### 6.1 서버
-
-| 컴포넌트 | 기술 | 이유 |
-|----------|------|------|
-| HTTP Server | Bun.serve | 빠른 성능, 번들 불필요 |
-| WebSocket | Bun WebSocket | 내장 지원 |
-| Router | Hono | 경량, Bun 최적화 |
-
-### 6.2 클라이언트
-
-| 컴포넌트 | 기술 | 이유 |
-|----------|------|------|
-| UI Framework | Preact + HTM | 번들 크기 최소 |
-| Styling | Tailwind CSS | 빠른 개발 |
-| State | Signals | 경량 반응성 |
-| Charts | Chart.js | 간단한 통계 시각화 |
-
-### 6.3 대안
-
-| 옵션 | 장점 | 단점 |
-|------|------|------|
-| React + Vite | 생태계 | 번들 크기 |
-| Vue 3 | 간결함 | 추가 학습 |
-| Svelte | 번들 최소 | 생태계 작음 |
-| **Preact + HTM** | 초경량, JSX 없이 | 생태계 제한 |
-
-## 7. 보안
-
-### 7.1 접근 제어
-
-```typescript
-// localhost만 허용
-const server = Bun.serve({
-  hostname: '127.0.0.1',  // localhost만
-  port: 37777,
-  // ...
-});
-
-// 또는 토큰 기반
-const AUTH_TOKEN = process.env.MEMORY_VIEWER_TOKEN;
-
-function authMiddleware(req: Request): boolean {
-  const token = req.headers.get('Authorization');
-  return token === `Bearer ${AUTH_TOKEN}`;
-}
-```
-
-### 7.2 민감 정보 필터링
-
-```typescript
-// API 응답에서 민감 정보 제거
-function sanitizeEvent(event: Event): SanitizedEvent {
-  return {
-    ...event,
-    payload: maskSensitiveFields(event.payload)
-  };
-}
-```
-
-## 8. 성공 기준
-
-- [ ] localhost:37777에서 대시보드 접근 가능
-- [ ] 세션 목록 및 상세 조회 동작
-- [ ] 실시간 이벤트 스트림 표시
-- [ ] 검색 기능 동작 (벡터 + FTS)
-- [ ] 통계 대시보드 표시
-- [ ] WebSocket 연결 안정적
-- [ ] 첫 로드 < 1초
-- [ ] API 응답 < 200ms

package/src/adapters/claude/capture/index.ts

@@ -1,3 +0,0 @@
-/** Claude capture policy layer for prompts, responses, and tools. */
-
-export {};

package/src/adapters/claude/context/index.ts

@@ -1,3 +0,0 @@
-/** Claude-specific context rendering and prompt formatting layer. */
-
-export {};

package/src/adapters/claude/hooks/index.ts

@@ -1,21 +0,0 @@
-/** Claude Code hook adapter entrypoints and supporting runtime utilities. */
-
-export { main as postToolUseMain } from './post-tool-use.js';
-export { main as sessionEndMain } from './session-end.js';
-export { main as semanticDaemonMain } from './semantic-daemon.js';
-export { main as sessionStartMain } from './session-start.js';
-export { main as stopMain } from './stop.js';
-export { main as userPromptSubmitMain } from './user-prompt-submit.js';
-export {
-  handleSemanticDaemonRequest,
-  isValidSemanticDaemonRequest,
-  isVectorSessionFilterError,
-  makeSemanticDaemonErrorResponse,
-  parseSemanticDaemonRequest
-} from './semantic-daemon.js';
-export type {
-  SemanticDaemonRequest,
-  SemanticDaemonResponse,
-  SemanticMemory
-} from './semantic-daemon.js';
-export * from './semantic-daemon-client.js';