claude-memory-layer 1.0.11 → 1.0.12

package/memory/specs/citations-system/2026-02-25.md

@@ -0,0 +1,1121 @@
+
+## 2026-02-25T12:31:26.220Z | 5f1e6336-dbdb-4bd2-96ea-d6f683c03325
+- type: session_summary
+- session: import:organized
+# 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 참조 시스템
+
+## 2026-02-25T12:31:26.227Z | ed4343cd-9ae7-4b7a-ba31-e9b3a5a048da
+- type: session_summary
+- session: import:organized
+# Citations System Implementation Plan
+
+> **Version**: 1.0.0
+> **Status**: Draft
+> **Created**: 2026-02-01
+
+## Phase 1: 인용 저장소 (P0)
+
+### 1.1 스키마 정의
+
+**파일**: `src/core/types.ts` 수정
+
+```typescript
+export const CitationSchema = z.object({
+  citationId: z.string().length(6),
+  eventId: z.string(),
+  createdAt: z.date()
+});
+
+export type Citation = z.infer<typeof CitationSchema>;
+
+export const CitationUsageSchema = z.object({
+  usageId: z.string(),
+  citationId: z.string(),
+  sessionId: z.string(),
+  usedAt: z.date(),
+  context: z.string().optional()
+});
+
+export type CitationUsage = z.infer<typeof CitationUsageSchema>;
+```
+
+**작업 항목**:
+- [ ] Citation 스키마 추가
+- [ ] CitationUsage 스키마 추가
+- [ ] 설정 스키마 확장
+
+### 1.2 DB 테이블
+
+**파일**: `src/core/event-store.ts` 수정
+
+```typescript
+private async initSchema(): Promise<void> {
+  // 기존 테이블...
+
+  // 인용 테이블
+  await this.db.exec(`
+    CREATE TABLE IF NOT EXISTS citations (
+      citation_id VARCHAR(8) PRIMARY KEY,
+      event_id VARCHAR NOT NULL,
+      created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+      UNIQUE(event_id)
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_citations_event ON citations(event_id);
+  `);
+
+  // 사용 로그 테이블
+  await this.db.exec(`
+    CREATE TABLE IF NOT EXISTS 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 IF NOT EXISTS idx_usages_citation ON citation_usages(citation_id);
+  `);
+}
+```
+
+**작업 항목**:
+- [ ] citations 테이블 생성
+- [ ] citation_usages 테이블 생성
+- [ ] 인덱스 생성
+
+## Phase 2: 인용 ID 생성 (P0)
+
+### 2.1 ID 생성기
+
+**파일**: `src/core/citation-generator.ts` (신규)
+
+```typescript
+import { createHash } from 'crypto';
+
+const ID_LENGTH = 6;
+const CHARSET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
+
+export function generateCitationId(eventId: string): string {
+  const hash = createHash('sha256')
+    .update(eventId)
+    .digest();
+
+  let id = '';
+  for (let i = 0; i < ID_LENGTH; i++) {
+    id += CHARSET[hash[i] % CHARSET.length];
+  }
+
+  return id;
+}
+
+// 충돌 처리 (드문 경우)
+export async function generateUniqueCitationId(
+  eventId: string,
+  store: CitationStore
+): Promise<string> {
+  let id = generateCitationId(eventId);
+  let attempt = 0;
+
+  while (await store.exists(id) && attempt < 10) {
+    // 솔트 추가하여 재생성
+    id = generateCitationId(`${eventId}:${attempt}`);
+    attempt++;
+  }
+
+  if (attempt >= 10) {
+    throw new Error('Failed to generate unique citation ID');
+  }
+
+  return id;
+}
+```
+
+**작업 항목**:
+- [ ] generateCitationId 함수 구현
+- [ ] 충돌 처리 로직
+- [ ] 유닛 테스트
+
+### 2.2 인용 저장소
+
+**파일**: `src/core/citation-store.ts` (신규)
+
+```typescript
+export class CitationStore {
+  constructor(private db: Database) {}
+
+  async create(citation: CitationInput): Promise<Citation> {
+    await this.db.run(`
+      INSERT INTO citations (citation_id, event_id, created_at)
+      VALUES (?, ?, ?)
+    `, [citation.citationId, citation.eventId, new Date()]);
+
+    return { ...citation, createdAt: new Date() };
+  }
+
+  async findById(citationId: string): Promise<Citation | null> {
+    return this.db.get(`
+      SELECT * FROM citations WHERE citation_id = ?
+    `, [citationId]);
+  }
+
+  async findByEventId(eventId: string): Promise<Citation | null> {
+    return this.db.get(`
+      SELECT * FROM citations WHERE event_id = ?
+    `, [eventId]);
+  }
+
+  async exists(citationId: string): Promise<boolean> {
+    const result = await this.db.get(`
+      SELECT 1 FROM citations WHERE citation_id = ?
+    `, [citationId]);
+    return !!result;
+  }
+
+  async getOrCreate(eventId: string): Promise<Citation> {
+    const existing = await this.findByEventId(eventId);
+    if (existing) return existing;
+
+    const citationId = await generateUniqueCitationId(eventId, this);
+    return this.create({ citationId, eventId });
+  }
+}
+```
+
+**작업 항목**:
+- [ ] CitationStore 클래스 구현
+- [ ] CRUD 메서드
+- [ ] getOrCreate 패턴
+
+## Phase 3: 컨텍스트 통합 (P0)
+
+### 3.1 인용 포함 검색
+
+**파일**: `src/core/retriever.ts` 수정
+
+```typescript
+export interface CitedSearchResult {
+  event: Event;
+  citation: Citation;
+  score: number;
+}
+
+export class Retriever {
+  async searchWithCitations(
+    query: string,
+    options?: SearchOptions
+  ): Promise<CitedSearchResult[]> {
+    const results = await this.search(query, options);
+
+    return Promise.all(
+      results.map(async (result) => {
+        const citation = await this.citationStore.getOrCreate(result.eventId);
+        return {
+          event: result,
+          citation,
+          score: result.score
+        };
+      })
+    );
+  }
+}
+```
+
+**작업 항목**:
+- [ ] searchWithCitations 메서드 추가
+- [ ] 인용 자동 생성/조회
+
+### 3.2 컨텍스트 포맷터 수정
+
+**파일**: `src/core/context-formatter.ts` 수정
+
+```typescript
+export function formatContextWithCitations(
+  results: CitedSearchResult[],
+  options?: FormatOptions
+): string {
+  const format = options?.format ?? 'inline';
+
+  switch (format) {
+    case 'inline':
+      return formatInline(results);
+    case 'footnote':
+      return formatFootnote(results);
+    case 'reference':
+      return formatReference(results);
+  }
+}
+
+function formatInline(results: CitedSearchResult[]): string {
+  return results.map(r => {
+    const date = r.event.timestamp.toLocaleDateString();
+    const session = r.event.sessionId.slice(0, 6);
+
+    return [
+      `> ${r.event.payload.content}`,
+      `>`,
+      `> [mem:${r.citation.citationId}] - ${date}, Session ${session}`
+    ].join('\n');
+  }).join('\n\n---\n\n');
+}
+```
+
+**작업 항목**:
+- [ ] 인라인 포맷 구현
+- [ ] 각주 포맷 구현
+- [ ] 참조 포맷 구현
+
+## Phase 4: 조회 인터페이스 (P0)
+
+### 4.1 CLI 명령
+
+**파일**: `src/cli/commands/show.ts` (신규)
+
+```typescript
+import { Command } from 'commander';
+
+export const showCommand = new Command('show')
+  .argument('<citation>', 'Citation ID (e.g., mem:a7Bc3x or just a7Bc3x)')
+  .description('Show full content of a cited memory')
+  .action(async (citation: string) => {
+    const memoryService = await MemoryService.getInstance();
+
+    // mem: 접두사 제거
+    const citationId = citation.replace(/^mem:/, '');
+
+    const result = await memoryService.getCitedMemory(citationId);
+
+    if (!result) {
+      console.log(chalk.red(`Citation not found: ${citationId}`));
+      return;
+    }
+
+    // 출력 포맷팅
+    console.log(chalk.bold(`📄 Memory Citation: ${citationId}`));
+    console.log();
+    console.log(`Session: ${result.event.sessionId}`);
+    console.log(`Date: ${result.event.timestamp.toLocaleString()}`);
+    console.log(`Type: ${result.event.eventType}`);
+    console.log();
+    console.log('Content:');
+    console.log('─'.repeat(40));
+    console.log(result.event.payload.content);
+    console.log('─'.repeat(40));
+
+    if (result.related) {
+      console.log();
+      console.log('Related:');
+      if (result.related.previous) {
+        console.log(`  Previous: [mem:${result.related.previous.citationId}]`);
+      }
+      if (result.related.next) {
+        console.log(`  Next: [mem:${result.related.next.citationId}]`);
+      }
+    }
+  });
+```
+
+**작업 항목**:
+- [ ] show 명령 구현
+- [ ] 출력 포맷팅
+- [ ] 관련 인용 표시
+
+### 4.2 API 엔드포인트
+
+**파일**: `src/server/api/citations.ts` (신규)
+
+```typescript
+import { Hono } from 'hono';
+
+export const citationsRouter = new Hono();
+
+// GET /api/citations/:id
+citationsRouter.get('/:id', async (c) => {
+  const { id } = c.req.param();
+  const memoryService = await MemoryService.getInstance();
+
+  const result = await memoryService.getCitedMemory(id);
+
+  if (!result) {
+    return c.json({ error: 'Citation not found' }, 404);
+  }
+
+  return c.json(result);
+});
+
+// GET /api/citations/:id/related
+citationsRouter.get('/:id/related', async (c) => {
+  const { id } = c.req.param();
+  const memoryService = await MemoryService.getInstance();
+
+  const related = await memoryService.getRelatedCitations(id);
+
+  return c.json({ related });
+});
+```
+
+**작업 항목**:
+- [ ] 인용 조회 API
+- [ ] 관련 인용 API
+- [ ] 에러 처리
+
+## Phase 5: 사용 추적 (P1)
+
+### 5.1 사용 로깅
+
+**파일**: `src/core/citation-store.ts` 수정
+
+```typescript
+export class CitationStore {
+  async logUsage(
+    citationId: string,
+    sessionId: string,
+    context?: string
+  ): Promise<void> {
+    const usageId = crypto.randomUUID();
+
+    await this.db.run(`
+      INSERT INTO citation_usages (usage_id, citation_id, session_id, used_at, context)
+      VALUES (?, ?, ?, ?, ?)
+    `, [usageId, citationId, sessionId, new Date(), context]);
+  }
+
+  async getUsageStats(citationId: string): Promise<CitationStats> {
+    const result = await this.db.get(`
+      SELECT
+        COUNT(*) as usage_count,
+        MAX(used_at) as last_used
+      FROM citation_usages
+      WHERE citation_id = ?
+    `, [citationId]);
+
+    return {
+      usageCount: result.usage_count,
+      lastUsed: result.last_used ? new Date(result.last_used) : null
+    };
+  }
+}
+```
+
+**작업 항목**:
+- [ ] 사용 로깅 구현
+- [ ] 통계 조회
+- [ ] user-prompt-submit 훅에서 로깅
+
+### 5.2 인기 인용 통계
+
+```typescript
+async getPopularCitations(options?: { limit?: number; days?: number }): Promise<PopularCitation[]> {
+  const { limit = 10, days = 30 } = options || {};
+
+  return this.db.query(`
+    SELECT
+      c.citation_id,
+      e.event_type,
+      SUBSTR(JSON_EXTRACT(e.payload_json, '$.content'), 1, 100) as preview,
+      COUNT(u.usage_id) as usage_count,
+      MAX(u.used_at) as last_used
+    FROM citations c
+    JOIN events e ON c.event_id = e.event_id
+    LEFT JOIN citation_usages u ON c.citation_id = u.citation_id
+      AND u.used_at > datetime('now', '-${days} days')
+    GROUP BY c.citation_id
+    ORDER BY usage_count DESC
+    LIMIT ?
+  `, [limit]);
+}
+```
+
+**작업 항목**:
+- [ ] 인기 인용 조회
+- [ ] 기간별 필터링
+- [ ] Stats API에 추가
+
+## 파일 목록
+
+### 신규 파일
+```
+src/core/citation-generator.ts   # ID 생성
+src/core/citation-store.ts       # 인용 저장소
+src/cli/commands/show.ts         # show 명령
+src/server/api/citations.ts      # 인용 API
+```
+
+### 수정 파일
+```
+src/core/types.ts                # 스키마 추가
+src/core/event-store.ts          # 테이블 추가
+src/core/retriever.ts            # 인용 포함 검색
+src/core/context-formatter.ts    # 인용 포맷
+src/hooks/user-prompt-submit.ts  # 사용 로깅
+src/cli/index.ts                 # show 명령 등록
+src/server/api/index.ts          # citations 라우터 추가
+```
+
+## 테스트
+
+### 필수 테스트 케이스
+
+1. **ID 생성**
+   ```typescript
+   test('should generate 6-char citation ID', () => {
+     const id = generateCitationId('event_123');
+     expect(id.length).toBe(6);
+     expect(/^[A-Za-z0-9]+$/.test(id)).toBe(true);
+   });
+   ```
+
+2. **충돌 처리**
+   ```typescript
+   test('should handle ID collision', async () => {
+     // 첫 번째 이벤트 저장
+     await store.create({ citationId: 'abc123', eventId: 'event_1' });
+
+     // 충돌 시 다른 ID 생성
+     const id = await generateUniqueCitationId('event_2', store);
+     expect(id).not.toBe('abc123');
+   });
+   ```
+
+3. **컨텍스트 포맷**
+   ```typescript
+   test('should format context with citations', () => {
+     const formatted = formatContextWithCitations([{
+       event: mockEvent,
+       citation: { citationId: 'a7Bc3x', ... },
+       score: 0.9
+     }]);
+
+     expect(formatted).toContain('[mem:a7Bc3x]');
+   });
+   ```
+
+## 마일스톤
+
+| 단계 | 완료 기준 |
+|------|----------|
+| M1 | 스키마 및 테이블 생성 |
+| M2 | ID 생성기 구현 |
+| M3 | CitationStore 구현 |
+| M4 | 검색에 인용 통합 |
+| M5 | CLI show 명령 |
+| M6 | API 엔드포인트 |
+| M7 | 사용 추적 |
+| M8 | 테스트 통과 |
+
+## 2026-02-25T12:31:26.235Z | 291960d8-18b8-42ca-b47d-8e822fb68b05
+- type: session_summary
+- session: import:organized
+# 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억 조합)