claude-memory-layer 1.0.10 → 1.0.12

package/memory/specs/vector-outbox-v2/2026-02-25.md

@@ -0,0 +1,1510 @@
+
+## 2026-02-25T12:31:26.442Z | f506a245-208e-42b1-a52a-016f6ecb94b4
+- type: session_summary
+- session: import:organized
+# Vector Outbox V2 Context
+
+> **Version**: 2.0.0
+> **Created**: 2026-01-31
+
+## 1. 배경
+
+### 1.1 분산 시스템의 정합성 문제
+
+두 개의 서로 다른 저장소(DuckDB, LanceDB)에 데이터를 저장할 때:
+
+```
+Application
+    │
+    ├──▶ DuckDB (entries 저장) ✓
+    │
+    └──▶ LanceDB (벡터 저장) ✗ (실패)
+
+결과: DuckDB에는 있지만 LanceDB에는 없는 불일치 상태
+```
+
+**문제 시나리오**:
+1. Entry가 저장되었지만 임베딩이 실패
+2. 재시작 시 어떤 entry가 임베딩되지 않았는지 알 수 없음
+3. 검색 결과에서 해당 entry가 누락
+
+### 1.2 Transactional Outbox Pattern
+
+마이크로서비스 아키텍처에서 검증된 패턴:
+
+```
+┌─────────────────────────────────────┐
+│ DuckDB Transaction                   │
+│                                      │
+│  1. INSERT INTO entries (...)        │
+│  2. INSERT INTO vector_outbox (...)  │
+│                                      │
+│  COMMIT                              │
+└─────────────────────────────────────┘
+            │
+            │ (비동기)
+            ▼
+┌─────────────────────────────────────┐
+│ Vector Worker                        │
+│                                      │
+│  1. SELECT * FROM vector_outbox      │
+│     WHERE status = 'pending'         │
+│  2. Generate embedding               │
+│  3. Upsert to LanceDB                │
+│  4. UPDATE status = 'done'           │
+└─────────────────────────────────────┘
+```
+
+**장점**:
+- 원자성 보장 (DuckDB 트랜잭션 내)
+- 실패 시 재시도 가능
+- 상태 추적 가능
+
+## 2. Memo.txt 참고 사항
+
+### 2.1 핵심 원칙 (섹션 2.6)
+
+> **6. Vector store 정합성**
+> - DuckDB에 먼저 기록 → outbox → 단일 writer가 LanceDB에 upsert → DuckDB 상태 업데이트
+
+### 2.2 스키마 (섹션 4.4)
+
+```sql
+CREATE TABLE vector_outbox (
+  job_id            VARCHAR PRIMARY KEY,
+  item_kind         VARCHAR NOT NULL,        -- entry|task_title
+  item_id           VARCHAR NOT NULL,
+  embedding_version VARCHAR NOT NULL,
+  status            VARCHAR NOT NULL,        -- pending|done|failed
+  error             VARCHAR,
+  created_at        TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  updated_at        TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  UNIQUE(item_kind, item_id, embedding_version)
+);
+```
+
+### 2.3 Worker 지시 (섹션 8)
+
+**Outbox enqueue**:
+- entry materialized 시: `item_kind='entry'`
+- task_created/task_title_changed 시: `item_kind='task_title'`
+
+**Single writer worker**:
+- pending 배치 처리
+- LanceDB **idempotent upsert**
+- 같은 id는 중복 row가 쌓이지 않게
+
+**reconcile()**:
+- pending 재처리
+- failed는 재시도 정책
+
+## 3. Idris2 영감 적용
+
+### 3.1 상태 머신 타입 안전성
+
+**Idris2 개념**:
+```idris
+-- 상태 전이가 타입 수준에서 정의됨
+data OutboxState = Pending | Processing | Done | Failed
+
+data Transition : OutboxState -> OutboxState -> Type where
+  Claim    : Transition Pending Processing
+  Complete : Transition Processing Done
+  Fail     : Transition Processing Failed
+  Retry    : Transition Failed Pending
+```
+
+**TypeScript 적용**:
+```typescript
+// 유효한 전이만 타입으로 정의
+type ValidTransition =
+  | { from: 'pending'; to: 'processing' }
+  | { from: 'processing'; to: 'done' }
+  | { from: 'processing'; to: 'failed' }
+  | { from: 'failed'; to: 'pending' };
+
+// 런타임 검증
+function assertValidTransition(from: OutboxStatus, to: OutboxStatus): void {
+  const valid: ValidTransition[] = [...];
+  if (!valid.some(t => t.from === from && t.to === to)) {
+    throw new Error(`Invalid transition: ${from} → ${to}`);
+  }
+}
+```
+
+### 3.2 Idempotency 증명
+
+**Idris2 개념**:
+```idris
+-- 같은 입력에 같은 결과
+idempotent : (f : a -> a) -> Type
+idempotent f = (x : a) -> f (f x) = f x
+```
+
+**TypeScript 적용**:
+```typescript
+// UNIQUE 제약으로 idempotency 보장
+const UNIQUE_CONSTRAINT = `
+  UNIQUE(item_kind, item_id, embedding_version)
+`;
+
+// enqueue는 여러 번 호출해도 같은 결과
+async function enqueue(input: EnqueueInput): Promise<EnqueueResult> {
+  await db.run(`
+    INSERT INTO vector_outbox (...)
+    ON CONFLICT (item_kind, item_id, embedding_version)
+    DO NOTHING
+  `, [...]);
+  // 결과는 항상 동일: 하나의 job만 존재
+}
+```
+
+### 3.3 벡터 upsert 증명
+
+```typescript
+// upsert 후 조건: 정확히 하나의 레코드만 존재
+interface UpsertInvariant {
+  // Pre: record with id=X may or may not exist
+  // Post: exactly one record with id=X exists, with latest values
+}
+
+async function upsert(record: VectorRecord): Promise<void> {
+  // Delete existing (if any)
+  await table.delete(`id = '${record.id}'`);
+  // Insert new
+  await table.add([record]);
+  // Invariant: exactly one record with id exists
+}
+```
+
+## 4. 기존 코드와의 관계
+
+### 4.1 현재 vector-worker.ts
+
+```typescript
+// 현재 구현 (src/core/vector-worker.ts)
+export class VectorWorker {
+  private embedder: Embedder;
+  private vectorStore: VectorStore;
+  private db: Database;
+}
+
+export interface OutboxItem {
+  id: string;
+  eventId: string;
+  content: string;
+  status: 'pending' | 'processing' | 'done' | 'failed';
+  retryCount: number;
+  createdAt: Date;
+  errorMessage?: string;
+}
+```
+
+### 4.2 V2 확장 포인트
+
+| 기존 | V2 확장 |
+|-----|---------|
+| eventId 기반 | item_kind + item_id |
+| 단순 status | embedding_version 추가 |
+| 재시도 없음 | reconcile + retry policy |
+| 중복 가능 | UNIQUE + upsert |
+
+### 4.3 현재 types.ts
+
+```typescript
+// 현재 OutboxItem 정의
+export interface OutboxItem {
+  id: string;
+  eventId: string;
+  content: string;
+  status: 'pending' | 'processing' | 'done' | 'failed';
+  retryCount: number;
+  createdAt: Date;
+  errorMessage?: string;
+}
+```
+
+V2에서 OutboxJob으로 확장.
+
+## 5. 설계 결정 사항
+
+### 5.1 왜 embedding_version을 포함하는가?
+
+**시나리오**:
+1. 모델 v1으로 entry A 임베딩
+2. 모델 v2로 업그레이드
+3. entry A를 v2로 재임베딩 필요
+
+**해결**:
+```sql
+-- v1과 v2 job이 별도로 존재 가능
+UNIQUE(item_kind, item_id, embedding_version)
+
+-- v1 job
+(job_1, 'entry', 'e1', 'minilm-v1', 'done')
+
+-- v2 job
+(job_2, 'entry', 'e1', 'minilm-v2', 'pending')
+```
+
+### 5.2 왜 단일 writer인가?
+
+**문제**: 여러 프로세스가 동시에 LanceDB에 쓰면
+- 동일 id에 대해 race condition
+- delete와 add 사이에 다른 write 끼어들 수 있음
+- LanceDB 자체 락 메커니즘 미약
+
+**해결**:
+- 애플리케이션 레벨에서 단일 writer 보장
+- 파일 락 또는 DB 락 사용
+
+### 5.3 왜 delete + add인가?
+
+LanceDB가 true upsert를 지원하지 않기 때문:
+
+```typescript
+// 방법 1: update 시도 (LanceDB 제한적 지원)
+await table.update({ id: 'e1' }, { vector: newVector });  // 불완전
+
+// 방법 2: delete + add (권장)
+await table.delete(`id = 'e1'`);
+await table.add([{ id: 'e1', vector: newVector, ... }]);  // 확실
+```
+
+## 6. Reconcile 전략
+
+### 6.1 Failed Job 재시도
+
+```typescript
+const RETRY_POLICY = {
+  maxRetries: 3,
+  backoffMs: [1000, 5000, 30000]  // 1초, 5초, 30초
+};
+
+async function shouldRetry(job: OutboxJob): Promise<boolean> {
+  return job.retryCount < RETRY_POLICY.maxRetries;
+}
+
+async function reconcileFailed(): Promise<number> {
+  return db.run(`
+    UPDATE vector_outbox
+    SET status = 'pending',
+        retry_count = retry_count + 1,
+        updated_at = CURRENT_TIMESTAMP
+    WHERE status = 'failed'
+      AND retry_count < ?
+  `, [RETRY_POLICY.maxRetries]);
+}
+```
+
+### 6.2 Stuck Job 복구
+
+Processing 상태에서 worker가 죽으면:
+
+```typescript
+const STUCK_THRESHOLD_MS = 5 * 60 * 1000;  // 5분
+
+async function recoverStuck(): Promise<number> {
+  const threshold = new Date(Date.now() - STUCK_THRESHOLD_MS);
+  return db.run(`
+    UPDATE vector_outbox
+    SET status = 'pending',
+        updated_at = CURRENT_TIMESTAMP
+    WHERE status = 'processing'
+      AND updated_at < ?
+  `, [threshold]);
+}
+```
+
+### 6.3 Done Job 정리
+
+저장 공간 관리:
+
+```typescript
+async function cleanupDone(olderThanDays: number = 7): Promise<number> {
+  return db.run(`
+    DELETE FROM vector_outbox
+    WHERE status = 'done'
+      AND updated_at < datetime('now', '-${olderThanDays} days')
+  `);
+}
+```
+
+## 7. 모니터링 및 알림
+
+### 7.1 메트릭
+
+```typescript
+interface OutboxMetrics {
+  pendingCount: number;
+  processingCount: number;
+  doneCount: number;
+  failedCount: number;
+  avgProcessingTimeMs: number;
+  oldestPendingAge: number;  // 가장 오래된 pending job의 나이 (ms)
+}
+```
+
+### 7.2 알림 조건
+
+```typescript
+const ALERT_THRESHOLDS = {
+  failedCount: 10,           // failed가 10개 이상
+  pendingAge: 60 * 60 * 1000 // pending이 1시간 이상 된 경우
+};
+
+async function checkAlerts(): Promise<Alert[]> {
+  const metrics = await getMetrics();
+  const alerts: Alert[] = [];
+
+  if (metrics.failedCount >= ALERT_THRESHOLDS.failedCount) {
+    alerts.push({
+      level: 'warning',
+      message: `${metrics.failedCount} vector jobs failed`
+    });
+  }
+
+  if (metrics.oldestPendingAge >= ALERT_THRESHOLDS.pendingAge) {
+    alerts.push({
+      level: 'warning',
+      message: `Oldest pending job is ${metrics.oldestPendingAge / 1000}s old`
+    });
+  }
+
+  return alerts;
+}
+```
+
+## 8. 에러 처리
+
+### 8.1 임베딩 실패
+
+```typescript
+try {
+  const embedding = await embedder.embed(content);
+} catch (error) {
+  if (error.message.includes('rate limit')) {
+    // 재시도 가능
+    throw new RetryableError('Rate limited', { retryAfterMs: 60000 });
+  } else if (error.message.includes('too long')) {
+    // 영구 실패
+    throw new PermanentError('Content too long for embedding');
+  }
+  throw error;
+}
+```
+
+### 8.2 LanceDB 실패
+
+```typescript
+try {
+  await vectorStore.upsert(record);
+} catch (error) {
+  if (error.message.includes('disk full')) {
+    throw new PermanentError('Disk full');
+  } else if (error.message.includes('connection')) {
+    throw new RetryableError('Connection failed');
+  }
+  throw error;
+}
+```
+
+### 8.3 콘텐츠 없음
+
+```typescript
+const content = await getContent(job.itemKind, job.itemId);
+if (!content) {
+  // Entry가 삭제되었거나 존재하지 않음
+  // Job을 done으로 마크하고 건너뜀
+  await markDone(job.jobId, { skipped: true, reason: 'content_not_found' });
+  return;
+}
+```
+
+## 9. 성능 고려사항
+
+### 9.1 배치 처리
+
+```typescript
+const BATCH_SIZE = 50;
+
+// 한 번에 여러 job claim
+const jobs = await claimJobs(BATCH_SIZE);
+
+// 임베딩도 배치로
+const contents = jobs.map(j => j.content);
+const embeddings = await embedder.embedBatch(contents);
+
+// LanceDB 배치 insert
+await vectorStore.addBatch(jobs.map((j, i) => ({
+  id: j.itemId,
+  vector: embeddings[i],
+  ...
+})));
+```
+
+### 9.2 병렬 처리 (주의)
+
+```typescript
+// 단일 writer 내에서 병렬 처리
+// LanceDB 쓰기는 순차적으로, 임베딩은 병렬로
+
+const jobs = await claimJobs(BATCH_SIZE);
+
+// 임베딩 병렬 생성
+const embeddings = await Promise.all(
+  jobs.map(async (job) => {
+    const content = await getContent(job.itemKind, job.itemId);
+    return embedder.embed(content);
+  })
+);
+
+// LanceDB 순차 쓰기
+for (let i = 0; i < jobs.length; i++) {
+  await vectorStore.upsert({ id: jobs[i].itemId, vector: embeddings[i], ... });
+  await markDone(jobs[i].jobId);
+}
+```
+
+## 10. 참고 자료
+
+- **Memo.txt**: 섹션 8 - Vector Outbox + LanceDB writer 구현 지시
+- **현재 구현**: `src/core/vector-worker.ts`
+- **Transactional Outbox**: 마이크로서비스 패턴
+- **AXIOMMIND**: Principle 6 - 벡터 정합성
+
+## 2026-02-25T12:31:26.450Z | becbd566-a1b0-419c-93f8-7ce2a18f4ffd
+- type: session_summary
+- session: import:organized
+# Vector Outbox V2 Implementation Plan
+
+> **Version**: 2.0.0
+> **Status**: Draft
+> **Created**: 2026-01-31
+
+## Phase 1: 스키마 및 타입 (P0)
+
+### 1.1 타입 정의
+
+**파일**: `src/core/types.ts` 수정
+
+```typescript
+// 추가할 타입들
+export const ItemKindSchema = z.enum(['entry', 'task_title', 'session_summary']);
+export type ItemKind = z.infer<typeof ItemKindSchema>;
+
+export const OutboxStatusSchema = z.enum(['pending', 'processing', 'done', 'failed']);
+export type OutboxStatus = z.infer<typeof OutboxStatusSchema>;
+
+export const OutboxJobSchema = z.object({
+  jobId: z.string(),
+  itemKind: ItemKindSchema,
+  itemId: z.string(),
+  embeddingVersion: z.string(),
+  status: OutboxStatusSchema,
+  retryCount: z.number().int().nonnegative(),
+  error: z.string().optional(),
+  createdAt: z.date(),
+  updatedAt: z.date()
+});
+export type OutboxJob = z.infer<typeof OutboxJobSchema>;
+```
+
+**작업 항목**:
+- [ ] ItemKind 스키마 추가
+- [ ] OutboxStatus 스키마 추가
+- [ ] OutboxJob 스키마 추가
+- [ ] EnqueueResult, ProcessResult 타입 추가
+
+### 1.2 DB 스키마
+
+**파일**: 마이그레이션 스크립트
+
+```sql
+-- 기존 outbox 테이블이 있다면 백업 후 마이그레이션
+-- 신규 vector_outbox 테이블
+
+CREATE TABLE vector_outbox (
+  job_id            VARCHAR PRIMARY KEY,
+  item_kind         VARCHAR NOT NULL,
+  item_id           VARCHAR NOT NULL,
+  embedding_version VARCHAR NOT NULL,
+  status            VARCHAR NOT NULL DEFAULT 'pending',
+  retry_count       INTEGER DEFAULT 0,
+  error             VARCHAR,
+  created_at        TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  updated_at        TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  UNIQUE(item_kind, item_id, embedding_version)
+);
+
+CREATE INDEX idx_outbox_status ON vector_outbox(status);
+CREATE INDEX idx_outbox_created ON vector_outbox(created_at);
+```
+
+**작업 항목**:
+- [ ] vector_outbox 테이블 DDL
+- [ ] 인덱스 생성
+- [ ] UNIQUE 제약 추가
+- [ ] 기존 데이터 마이그레이션 스크립트 (필요시)
+
+## Phase 2: VectorOutbox 클래스 (P0)
+
+### 2.1 Enqueue 구현
+
+**파일**: `src/core/vector-outbox.ts` (신규)
+
+```typescript
+export class VectorOutbox {
+  constructor(private db: Database);
+
+  async enqueue(input: OutboxEnqueueInput): Promise<EnqueueResult> {
+    const jobId = uuidv4();
+
+    try {
+      await this.db.run(`
+        INSERT INTO vector_outbox
+        (job_id, item_kind, item_id, embedding_version, status)
+        VALUES (?, ?, ?, ?, 'pending')
+        ON CONFLICT (item_kind, item_id, embedding_version)
+        DO NOTHING
+      `, [jobId, input.itemKind, input.itemId, input.embeddingVersion]);
+
+      // 삽입 성공 여부 확인
+      const inserted = await this.db.query(`
+        SELECT job_id FROM vector_outbox
+        WHERE item_kind = ? AND item_id = ? AND embedding_version = ?
+      `, [input.itemKind, input.itemId, input.embeddingVersion]);
+
+      const isNew = inserted[0]?.job_id === jobId;
+      return { success: true, jobId: inserted[0].job_id, isNew };
+
+    } catch (error) {
+      return { success: false, error: error.message };
+    }
+  }
+}
+```
+
+**작업 항목**:
+- [ ] enqueue() 메서드 (중복 처리 포함)
+- [ ] enqueueBatch() 배치 메서드
+- [ ] ON CONFLICT DO NOTHING 처리
+
+### 2.2 조회 메서드
+
+```typescript
+async getPendingJobs(limit: number = 100): Promise<OutboxJob[]> {
+  return this.db.query(`
+    SELECT * FROM vector_outbox
+    WHERE status = 'pending'
+    ORDER BY created_at ASC
+    LIMIT ?
+  `, [limit]);
+}
+
+async getJobById(jobId: string): Promise<OutboxJob | null> {
+  const rows = await this.db.query(`
+    SELECT * FROM vector_outbox WHERE job_id = ?
+  `, [jobId]);
+  return rows[0] || null;
+}
+
+async getMetrics(): Promise<OutboxMetrics> {
+  // 상태별 통계 조회
+}
+```
+
+**작업 항목**:
+- [ ] getPendingJobs() 메서드
+- [ ] getJobById() 메서드
+- [ ] getMetrics() 통계 메서드
+
+## Phase 3: VectorWorker V2 (P0)
+
+### 3.1 Worker 기본 구현
+
+**파일**: `src/core/vector-worker.ts` 수정
+
+```typescript
+export class VectorWorkerV2 {
+  constructor(
+    private outbox: VectorOutbox,
+    private embedder: Embedder,
+    private vectorStore: VectorStore,
+    private db: Database
+  );
+
+  // Job claiming with lock
+  async claimJobs(limit: number): Promise<OutboxJob[]> {
+    // 트랜잭션으로 pending → processing 변경
+    return this.db.transaction(async (tx) => {
+      const jobs = await tx.query(`
+        SELECT * FROM vector_outbox
+        WHERE status = 'pending'
+        ORDER BY created_at ASC
+        LIMIT ?
+        FOR UPDATE  -- DuckDB에서 지원 시
+      `, [limit]);
+
+      if (jobs.length === 0) return [];
+
+      const jobIds = jobs.map(j => j.job_id);
+      await tx.run(`
+        UPDATE vector_outbox
+        SET status = 'processing', updated_at = CURRENT_TIMESTAMP
+        WHERE job_id IN (${jobIds.map(() => '?').join(',')})
+      `, jobIds);
+
+      return jobs.map(j => ({ ...j, status: 'processing' as const }));
+    });
+  }
+}
+```
+
+**작업 항목**:
+- [ ] claimJobs() 락 처리
+- [ ] markDone() 메서드
+- [ ] markFailed() 메서드
+
+### 3.2 Process 루프
+
+```typescript
+async processAll(): Promise<ProcessResult> {
+  const result: ProcessResult = {
+    processed: 0,
+    succeeded: 0,
+    failed: 0,
+    errors: []
+  };
+
+  const BATCH_SIZE = 50;
+
+  while (true) {
+    const jobs = await this.claimJobs(BATCH_SIZE);
+    if (jobs.length === 0) break;
+
+    for (const job of jobs) {
+      try {
+        await this.processJob(job);
+        await this.markDone(job.jobId);
+        result.succeeded++;
+      } catch (error) {
+        await this.markFailed(job.jobId, error.message);
+        result.failed++;
+        result.errors.push({ jobId: job.jobId, error: error.message });
+      }
+      result.processed++;
+    }
+  }
+
+  return result;
+}
+
+private async processJob(job: OutboxJob): Promise<void> {
+  // 1. 콘텐츠 조회
+  const content = await this.getContent(job.itemKind, job.itemId);
+  if (!content) {
+    throw new Error(`Content not found: ${job.itemKind}:${job.itemId}`);
+  }
+
+  // 2. 임베딩 생성
+  const embedding = await this.embedder.embed(content);
+
+  // 3. LanceDB upsert
+  await this.vectorStore.upsert({
+    id: `${job.itemKind}:${job.itemId}`,
+    vector: embedding,
+    content,
+    metadata: {
+      itemKind: job.itemKind,
+      embeddingVersion: job.embeddingVersion,
+      indexedAt: new Date().toISOString()
+    }
+  });
+}
+```
+
+**작업 항목**:
+- [ ] processAll() 메인 루프
+- [ ] processJob() 단일 job 처리
+- [ ] getContent() 콘텐츠 조회 (itemKind별)
+
+### 3.3 Reconcile
+
+```typescript
+async reconcileFailed(maxRetries: number = 3): Promise<number> {
+  const result = await this.db.run(`
+    UPDATE vector_outbox
+    SET status = 'pending',
+        retry_count = retry_count + 1,
+        updated_at = CURRENT_TIMESTAMP
+    WHERE status = 'failed'
+      AND retry_count < ?
+  `, [maxRetries]);
+
+  return result.changes;
+}
+
+async recoverStuck(stuckThresholdMs: number = 5 * 60 * 1000): Promise<number> {
+  const threshold = new Date(Date.now() - stuckThresholdMs);
+  const result = await this.db.run(`
+    UPDATE vector_outbox
+    SET status = 'pending',
+        updated_at = CURRENT_TIMESTAMP
+    WHERE status = 'processing'
+      AND updated_at < ?
+  `, [threshold.toISOString()]);
+
+  return result.changes;
+}
+```
+
+**작업 항목**:
+- [ ] reconcileFailed() 재시도 메서드
+- [ ] recoverStuck() stuck 복구 메서드
+- [ ] cleanupDone() 정리 메서드
+
+## Phase 4: VectorStore Upsert (P0)
+
+### 4.1 Upsert 메서드
+
+**파일**: `src/core/vector-store.ts` 수정
+
+```typescript
+// 기존 add() 메서드 외에 upsert() 추가
+async upsert(record: VectorRecord): Promise<void> {
+  const table = await this.getOrCreateTable();
+
+  // 기존 레코드 확인
+  const existing = await table
+    .search([0])  // dummy
+    .filter(`id = '${record.id}'`)
+    .limit(1)
+    .toArray();
+
+  if (existing.length > 0) {
+    // 삭제 후 재삽입 (LanceDB upsert 패턴)
+    await table.delete(`id = '${record.id}'`);
+  }
+
+  await table.add([{
+    id: record.id,
+    vector: record.vector,
+    content: record.content,
+    timestamp: record.timestamp,
+    ...record.metadata
+  }]);
+}
+```
+
+**작업 항목**:
+- [ ] upsert() 메서드 구현
+- [ ] delete + add 패턴 적용
+- [ ] 기존 add()와 구분
+
+### 4.2 테이블 버전 관리
+
+```typescript
+// 임베딩 모델 버전별 테이블
+private getTableName(itemKind: ItemKind, version: string): string {
+  const versionSlug = version.replace(/[^a-z0-9]/gi, '_').toLowerCase();
+  return `${itemKind}_vectors_${versionSlug}`;
+}
+
+async getOrCreateTable(itemKind: ItemKind, version: string): Promise<Table> {
+  const tableName = this.getTableName(itemKind, version);
+
+  try {
+    return await this.db.openTable(tableName);
+  } catch {
+    // 테이블 생성
+    return await this.db.createTable(tableName, [
+      { id: '', vector: [], content: '', timestamp: '' }
+    ]);
+  }
+}
+```
+
+**작업 항목**:
+- [ ] getTableName() 버전별 테이블명
+- [ ] getOrCreateTable() lazy 생성
+
+## Phase 5: 통합 및 트리거 (P0)
+
+### 5.1 Entry 저장 시 자동 enqueue
+
+**파일**: Graduation 또는 Entry 저장 로직
+
+```typescript
+async function materializeEntry(entry: Entry): Promise<void> {
+  // 1. Entry 저장
+  await entryRepo.create(entry);
+
+  // 2. Outbox에 자동 enqueue
+  await outbox.enqueue({
+    itemKind: 'entry',
+    itemId: entry.entry_id,
+    embeddingVersion: config.embedding.version
+  });
+}
+```
+
+**작업 항목**:
+- [ ] Entry 저장 후 outbox.enqueue() 호출
+- [ ] Task 생성 시 task_title enqueue
+- [ ] Session 종료 시 session_summary enqueue
+
+### 5.2 단일 Writer 보장
+
+**파일**: `src/core/worker-lock.ts` (신규)
+
+```typescript
+export class WorkerLock {
+  private lockFile: string;
+
+  constructor(lockPath: string = '/tmp/vector-worker.lock');
+
+  acquire(): boolean {
+    if (fs.existsSync(this.lockFile)) {
+      const pid = parseInt(fs.readFileSync(this.lockFile, 'utf8'));
+      if (this.isProcessRunning(pid)) {
+        return false;  // 다른 worker 실행 중
+      }
+      // stale lock file 제거
+      fs.unlinkSync(this.lockFile);
+    }
+    fs.writeFileSync(this.lockFile, process.pid.toString());
+    return true;
+  }
+
+  release(): void {
+    if (fs.existsSync(this.lockFile)) {
+      fs.unlinkSync(this.lockFile);
+    }
+  }
+}
+```
+
+**작업 항목**:
+- [ ] WorkerLock 클래스
+- [ ] acquire/release 메서드
+- [ ] stale lock 처리
+
+## Phase 6: CLI 및 모니터링 (P1)
+
+### 6.1 CLI 커맨드
+
+**파일**: `src/cli/index.ts` 수정
+
+```typescript
+// 벡터 워커 실행
+program
+  .command('vector-worker')
+  .description('Process pending vector jobs')
+  .option('--once', 'Process once and exit')
+  .option('--reconcile', 'Also reconcile failed jobs')
+  .action(async (options) => {
+    const lock = new WorkerLock();
+    if (!lock.acquire()) {
+      console.log('Another worker is running');
+      process.exit(0);
+    }
+
+    try {
+      if (options.reconcile) {
+        const recovered = await worker.reconcileFailed(3);
+        console.log(`Recovered ${recovered} failed jobs`);
+      }
+
+      const result = await worker.processAll();
+      console.log(`Processed: ${result.processed}, Succeeded: ${result.succeeded}, Failed: ${result.failed}`);
+
+      if (!options.once) {
+        // 주기적 실행
+        setInterval(async () => {
+          await worker.processAll();
+        }, 10000);
+      }
+    } finally {
+      lock.release();
+    }
+  });
+```
+
+**작업 항목**:
+- [ ] `cli vector-worker` 커맨드
+- [ ] `cli vector-status` 통계 조회
+- [ ] `cli vector-reconcile` 수동 복구
+
+### 6.2 상태 조회
+
+```typescript
+program
+  .command('vector-status')
+  .description('Show vector outbox status')
+  .action(async () => {
+    const metrics = await outbox.getMetrics();
+    console.log('Vector Outbox Status:');
+    console.log(`  Pending:    ${metrics.pendingCount}`);
+    console.log(`  Processing: ${metrics.processingCount}`);
+    console.log(`  Done:       ${metrics.doneCount}`);
+    console.log(`  Failed:     ${metrics.failedCount}`);
+    console.log(`  Last sync:  ${metrics.lastProcessedAt || 'Never'}`);
+  });
+```
+
+**작업 항목**:
+- [ ] 상태 조회 커맨드
+- [ ] 테이블 형식 출력
+
+## 파일 목록
+
+### 신규 파일
+```
+src/core/vector-outbox.ts    # Outbox 관리
+src/core/worker-lock.ts      # 단일 worker 락
+```
+
+### 수정 파일
+```
+src/core/types.ts            # 타입 추가
+src/core/vector-worker.ts    # V2 로직 추가
+src/core/vector-store.ts     # upsert 추가
+src/cli/index.ts             # CLI 커맨드 추가
+```
+
+## 테스트
+
+### 필수 테스트 케이스
+
+1. **Idempotent Enqueue**
+   ```typescript
+   await outbox.enqueue({ itemKind: 'entry', itemId: 'e1', embeddingVersion: 'v1' });
+   await outbox.enqueue({ itemKind: 'entry', itemId: 'e1', embeddingVersion: 'v1' });
+   // 두 번째는 isNew: false
+   const count = await db.query('SELECT COUNT(*) FROM vector_outbox');
+   expect(count[0].count).toBe(1);
+   ```
+
+2. **Process All**
+   ```typescript
+   await outbox.enqueue({ itemKind: 'entry', itemId: 'e1', ... });
+   await outbox.enqueue({ itemKind: 'entry', itemId: 'e2', ... });
+   const result = await worker.processAll();
+   expect(result.processed).toBe(2);
+   expect(result.succeeded).toBe(2);
+   ```
+
+3. **Reconcile Failed**
+   ```typescript
+   // 실패한 job 생성
+   await db.run(`
+     INSERT INTO vector_outbox (job_id, item_kind, item_id, embedding_version, status, retry_count)
+     VALUES ('j1', 'entry', 'e1', 'v1', 'failed', 1)
+   `);
+   const recovered = await worker.reconcileFailed(3);
+   expect(recovered).toBe(1);
+   // status가 pending으로 변경됨
+   ```
+
+4. **LanceDB Upsert**
+   ```typescript
+   await vectorStore.upsert({ id: 'e1', vector: [0.1, 0.2], ... });
+   await vectorStore.upsert({ id: 'e1', vector: [0.3, 0.4], ... });
+   // 중복 없이 최신 벡터만 존재
+   const results = await vectorStore.search([0.3, 0.4], 10);
+   expect(results.filter(r => r.id === 'e1').length).toBe(1);
+   ```
+
+5. **Single Writer Lock**
+   ```typescript
+   const lock1 = new WorkerLock();
+   const lock2 = new WorkerLock();
+   expect(lock1.acquire()).toBe(true);
+   expect(lock2.acquire()).toBe(false);
+   lock1.release();
+   expect(lock2.acquire()).toBe(true);
+   ```
+
+## 마일스톤
+
+| 단계 | 완료 기준 |
+|------|----------|
+| M1 | 타입 정의 + vector_outbox 테이블 |
+| M2 | VectorOutbox enqueue/getPending |
+| M3 | VectorWorkerV2 claimJobs/markDone |
+| M4 | VectorStore upsert |
+| M5 | processAll() 전체 루프 |
+| M6 | reconcile + recoverStuck |
+| M7 | CLI 커맨드 |
+| M8 | 테스트 통과 |
+
+## 2026-02-25T12:31:26.457Z | 69fdda54-43d8-4a4f-a869-20ab2f32b2ab
+- type: session_summary
+- session: import:organized
+# Vector Outbox V2 Specification
+
+> **Version**: 2.0.0
+> **Status**: Draft
+> **Created**: 2026-01-31
+
+## 1. 개요
+
+### 1.1 문제 정의
+
+DuckDB와 LanceDB 간 데이터 정합성 문제:
+
+1. **원자성 부재**: DuckDB 쓰기와 LanceDB 쓰기가 별도 트랜잭션
+2. **중복 벡터**: 재처리 시 같은 벡터가 중복 저장될 수 있음
+3. **일관성**: DuckDB에는 있지만 LanceDB에는 없는 상태 발생
+4. **동시성**: 여러 프로세스가 동시에 벡터 저장 시 충돌
+
+### 1.2 해결 방향
+
+**Transactional Outbox Pattern**:
+1. DuckDB에 먼저 기록 (vector_outbox 테이블)
+2. 단일 writer가 outbox를 처리하여 LanceDB에 upsert
+3. 성공 시 outbox 상태 업데이트
+
+## 2. 핵심 개념
+
+### 2.1 Outbox 패턴 흐름
+
+```
+Application                 DuckDB                    LanceDB
+    │                         │                          │
+    │  1. Entry 저장           │                          │
+    ├────────────────────────▶│                          │
+    │                         │                          │
+    │  2. Outbox job 생성      │                          │
+    ├────────────────────────▶│                          │
+    │                         │                          │
+    │  (트랜잭션 커밋)          │                          │
+    │                         │                          │
+                        ┌─────┴─────┐
+                        │  Worker   │
+                        └─────┬─────┘
+                              │                          │
+                              │  3. pending job 조회      │
+                              │◀────────────────────────│
+                              │                          │
+                              │  4. 임베딩 생성           │
+                              │                          │
+                              │  5. LanceDB upsert       │
+                              │─────────────────────────▶│
+                              │                          │
+                              │  6. status='done' 업데이트 │
+                              │────────────────────────▶│
+```
+
+### 2.2 Job 상태 머신
+
+```
+┌─────────┐     Worker 픽업      ┌────────────┐
+│ pending │ ──────────────────▶ │ processing │
+└─────────┘                     └──────┬─────┘
+     │                                 │
+     │ 재시도 (reconcile)              │
+     │                                 │
+     │         ┌───────────────────────┼───────────────────────┐
+     │         │                       │                       │
+     │         ▼                       ▼                       ▼
+     │    ┌─────────┐            ┌──────────┐           ┌─────────┐
+     └───▶│ pending │            │   done   │           │ failed  │
+          └─────────┘            └──────────┘           └─────────┘
+                                                              │
+                                                              │ retry < max
+                                                              ▼
+                                                        ┌─────────┐
+                                                        │ pending │
+                                                        └─────────┘
+```
+
+### 2.3 Item 종류
+
+```typescript
+type ItemKind =
+  | 'entry'           // entries 테이블의 content 임베딩
+  | 'task_title'      // entities 테이블의 task 제목 임베딩
+  | 'session_summary' // 세션 요약 임베딩
+  ;
+```
+
+## 3. DB 스키마
+
+### 3.1 vector_outbox 테이블
+
+```sql
+CREATE TABLE vector_outbox (
+  job_id            VARCHAR PRIMARY KEY,
+  item_kind         VARCHAR NOT NULL,        -- entry|task_title|session_summary
+  item_id           VARCHAR NOT NULL,
+  embedding_version VARCHAR NOT NULL,        -- e.g., 'v1.0.0', 'minilm-v2'
+  status            VARCHAR NOT NULL,        -- pending|processing|done|failed
+  retry_count       INTEGER DEFAULT 0,
+  error             VARCHAR,
+  created_at        TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  updated_at        TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+
+  -- 중복 방지: 같은 아이템+버전은 하나만
+  UNIQUE(item_kind, item_id, embedding_version)
+);
+
+CREATE INDEX idx_outbox_status ON vector_outbox(status);
+CREATE INDEX idx_outbox_created ON vector_outbox(created_at);
+```
+
+### 3.2 vector_store_meta 테이블 (선택)
+
+```sql
+-- LanceDB 테이블 메타데이터 추적
+CREATE TABLE vector_store_meta (
+  table_name        VARCHAR PRIMARY KEY,     -- e.g., 'entry_vectors_v1'
+  embedding_version VARCHAR NOT NULL,
+  item_count        INTEGER DEFAULT 0,
+  last_sync_at      TIMESTAMP,
+  created_at        TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+```
+
+## 4. Outbox API
+
+### 4.1 Enqueue
+
+```typescript
+interface OutboxEnqueueInput {
+  itemKind: ItemKind;
+  itemId: string;
+  embeddingVersion: string;
+}
+
+interface VectorOutbox {
+  // Job 추가 (중복 시 무시)
+  enqueue(input: OutboxEnqueueInput): Promise<EnqueueResult>;
+
+  // 배치 추가
+  enqueueBatch(inputs: OutboxEnqueueInput[]): Promise<EnqueueResult[]>;
+}
+
+type EnqueueResult =
+  | { success: true; jobId: string; isNew: true }
+  | { success: true; jobId: string; isNew: false }  // 이미 존재
+  | { success: false; error: string };
+```
+
+### 4.2 Process (Worker)
+
+```typescript
+interface VectorWorker {
+  // pending job 가져오기 (락)
+  claimJobs(limit: number): Promise<OutboxJob[]>;
+
+  // 처리 완료 표시
+  markDone(jobId: string): Promise<void>;
+
+  // 실패 표시
+  markFailed(jobId: string, error: string): Promise<void>;
+
+  // 전체 처리 루프
+  processAll(): Promise<ProcessResult>;
+}
+
+interface ProcessResult {
+  processed: number;
+  succeeded: number;
+  failed: number;
+  errors: { jobId: string; error: string }[];
+}
+```
+
+### 4.3 Reconcile
+
+```typescript
+interface VectorOutbox {
+  // 재시도 가능한 failed job을 pending으로 변경
+  reconcileFailed(maxRetries: number): Promise<number>;
+
+  // processing 상태로 오래 멈춘 job 복구
+  recoverStuck(stuckThresholdMs: number): Promise<number>;
+
+  // 완료된 job 정리
+  cleanupDone(olderThanDays: number): Promise<number>;
+}
+```
+
+## 5. 단일 Writer 패턴
+
+### 5.1 왜 단일 Writer인가?
+
+**문제**: 여러 프로세스가 동시에 LanceDB에 쓰면
+- 충돌 발생 가능
+- 중복 벡터 생성
+- 트랜잭션 보장 어려움
+
+**해결**: 하나의 worker만 LanceDB에 쓰기
+
+```typescript
+// 단일 writer 보장 방법들
+
+// 방법 1: 프로세스 수준 락
+const lockFile = '/tmp/vector-worker.lock';
+if (fs.existsSync(lockFile)) {
+  console.log('Another worker is running');
+  process.exit(0);
+}
+fs.writeFileSync(lockFile, process.pid.toString());
+
+// 방법 2: DB 수준 락
+await db.run(`
+  INSERT INTO worker_locks (worker_name, locked_at)
+  VALUES ('vector_worker', CURRENT_TIMESTAMP)
+  ON CONFLICT (worker_name)
+  DO UPDATE SET locked_at = CURRENT_TIMESTAMP
+  WHERE locked_at < datetime('now', '-5 minutes')
+`);
+```
+
+### 5.2 Worker 구현
+
+```typescript
+class VectorWorkerImpl implements VectorWorker {
+  private embedder: Embedder;
+  private vectorStore: VectorStore;
+  private db: Database;
+
+  async processAll(): Promise<ProcessResult> {
+    const result: ProcessResult = { processed: 0, succeeded: 0, failed: 0, errors: [] };
+
+    while (true) {
+      const jobs = await this.claimJobs(BATCH_SIZE);
+      if (jobs.length === 0) break;
+
+      for (const job of jobs) {
+        try {
+          await this.processJob(job);
+          await this.markDone(job.jobId);
+          result.succeeded++;
+        } catch (error) {
+          await this.markFailed(job.jobId, error.message);
+          result.failed++;
+          result.errors.push({ jobId: job.jobId, error: error.message });
+        }
+        result.processed++;
+      }
+    }
+
+    return result;
+  }
+
+  private async processJob(job: OutboxJob): Promise<void> {
+    // 1. 원본 콘텐츠 조회
+    const content = await this.getContent(job.itemKind, job.itemId);
+
+    // 2. 임베딩 생성
+    const embedding = await this.embedder.embed(content);
+
+    // 3. LanceDB upsert (idempotent)
+    await this.vectorStore.upsert({
+      id: job.itemId,
+      vector: embedding,
+      metadata: {
+        itemKind: job.itemKind,
+        embeddingVersion: job.embeddingVersion
+      }
+    });
+  }
+}
+```
+
+## 6. LanceDB Upsert 전략
+
+### 6.1 Idempotent Upsert
+
+```typescript
+async function upsertVector(record: VectorRecord): Promise<void> {
+  const table = await this.getTable(record.itemKind, record.embeddingVersion);
+
+  // LanceDB에서 기존 레코드 확인
+  const existing = await table
+    .search([0])  // dummy search for filter
+    .filter(`id = '${record.id}'`)
+    .limit(1)
+    .toArray();
+
+  if (existing.length > 0) {
+    // 업데이트: 삭제 후 재삽입
+    await table.delete(`id = '${record.id}'`);
+  }
+
+  // 삽입
+  await table.add([{
+    id: record.id,
+    vector: record.vector,
+    content: record.content,
+    timestamp: record.timestamp,
+    metadata: record.metadata
+  }]);
+}
+```
+
+### 6.2 테이블 버전 관리
+
+```typescript
+// 임베딩 모델 버전별 테이블 분리
+function getTableName(itemKind: ItemKind, embeddingVersion: string): string {
+  // entry_vectors_minilm_v2
+  // task_title_vectors_minilm_v2
+  const versionSlug = embeddingVersion.replace(/[^a-z0-9]/gi, '_');
+  return `${itemKind}_vectors_${versionSlug}`;
+}
+```
+
+## 7. Idris2 영감 적용
+
+### 7.1 상태 전이 타입 안전성
+
+```typescript
+// 타입 레벨에서 유효한 상태 전이만 허용
+type ValidTransition =
+  | { from: 'pending'; to: 'processing' }
+  | { from: 'processing'; to: 'done' }
+  | { from: 'processing'; to: 'failed' }
+  | { from: 'failed'; to: 'pending' };  // retry
+
+function transition(job: OutboxJob, to: OutboxStatus): OutboxJob {
+  const valid: ValidTransition[] = [
+    { from: 'pending', to: 'processing' },
+    { from: 'processing', to: 'done' },
+    { from: 'processing', to: 'failed' },
+    { from: 'failed', to: 'pending' }
+  ];
+
+  const isValid = valid.some(t => t.from === job.status && t.to === to);
+  if (!isValid) {
+    throw new InvalidTransitionError(`Cannot transition from ${job.status} to ${to}`);
+  }
+
+  return { ...job, status: to, updatedAt: new Date() };
+}
+```
+
+### 7.2 Idempotency 불변식
+
+```typescript
+// Zod로 idempotency 검증
+const OutboxJobSchema = z.object({
+  itemKind: ItemKindSchema,
+  itemId: z.string(),
+  embeddingVersion: z.string()
+}).refine(
+  async (job) => {
+    // 같은 조합은 하나만 존재해야 함
+    const existing = await db.query(`
+      SELECT COUNT(*) as cnt FROM vector_outbox
+      WHERE item_kind = ? AND item_id = ? AND embedding_version = ?
+    `, [job.itemKind, job.itemId, job.embeddingVersion]);
+    return existing[0].cnt <= 1;
+  },
+  { message: 'Duplicate outbox job' }
+);
+```
+
+## 8. 기존 코드와의 관계
+
+### 8.1 현재 vector-worker.ts
+
+```typescript
+// 현재 구현 (src/core/vector-worker.ts)
+export class VectorWorker {
+  // OutboxItem 타입 사용
+  // status: 'pending' | 'processing' | 'done' | 'failed'
+}
+```
+
+### 8.2 V2 확장 포인트
+
+| 기존 | V2 확장 |
+|-----|---------|
+| OutboxItem 타입 | itemKind, embeddingVersion 추가 |
+| 단순 배치 처리 | claiming with lock |
+| 재시도 없음 | reconcile + retry policy |
+| 중복 가능 | UNIQUE 제약 + upsert |
+
+### 8.3 현재 vector-store.ts
+
+```typescript
+// 현재 구현 (src/core/vector-store.ts)
+export class VectorStore {
+  async add(record: VectorRecord): Promise<void>;
+  async search(query: number[], limit: number): Promise<SearchResult[]>;
+}
+```
+
+V2에서 `upsert` 메서드 추가 필요.
+
+## 9. 운영 고려사항
+
+### 9.1 모니터링
+
+```typescript
+// 메트릭 수집
+interface OutboxMetrics {
+  pendingCount: number;
+  processingCount: number;
+  failedCount: number;
+  doneCount: number;
+  avgProcessingTimeMs: number;
+  lastProcessedAt: Date | null;
+}
+
+async function getMetrics(): Promise<OutboxMetrics> {
+  return db.query(`
+    SELECT
+      SUM(CASE WHEN status = 'pending' THEN 1 ELSE 0 END) as pendingCount,
+      SUM(CASE WHEN status = 'processing' THEN 1 ELSE 0 END) as processingCount,
+      SUM(CASE WHEN status = 'failed' THEN 1 ELSE 0 END) as failedCount,
+      SUM(CASE WHEN status = 'done' THEN 1 ELSE 0 END) as doneCount,
+      MAX(updated_at) as lastProcessedAt
+    FROM vector_outbox
+  `);
+}
+```
+
+### 9.2 알림
+
+```typescript
+// failed job이 임계값 초과 시 알림
+const FAILED_THRESHOLD = 10;
+
+async function checkAndAlert(): Promise<void> {
+  const metrics = await getMetrics();
+  if (metrics.failedCount >= FAILED_THRESHOLD) {
+    console.error(`[ALERT] ${metrics.failedCount} failed vector jobs`);
+    // 추가 알림 로직
+  }
+}
+```
+
+### 9.3 정리 작업
+
+```typescript
+// 정기적으로 완료된 job 정리
+async function cleanup(): Promise<void> {
+  const deleted = await db.run(`
+    DELETE FROM vector_outbox
+    WHERE status = 'done'
+      AND updated_at < datetime('now', '-7 days')
+  `);
+  console.log(`Cleaned up ${deleted.changes} done jobs`);
+}
+```
+
+## 10. 성공 기준
+
+- [ ] vector_outbox 테이블 생성 및 UNIQUE 제약
+- [ ] enqueue가 중복을 무시하고 idempotent하게 동작
+- [ ] 단일 worker가 pending job을 처리
+- [ ] LanceDB upsert로 중복 벡터 방지
+- [ ] failed job 재시도 (reconcile) 동작
+- [ ] processing 상태 stuck 복구 동작
+- [ ] 기존 vector-worker.ts와 호환 유지