claude-memory-layer 1.0.31 → 1.0.33

package/specs/20260207-dashboard-upgrade/spec.md

@@ -1,96 +0,0 @@
-# Dashboard Upgrade Spec
-
-## Overview
-대시보드에 인터랙티브 기능 추가. 메모리 이벤트 클릭 시 상세 모달, stat 카드 클릭 시 관련 데이터 목록, 사이드바 네비게이션으로 페이지 전환.
-
-## User Stories
-
-### US-1: 메모리 이벤트 상세 모달
-- **As a** 사용자
-- **I want** 메모리 이벤트를 클릭하면 전체 내용을 모달로 볼 수 있다
-- **So that** 잘린 preview가 아닌 전체 content와 context를 확인할 수 있다
-
-### US-2: Stat 카드 클릭 → 관련 데이터 표시
-- **As a** 사용자
-- **I want** Total Events, Active Sessions, Shared Items, Vector Nodes 카드를 클릭하면 해당 데이터 목록을 볼 수 있다
-- **So that** 대시보드 숫자의 실제 데이터를 탐색할 수 있다
-
-### US-3: 사이드바 네비게이션 페이지 전환
-- **As a** 사용자
-- **I want** Knowledge Graph, Memory Banks, Configuration을 클릭하면 메인 콘텐츠 영역이 해당 뷰로 전환된다
-- **So that** 대시보드 외의 기능에도 접근할 수 있다
-
-## Acceptance Criteria
-
-### AC-1: 메모리 이벤트 모달
-- [ ] 이벤트 아이템 클릭 시 모달 오픈
-- [ ] 모달에 전체 content 표시 (잘림 없이)
-- [ ] eventType, timestamp, sessionId 메타데이터 표시
-- [ ] context (앞뒤 이벤트) 표시
-- [ ] ESC 키 또는 오버레이 클릭으로 모달 닫기
-- [ ] 로딩 상태 표시
-
-### AC-2: Stat 카드 클릭
-- [ ] **Total Events** 클릭 → 전체 이벤트 목록 모달 (타입별 필터, 페이지네이션)
-- [ ] **Active Sessions** 클릭 → 세션 목록 모달 (세션 ID, 이벤트 수, 시작/종료 시간)
-- [ ] **Shared Items** 클릭 → 공유 아이템 상세 모달 (Troubleshooting, Best Practices, Common Errors 카운트)
-- [ ] **Vector Nodes** 클릭 → 벡터 노드 정보 모달 (벡터 수, 메모리 사용량)
-
-### AC-3: 사이드바 네비게이션
-- [ ] **Overview** → 현재 대시보드 (기존 동작 유지)
-- [ ] **Knowledge Graph** → 가장 많이 접근된 메모리, 토픽별 분포 표시
-- [ ] **Memory Banks** → 레벨별 메모리 목록 (L0~L4), 졸업 기준 표시
-- [ ] **Configuration** → 졸업 기준 설정, 시스템 정보 표시
-- [ ] active nav-item 하이라이트 전환
-- [ ] 페이지 전환 시 부드러운 트랜지션
-
-## Technical Constraints
-- 순수 HTML/CSS/JS (프레임워크 없음)
-- 기존 `app.js`, `style.css`, `index.html` 수정
-- 기존 API 엔드포인트 최대한 활용
-- ApexCharts는 Overview 페이지에서만 사용
-
-## API Endpoints (기존)
-
-| Endpoint | Method | 용도 |
-|----------|--------|------|
-| `/api/events/:id` | GET | 이벤트 상세 (content + context) |
-| `/api/events` | GET | 이벤트 목록 (level, sort, limit, offset) |
-| `/api/sessions` | GET | 세션 목록 (page, pageSize) |
-| `/api/sessions/:id` | GET | 세션 상세 |
-| `/api/stats` | GET | 전체 통계 |
-| `/api/stats/shared` | GET | 공유 스토어 통계 |
-| `/api/stats/most-accessed` | GET | 가장 많이 접근된 메모리 |
-| `/api/stats/levels/:level` | GET | 레벨별 이벤트 |
-| `/api/stats/graduation` | GET | 졸업 기준 정보 |
-| `/api/stats/helpfulness` | GET | 도움됨 통계 |
-| `/api/stats/timeline` | GET | 활동 타임라인 |
-| `/api/search?q=` | GET | 메모리 검색 |
-
-## UI Components (신규)
-
-### 1. Detail Modal (`#detail-modal`)
-- overlay + centered content box
-- header: 타입 배지 + 타임스탬프 + 닫기 버튼
-- body: 전체 content (코드 블록 포맷팅)
-- footer: context 이벤트 목록
-- 애니메이션: fadeIn/fadeOut
-
-### 2. List Modal (`#list-modal`)
-- stat 카드 클릭 시 사용하는 범용 목록 모달
-- header: 제목 + 닫기 버튼
-- body: 스크롤 가능한 아이템 목록
-- 각 아이템 클릭 시 detail modal 열기 가능
-
-### 3. Page Views
-- `#view-overview` - 기존 대시보드 (기본)
-- `#view-knowledge-graph` - Knowledge Graph 뷰
-- `#view-memory-banks` - Memory Banks 뷰
-- `#view-configuration` - Configuration 뷰
-- 한 번에 하나만 visible (display: none/block 전환)
-
-## Design Guidelines
-- 기존 Deep Space 테마 유지
-- 모달: `var(--bg-panel)` 배경, `var(--glass-border)` 테두리
-- 애니메이션: 200~300ms ease 트랜지션
-- 모바일 대응: 모달 full-width on mobile

package/specs/citations-system/context.md

@@ -1,243 +0,0 @@
-# Citations System Context
-
-> **Version**: 1.0.0
-> **Created**: 2026-02-01
-
-## 1. 배경
-
-### 1.1 claude-mem의 접근 방식
-
-claude-mem은 observation에 ID를 부여하여 참조 가능하게 함:
-
-```
-[mem:abc123] 에서 참조한 정보입니다.
-```
-
-**특징**:
-- 모든 observation에 고유 ID
-- 검색 결과에 ID 표시
-- ID로 원본 조회 가능
-
-### 1.2 현재 code-memory의 상황
-
-현재 이벤트 ID는 존재하지만 인용 시스템 없음:
-
-```typescript
-// 현재 검색 결과
-{
-  eventId: "evt_abc123def456...",  // 긴 UUID
-  content: "...",
-  score: 0.9
-}
-```
-
-**문제**:
-1. eventId가 너무 길어서 참조하기 불편
-2. 컨텍스트에 인용 표시 없음
-3. 출처 확인 어려움
-
-### 1.3 인용의 가치
-
-| 인용 없음 | 인용 있음 |
-|----------|----------|
-| 출처 불명 | 명확한 출처 |
-| 검증 불가 | 원본 확인 가능 |
-| 맥락 손실 | 전후 관계 파악 |
-| 신뢰도 낮음 | 신뢰도 높음 |
-
-## 2. ID 설계
-
-### 2.1 고려사항
-
-| 요소 | 요구사항 |
-|------|----------|
-| 길이 | 짧고 기억하기 쉬움 |
-| 고유성 | 충돌 확률 낮음 |
-| 가독성 | 쉽게 읽고 말할 수 있음 |
-| 생성 | 빠르고 결정적 |
-
-### 2.2 옵션 비교
-
-| 옵션 | 예시 | 조합 수 | 장점 | 단점 |
-|------|------|--------|------|------|
-| 4자 base62 | a7Bc | 14.7M | 매우 짧음 | 충돌 위험 |
-| **6자 base62** | a7Bc3x | 56.8B | 균형 | - |
-| 8자 base62 | a7Bc3xYz | 218T | 충돌 없음 | 다소 김 |
-| 8자 hex | ab12cd34 | 4.3B | 익숙함 | 효율 낮음 |
-
-**선택**: 6자 base62 (56.8억 조합)
-- 1000만 이벤트에서 충돌 확률 < 0.0001%
-
-### 2.3 생성 알고리즘
-
-```typescript
-// SHA256 해시 기반 (결정적, 빠름)
-function generateCitationId(eventId: string): string {
-  const hash = crypto.createHash('sha256').update(eventId).digest();
-
-  // base62 인코딩
-  const charset = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
-  let id = '';
-  for (let i = 0; i < 6; i++) {
-    id += charset[hash[i] % 62];
-  }
-  return id;
-}
-```
-
-## 3. 기존 코드와의 관계
-
-### 3.1 event-store.ts
-
-인용 테이블 추가:
-
-```sql
--- events 테이블과 1:1 관계
-CREATE TABLE citations (
-  citation_id VARCHAR(8) PRIMARY KEY,
-  event_id VARCHAR NOT NULL UNIQUE REFERENCES events(event_id)
-);
-```
-
-### 3.2 retriever.ts
-
-검색 결과에 인용 포함:
-
-```typescript
-// 현재
-async search(query): Promise<SearchResult[]>
-
-// 확장
-async searchWithCitations(query): Promise<CitedSearchResult[]>
-```
-
-### 3.3 context-formatter.ts
-
-인용 표시 포맷:
-
-```typescript
-// 현재
-> DuckDB를 사용하여...
-
-// 확장
-> DuckDB를 사용하여...
->
-> [mem:a7Bc3x] - 2026-01-30, Session abc123
-```
-
-## 4. 설계 결정 사항
-
-### 4.1 생성 시점
-
-**옵션 1: 이벤트 저장 시 즉시 생성**
-- 장점: 항상 인용 ID 존재
-- 단점: 저장 오버헤드
-
-**옵션 2: 검색 시 지연 생성**
-- 장점: 필요할 때만 생성
-- 단점: 첫 검색 약간 느림
-
-**선택**: 지연 생성 (getOrCreate 패턴)
-- 저장 시 오버헤드 없음
-- 대부분 이벤트는 검색되지 않음
-
-### 4.2 인용 포맷
-
-**옵션들**:
-1. `[mem:a7Bc3x]` - 명확하고 검색 가능
-2. `(ref: a7Bc3x)` - 간결
-3. `¹` (각주 스타일) - 학술적
-4. `<a7Bc3x>` - 태그 스타일
-
-**선택**: `[mem:a7Bc3x]`
-- `mem:` 접두사로 명확한 의미
-- 대괄호로 시각적 구분
-- 검색/복사 용이
-
-### 4.3 컨텍스트 포함 방식
-
-**인라인 방식** (선택):
-```markdown
-> 내용...
-> [mem:a7Bc3x] - 2026-01-30
-```
-
-**각주 방식**:
-```markdown
-DuckDB를 사용[1]...
-
----
-[1] mem:a7Bc3x - 2026-01-30
-```
-
-**참조 방식**:
-```markdown
-## Content
-DuckDB를 사용...
-
-## References
-- [mem:a7Bc3x] Session abc123, 2026-01-30
-```
-
-## 5. 사용 추적
-
-### 5.1 목적
-
-- 인기 있는 메모리 파악
-- 자주 참조되는 지식 식별
-- graduation 우선순위 결정
-
-### 5.2 추적 데이터
-
-```sql
-CREATE TABLE citation_usages (
-  usage_id VARCHAR PRIMARY KEY,
-  citation_id VARCHAR NOT NULL,
-  session_id VARCHAR NOT NULL,
-  used_at TIMESTAMP,
-  context VARCHAR  -- 검색 쿼리
-);
-```
-
-### 5.3 통계 활용
-
-```typescript
-// 인기 인용 → graduation 우선순위
-async function graduationCandidates(): Promise<Event[]> {
-  const popular = await getPopularCitations({ limit: 100 });
-  return popular.filter(c => c.usageCount >= 5);
-}
-```
-
-## 6. 성능 고려사항
-
-### 6.1 ID 생성
-
-- SHA256 해시: ~1µs
-- DB 조회 (exists): ~1ms
-- 충돌 시 재시도: 드묾
-
-### 6.2 인덱스
-
-```sql
--- 빠른 조회를 위한 인덱스
-CREATE INDEX idx_citations_event ON citations(event_id);
-CREATE INDEX idx_usages_citation ON citation_usages(citation_id);
-```
-
-### 6.3 캐싱
-
-```typescript
-// 최근 사용된 인용 캐싱
-const citationCache = new LRUCache<string, Citation>({
-  max: 1000,
-  ttl: 3600000  // 1시간
-});
-```
-
-## 7. 참고 자료
-
-- **claude-mem**: Citation system with observation IDs
-- **학술 인용**: APA, MLA 스타일
-- **GitHub**: Issue/PR 참조 (#123)
-- **Notion**: 블록 ID 참조 시스템