claude-memory-layer 1.0.0

package/specs/citations-system/spec.md

@@ -0,0 +1,371 @@
+# Citations System Specification
+
+> **Version**: 1.0.0
+> **Status**: Draft
+> **Created**: 2026-02-01
+> **Reference**: claude-mem (thedotmack/claude-mem)
+
+## 1. 개요
+
+### 1.1 문제 정의
+
+현재 시스템에서 메모리 출처 추적이 어려움:
+
+1. **출처 불명확**: 검색 결과가 어느 세션에서 왔는지 즉시 파악 어려움
+2. **검증 불가**: AI가 참조한 정보의 원본 확인 어려움
+3. **맥락 손실**: 인용된 정보의 전후 맥락 파악 어려움
+
+### 1.2 해결 방향
+
+**Citations (인용) 시스템**:
+- 모든 메모리에 고유 인용 ID 부여
+- 컨텍스트 주입 시 인용 표시
+- 클릭/명령으로 원본 조회 가능
+
+## 2. 핵심 개념
+
+### 2.1 인용 형식
+
+```
+[mem:abc123] 에서 참조한 정보입니다.
+```
+
+### 2.2 인용 구조
+
+```typescript
+interface Citation {
+  // 식별
+  id: string;                    // 짧은 인용 ID (6-8자)
+  eventId: string;               // 전체 이벤트 ID
+
+  // 출처 정보
+  sessionId: string;
+  timestamp: Date;
+  eventType: 'prompt' | 'response' | 'tool' | 'insight';
+
+  // 메타데이터
+  preview: string;               // 50자 미리보기
+  confidence: number;            // 매칭 신뢰도
+  relevanceScore: number;        // 검색 관련성 점수
+}
+```
+
+### 2.3 인용 ID 생성
+
+```typescript
+// 짧고 읽기 쉬운 ID
+function generateCitationId(eventId: string): string {
+  // eventId의 해시에서 6자 추출
+  const hash = crypto.createHash('sha256')
+    .update(eventId)
+    .digest('base64url')
+    .slice(0, 6);
+
+  return hash;  // 예: "a7Bc3x"
+}
+```
+
+## 3. 데이터 스키마
+
+### 3.1 인용 테이블
+
+```sql
+CREATE TABLE citations (
+  citation_id   VARCHAR(8) PRIMARY KEY,
+  event_id      VARCHAR NOT NULL REFERENCES events(event_id),
+  created_at    TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+
+  -- 인덱스
+  UNIQUE(event_id)
+);
+
+CREATE INDEX idx_citations_event ON citations(event_id);
+```
+
+### 3.2 이벤트 확장
+
+```typescript
+const EventSchema = z.object({
+  eventId: z.string(),
+  // ... 기존 필드
+
+  // 인용 정보 추가
+  citationId: z.string().optional(),  // 생성된 인용 ID
+});
+```
+
+## 4. 인용 생성 흐름
+
+### 4.1 자동 생성
+
+```typescript
+// 이벤트 저장 시 자동으로 인용 ID 생성
+async function storeEventWithCitation(event: Event): Promise<string> {
+  const eventId = await eventStore.append(event);
+
+  // 인용 ID 생성 및 저장
+  const citationId = generateCitationId(eventId);
+  await citationStore.create({
+    citationId,
+    eventId,
+    createdAt: new Date()
+  });
+
+  return eventId;
+}
+```
+
+### 4.2 지연 생성
+
+```typescript
+// 검색 시 필요할 때만 인용 ID 생성
+async function getCitationId(eventId: string): Promise<string> {
+  // 기존 인용 확인
+  const existing = await citationStore.findByEventId(eventId);
+  if (existing) {
+    return existing.citationId;
+  }
+
+  // 새로 생성
+  const citationId = generateCitationId(eventId);
+  await citationStore.create({ citationId, eventId });
+  return citationId;
+}
+```
+
+## 5. 컨텍스트 주입
+
+### 5.1 인용 포함 포맷
+
+```markdown
+## Relevant Context
+
+Based on previous conversations:
+
+> DuckDB를 사용하여 이벤트 소싱 패턴을 구현하는 것이 좋습니다.
+> 이벤트는 불변이어야 하며, append-only 방식으로 저장합니다.
+>
+> [mem:a7Bc3x] - 2026-01-30, Session abc123
+
+---
+
+> 타입 안전성을 위해 Zod 스키마를 사용하세요.
+>
+> [mem:x9Yz2w] - 2026-01-29, Session def456
+```
+
+### 5.2 포맷터 구현
+
+```typescript
+interface CitedMemory {
+  content: string;
+  citation: Citation;
+}
+
+function formatCitedContext(memories: CitedMemory[]): string {
+  const parts = memories.map(m => {
+    const lines = [
+      `> ${m.content}`,
+      `>`,
+      `> [mem:${m.citation.id}] - ${formatDate(m.citation.timestamp)}, ` +
+      `Session ${m.citation.sessionId.slice(0, 6)}`
+    ];
+    return lines.join('\n');
+  });
+
+  return [
+    '## Relevant Context',
+    '',
+    'Based on previous conversations:',
+    '',
+    parts.join('\n\n---\n\n')
+  ].join('\n');
+}
+```
+
+## 6. 인용 조회
+
+### 6.1 CLI 명령
+
+```bash
+# 인용 ID로 원본 조회
+$ code-memory show mem:a7Bc3x
+
+📄 Memory Citation: a7Bc3x
+
+Session: abc123
+Date: 2026-01-30 14:05
+Type: assistant_response
+
+Content:
+────────────────────────────────────────
+DuckDB를 사용하여 이벤트 소싱 패턴을 구현하는 것이 좋습니다.
+이벤트는 불변이어야 하며, append-only 방식으로 저장합니다.
+
+스키마 예시:
+```sql
+CREATE TABLE events (
+  event_id VARCHAR PRIMARY KEY,
+  ...
+);
+```
+────────────────────────────────────────
+
+Related:
+  Previous: [mem:b8Xc2y] - User question about DB design
+  Next: [mem:c9Yd3z] - Follow-up on indexing
+```
+
+### 6.2 API 엔드포인트
+
+```typescript
+// GET /api/citations/:id
+router.get('/citations/:id', async (c) => {
+  const { id } = c.req.param();
+
+  const citation = await citationStore.findById(id);
+  if (!citation) {
+    return c.json({ error: 'Citation not found' }, 404);
+  }
+
+  const event = await eventStore.findById(citation.eventId);
+  const related = await getRelatedEvents(citation.eventId);
+
+  return c.json({
+    citation,
+    event,
+    related
+  });
+});
+```
+
+### 6.3 슬래시 명령
+
+```
+User: /show a7Bc3x
+
+---
+이 메모리의 전체 내용을 보여드립니다:
+
+[원본 내용 표시]
+---
+```
+
+## 7. 인용 검색
+
+### 7.1 인용 ID로 검색
+
+```typescript
+async function searchByCitation(citationId: string): Promise<Event | null> {
+  const citation = await citationStore.findById(citationId);
+  if (!citation) return null;
+
+  return eventStore.findById(citation.eventId);
+}
+```
+
+### 7.2 역참조 검색
+
+```typescript
+// 특정 이벤트를 인용한 세션들 조회
+async function findCitingSession(citationId: string): Promise<string[]> {
+  // 인용 사용 로그에서 검색
+  const usages = await citationUsageStore.findByCitationId(citationId);
+  return [...new Set(usages.map(u => u.sessionId))];
+}
+```
+
+## 8. 인용 사용 추적
+
+### 8.1 사용 로그
+
+```sql
+CREATE TABLE citation_usages (
+  usage_id      VARCHAR PRIMARY KEY,
+  citation_id   VARCHAR NOT NULL,
+  session_id    VARCHAR NOT NULL,
+  used_at       TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  context       VARCHAR  -- 어떤 쿼리에서 사용됐는지
+);
+
+CREATE INDEX idx_usages_citation ON citation_usages(citation_id);
+CREATE INDEX idx_usages_session ON citation_usages(session_id);
+```
+
+### 8.2 인기 인용 통계
+
+```typescript
+async function getPopularCitations(limit: number = 10): Promise<CitationStats[]> {
+  return db.query(`
+    SELECT
+      c.citation_id,
+      COUNT(u.usage_id) as usage_count,
+      MAX(u.used_at) as last_used
+    FROM citations c
+    LEFT JOIN citation_usages u ON c.citation_id = u.citation_id
+    GROUP BY c.citation_id
+    ORDER BY usage_count DESC
+    LIMIT ?
+  `, [limit]);
+}
+```
+
+## 9. UI 표시
+
+### 9.1 CLI
+
+```
+$ code-memory search "DuckDB"
+
+🔍 Search Results:
+
+#1 [mem:a7Bc3x] (score: 0.94)
+   "DuckDB를 사용하여 이벤트 소싱 패턴을..."
+   📅 2026-01-30 | 🔗 Session abc123
+
+#2 [mem:d4Ef5g] (score: 0.87)
+   "DuckDB의 인덱싱 전략..."
+   📅 2026-01-29 | 🔗 Session def456
+
+💡 Use "code-memory show mem:a7Bc3x" for full content
+```
+
+### 9.2 Web Viewer
+
+```html
+<div class="search-result">
+  <div class="result-header">
+    <span class="citation-badge" title="Click to copy">
+      [mem:a7Bc3x]
+    </span>
+    <span class="score">0.94</span>
+  </div>
+  <p class="preview">DuckDB를 사용하여 이벤트 소싱 패턴을...</p>
+  <div class="metadata">
+    <span>📅 2026-01-30</span>
+    <a href="/sessions/abc123">🔗 Session abc123</a>
+  </div>
+  <button onclick="showCitation('a7Bc3x')">View Full</button>
+</div>
+```
+
+## 10. 설정
+
+```typescript
+const CitationsConfigSchema = z.object({
+  enabled: z.boolean().default(true),
+  idLength: z.number().default(6),          // 인용 ID 길이
+  includeInContext: z.boolean().default(true),  // 컨텍스트에 포함
+  trackUsage: z.boolean().default(true),    // 사용 추적
+  format: z.enum(['inline', 'footnote', 'reference']).default('inline')
+});
+```
+
+## 11. 성공 기준
+
+- [ ] 모든 이벤트에 인용 ID 자동 생성
+- [ ] 컨텍스트 주입 시 인용 표시
+- [ ] `code-memory show mem:xxx` 명령 동작
+- [ ] Web Viewer에서 인용 클릭 시 원본 표시
+- [ ] 인용 사용 통계 수집
+- [ ] 인용 ID 충돌 없음 (6자, 64^6 = 687억 조합)

package/specs/endless-mode/context.md

@@ -0,0 +1,305 @@
+# Endless Mode Context
+
+> **Version**: 1.0.0
+> **Created**: 2026-02-01
+
+## 1. 배경
+
+### 1.1 claude-mem의 접근 방식
+
+claude-mem은 "Endless Mode"를 Beta 기능으로 제공:
+
+```
+Biomimetic Memory Architecture for extended sessions
+```
+
+**특징**:
+- 세션 경계 없는 연속 메모리
+- 자동 컨텍스트 통합
+- 장기 학습 지원
+
+### 1.2 인간 기억 시스템 모방
+
+```
+Human Memory:
+┌─────────────────────────────────────────┐
+│ Sensory → Working → Long-term          │
+│ (즉각)    (단기)    (장기)              │
+└─────────────────────────────────────────┘
+
+Endless Mode:
+┌─────────────────────────────────────────┐
+│ Events → Working Set → Consolidated    │
+│ (L0)     (Active)      (Integrated)    │
+└─────────────────────────────────────────┘
+```
+
+### 1.3 현재 code-memory의 세션 모델
+
+```typescript
+// 현재 세션 기반 모델
+session_start → [conversations] → session_end
+                                      ↓
+                              session_summary
+                                      ↓
+                            (새 세션에서 검색)
+```
+
+**한계**:
+1. 세션 경계에서 컨텍스트 단절
+2. 재시작 시 처음부터 컨텍스트 구축
+3. 장기 프로젝트에서 지식 파편화
+
+## 2. Biomimetic Memory 개념
+
+### 2.1 Working Memory (작업 기억)
+
+인간의 작업 기억:
+- 용량 제한: 7±2 항목
+- 지속 시간: 15-30초
+- 적극적 유지 필요
+
+Endless Mode 적용:
+```typescript
+const workingSet = {
+  maxEvents: 100,           // 용량 제한
+  timeWindowHours: 24,      // 시간 제한
+  activeRehearsal: true     // 관련성 높은 것 유지
+};
+```
+
+### 2.2 Memory Consolidation (기억 통합)
+
+인간의 기억 통합:
+- 수면 중 발생
+- 관련 기억 연결
+- 불필요한 세부사항 제거
+- 패턴 추출
+
+Endless Mode 적용:
+```typescript
+const consolidation = {
+  triggerIdleTime: 30 * 60 * 1000,  // 유휴 시 통합 (수면 유사)
+  groupByTopic: true,                // 관련 기억 그룹화
+  summarize: true,                   // 세부사항 요약
+  extractPatterns: true              // 패턴 추출
+};
+```
+
+### 2.3 Context-Dependent Memory
+
+인간: 특정 맥락에서 관련 기억 활성화
+
+Endless Mode:
+```typescript
+// 현재 컨텍스트와 유사한 과거 컨텍스트 활성화
+const relevantContext = await findSimilarContext(currentQuery);
+```
+
+## 3. 기존 코드와의 관계
+
+### 3.1 Graduation 파이프라인과의 관계
+
+```
+기존 Graduation:
+L0 (Raw) → L1 (Structured) → L2 (Validated) → L3 (Verified) → L4 (Active)
+
+Endless Mode 추가:
+L0 (Raw) → Working Set → Consolidated Memory
+              ↓              ↓
+           (Active)     (Long-term)
+```
+
+**통합 방안**:
+- Working Set은 L0-L2 이벤트 포함
+- Consolidated Memory는 L3-L4 수준의 검증된 지식
+
+### 3.2 Event Store
+
+```typescript
+// 기존: 세션 기반 저장
+await eventStore.append({
+  sessionId: currentSession,
+  ...event
+});
+
+// Endless Mode: 세션 개념 유연화
+await eventStore.append({
+  sessionId: endlessSessionId,  // 고정 또는 날짜 기반
+  workingSetId: currentWorkingSet,
+  ...event
+});
+```
+
+### 3.3 Retriever
+
+```typescript
+// 기존
+async search(query): Promise<Event[]>
+
+// Endless Mode 확장
+async searchWithContext(query, options): Promise<{
+  workingSet: Event[];
+  consolidated: ConsolidatedMemory[];
+  continuityScore: number;
+}>
+```
+
+## 4. 설계 결정 사항
+
+### 4.1 세션 ID 처리
+
+**옵션 1: 고정 세션 ID**
+```typescript
+const ENDLESS_SESSION_ID = 'endless';
+```
+- 단순함
+- 기존 코드 호환
+
+**옵션 2: 날짜 기반 세션 ID**
+```typescript
+const sessionId = `endless_${format(new Date(), 'yyyy-MM-dd')}`;
+```
+- 일별 구분 가능
+- 통계/분석 용이
+
+**선택**: 하이브리드
+- Endless Mode 내부: 날짜 기반
+- 외부 인터페이스: 'endless'로 통합
+
+### 4.2 통합 트리거
+
+**옵션 1: 시간 기반만**
+```typescript
+setInterval(consolidate, 1 * 60 * 60 * 1000);  // 1시간마다
+```
+
+**옵션 2: 이벤트 수 기반만**
+```typescript
+if (workingSet.length >= 100) consolidate();
+```
+
+**옵션 3: 하이브리드 (선택)**
+```typescript
+// 세 가지 조건 중 하나라도 충족 시
+if (
+  timeSinceLastConsolidation >= 1 * 60 * 60 * 1000 ||
+  workingSet.length >= 100 ||
+  idleTime >= 30 * 60 * 1000
+) {
+  consolidate();
+}
+```
+
+### 4.3 요약 생성
+
+**옵션 1: 규칙 기반만**
+```typescript
+// 키포인트 추출
+const summary = events
+  .map(e => extractKeyPoint(e))
+  .join('\n');
+```
+- 빠름, 무료
+- 품질 제한
+
+**옵션 2: LLM 기반**
+```typescript
+const summary = await llm.summarize(events);
+```
+- 고품질
+- 비용, 지연
+
+**선택**: 규칙 기반 기본, LLM 옵션
+```typescript
+if (config.useLLMSummarization) {
+  return await llmSummarize(events);
+} else {
+  return extractKeyPoints(events);
+}
+```
+
+### 4.4 연속성 점수 가중치
+
+```typescript
+const weights = {
+  topicOverlap: 0.3,     // 주제 연속성
+  timeProximity: 0.3,    // 시간 근접성
+  fileOverlap: 0.2,      // 파일 연속성
+  entityOverlap: 0.2     // 엔티티 연속성
+};
+```
+
+**조정 필요 시**:
+- 코드 작업 중심: fileOverlap 가중치 증가
+- 연구/학습 중심: topicOverlap 가중치 증가
+
+## 5. 성능 고려사항
+
+### 5.1 Working Set 크기
+
+```typescript
+// 메모리 사용량 추정
+// 100 이벤트 × 평균 2KB = 200KB
+const maxWorkingSetSize = 100;
+```
+
+### 5.2 Consolidation 비용
+
+```typescript
+// 통합 작업 시간 추정
+// 100 이벤트 그룹화 + 요약: ~100ms
+// LLM 요약 사용 시: ~2s
+```
+
+### 5.3 검색 성능
+
+```typescript
+// Working Set 검색: O(n), n=100, ~1ms
+// Consolidated 검색: 벡터 검색, ~50ms
+```
+
+## 6. 마이그레이션
+
+### 6.1 Session → Endless
+
+```typescript
+async function migrateToEndless(): Promise<void> {
+  // 1. 최근 세션 이벤트를 Working Set에 추가
+  const recentEvents = await getRecentEvents(7 * 24);  // 7일
+
+  for (const event of recentEvents) {
+    await workingSetStore.add(event);
+  }
+
+  // 2. 기존 세션 요약을 Consolidated Memory로 이전
+  const summaries = await getSessionSummaries();
+
+  for (const summary of summaries) {
+    await consolidatedStore.create({
+      summary: summary.content,
+      sourceEvents: [],  // 원본 연결 불가
+      confidence: 0.6    // 낮은 신뢰도
+    });
+  }
+}
+```
+
+### 6.2 Endless → Session 복귀
+
+```typescript
+async function revertToSession(): Promise<void> {
+  // 모드만 변경, 데이터 유지
+  await setConfig('mode', 'session');
+
+  // Working Set과 Consolidated Memory는 유지
+  // (향후 Endless Mode 재활성화 시 활용)
+}
+```
+
+## 7. 참고 자료
+
+- **claude-mem Beta**: Endless Mode, Biomimetic Memory Architecture
+- **Cognitive Psychology**: Working Memory (Baddeley), Memory Consolidation
+- **Spaced Repetition**: 장기 기억 강화 기법
+- **기존 specs**: graduation.ts, vector-worker.ts