memento-mcp-server 0.1.0

package/.cursor/rules/cache-management.mdc

@@ -0,0 +1,171 @@
+---
+globs: *.ts,*.js
+description: 캐시 서비스 개발 규칙
+---
+
+# 캐시 관리 서비스 개발 규칙
+
+## 🗄️ 캐시 서비스 아키텍처
+
+### 핵심 컴포넌트
+
+#### 1. Cache Service (`src/services/cache-service.ts` - 352줄)
+- **LRU 캐시 구현**: 최근 사용 항목 우선 유지
+- **TTL 관리**: 시간 기반 캐시 만료
+- **메모리 효율적 관리**: 캐시 크기 제한 및 정리
+- **통계 수집**: 캐시 성능 메트릭 제공
+
+#### 2. 캐시 타입별 관리
+- **검색 결과 캐시**: 검색 성능 향상
+- **임베딩 캐시**: 임베딩 생성 비용 절약
+- **메타데이터 캐시**: 자주 접근하는 데이터
+- **세션 캐시**: 사용자 세션 정보
+
+## 🔧 캐시 구현 가이드라인
+
+### LRU 캐시 구현
+```typescript
+interface LRUCache<T> {
+  maxSize: number;
+  ttl: number;
+  get(key: string): T | null;
+  set(key: string, value: T): void;
+  delete(key: string): boolean;
+  clear(): void;
+  size(): number;
+}
+```
+
+### TTL 관리
+- **검색 결과**: 1시간 (3600초)
+- **임베딩**: 24시간 (86400초)
+- **메타데이터**: 30분 (1800초)
+- **세션**: 2시간 (7200초)
+
+### 캐시 키 전략
+- **검색 결과**: `search:${hash(query)}`
+- **임베딩**: `embedding:${hash(text)}`
+- **메타데이터**: `meta:${type}:${id}`
+- **세션**: `session:${sessionId}`
+
+## 📊 캐시 성능 메트릭
+
+### 주요 지표
+- **캐시 히트율**: 80% 이상 목표
+- **캐시 크기**: 메모리 사용량 제한
+- **평균 응답 시간**: 캐시된 데이터 접근 시간
+- **캐시 정리 빈도**: 만료된 항목 제거 빈도
+
+### 모니터링
+- **실시간 통계**: 현재 캐시 상태
+- **히스토리 추적**: 성능 변화 추이
+- **알림 설정**: 임계값 초과 시 알림
+- **리포트 생성**: 정기적인 성능 리포트
+
+## 🚀 캐시 최적화 전략
+
+### 메모리 최적화
+1. **크기 제한**: 최대 캐시 크기 설정
+2. **자동 정리**: 만료된 항목 자동 제거
+3. **우선순위**: 중요한 데이터 우선 유지
+4. **압축**: 대용량 데이터 압축 저장
+
+### 성능 최적화
+1. **병렬 처리**: 동시 캐시 접근 처리
+2. **배치 작업**: 대량 캐시 작업 최적화
+3. **지연 로딩**: 필요 시에만 데이터 로드
+4. **예측적 캐싱**: 자주 사용될 데이터 미리 캐싱
+
+### 안정성 보장
+1. **에러 처리**: 캐시 실패 시 대체 방안
+2. **데이터 일관성**: 캐시와 원본 데이터 동기화
+3. **복구 메커니즘**: 캐시 손상 시 자동 복구
+4. **백업 전략**: 중요한 캐시 데이터 백업
+
+## 🔍 캐시 디버깅
+
+### 일반적인 문제
+- **캐시 미스**: 캐시 키 불일치 또는 만료
+- **메모리 누수**: 캐시 크기 제한 초과
+- **성능 저하**: 캐시 히트율 낮음
+- **데이터 불일치**: 캐시와 원본 데이터 차이
+
+### 디버깅 도구
+- **캐시 통계**: 현재 캐시 상태 확인
+- **로그 분석**: 캐시 접근 패턴 분석
+- **프로파일링**: 캐시 성능 측정
+- **모니터링**: 실시간 캐시 상태 추적
+
+## 📋 캐시 정책
+
+### 저장 정책
+- **자동 저장**: 자주 접근하는 데이터 자동 캐싱
+- **수동 저장**: 사용자 요청에 의한 캐싱
+- **조건부 저장**: 특정 조건 만족 시 캐싱
+- **우선순위 저장**: 중요한 데이터 우선 캐싱
+
+### 만료 정책
+- **시간 기반**: TTL 만료 시 자동 삭제
+- **크기 기반**: 캐시 크기 초과 시 오래된 항목 삭제
+- **사용 기반**: 사용하지 않는 항목 우선 삭제
+- **수동 삭제**: 사용자 요청에 의한 삭제
+
+### 동기화 정책
+- **즉시 동기화**: 데이터 변경 시 즉시 캐시 업데이트
+- **지연 동기화**: 주기적으로 캐시 동기화
+- **조건부 동기화**: 특정 조건에서만 동기화
+- **수동 동기화**: 사용자 요청에 의한 동기화
+
+## 🧪 캐시 테스트
+
+### 단위 테스트
+- **기본 기능**: 캐시 저장/조회/삭제 테스트
+- **TTL 테스트**: 시간 기반 만료 테스트
+- **크기 제한**: 최대 크기 초과 시 동작 테스트
+- **에러 처리**: 예외 상황 처리 테스트
+
+### 성능 테스트
+- **부하 테스트**: 높은 부하에서의 캐시 성능
+- **동시성 테스트**: 동시 접근 시 안정성
+- **메모리 테스트**: 메모리 사용량 측정
+- **응답 시간**: 캐시 접근 응답 시간 측정
+
+### 통합 테스트
+- **전체 시스템**: 캐시와 다른 컴포넌트 연동 테스트
+- **데이터 일관성**: 캐시와 원본 데이터 일치성 확인
+- **장애 복구**: 캐시 실패 시 대체 방안 테스트
+- **성능 영향**: 캐시 도입 시 전체 성능 영향 측정
+
+## 📈 캐시 모니터링
+
+### 실시간 모니터링
+- **캐시 크기**: 현재 사용 중인 메모리
+- **히트율**: 캐시 성공률
+- **응답 시간**: 캐시 접근 속도
+- **에러율**: 캐시 관련 에러 발생률
+
+### 알림 설정
+- **히트율 저하**: 70% 미만 시 경고
+- **메모리 사용량**: 90% 초과 시 경고
+- **응답 시간**: 100ms 초과 시 경고
+- **에러율**: 5% 초과 시 경고
+
+### 리포트 생성
+- **일일 리포트**: 캐시 성능 요약
+- **주간 리포트**: 성능 트렌드 분석
+- **월간 리포트**: 장기 성능 변화
+- **특별 리포트**: 문제 발생 시 상세 분석
+
+## 🎯 캐시 목표
+
+### 성능 목표
+- **캐시 히트율**: 80% 이상
+- **평균 응답 시간**: 10ms 이하
+- **메모리 사용량**: 100MB 이하
+- **에러율**: 1% 이하
+
+### 가용성 목표
+- **캐시 가용성**: 99.9% 이상
+- **데이터 일관성**: 99.99% 이상
+- **복구 시간**: 5분 이하
+- **데이터 손실**: 0%

package/.cursor/rules/database-schema.mdc

@@ -0,0 +1,344 @@
+---
+globs: *.sql,*.ts
+description: 데이터베이스 스키마 및 마이그레이션 규칙
+---
+
+# 데이터베이스 스키마 규칙
+
+## 📋 M1 (SQLite) 스키마
+
+### 메인 테이블
+```sql
+-- 기억 아이템 테이블
+CREATE TABLE memory_item (
+  id TEXT PRIMARY KEY,
+  type TEXT CHECK (type IN ('working','episodic','semantic','procedural')),
+  content TEXT NOT NULL,
+  importance REAL CHECK (importance >= 0 AND importance <= 1) DEFAULT 0.5,
+  privacy_scope TEXT CHECK (privacy_scope IN ('private','team','public')) DEFAULT 'private',
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  last_accessed TIMESTAMP,
+  pinned BOOLEAN DEFAULT FALSE,
+  source TEXT,
+  agent_id TEXT,
+  user_id TEXT,
+  project_id TEXT,
+  origin_trace TEXT -- JSON 형태
+);
+
+-- 임베딩 테이블
+CREATE TABLE memory_embedding (
+  memory_id TEXT PRIMARY KEY,
+  embedding BLOB, -- 벡터 데이터
+  dim INTEGER NOT NULL,
+  FOREIGN KEY (memory_id) REFERENCES memory_item(id) ON DELETE CASCADE
+);
+
+-- 태그 테이블 (N:N 관계)
+CREATE TABLE memory_tag (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  name TEXT UNIQUE NOT NULL
+);
+
+-- 기억-태그 관계 테이블
+CREATE TABLE memory_item_tag (
+  memory_id TEXT,
+  tag_id INTEGER,
+  PRIMARY KEY (memory_id, tag_id),
+  FOREIGN KEY (memory_id) REFERENCES memory_item(id) ON DELETE CASCADE,
+  FOREIGN KEY (tag_id) REFERENCES memory_tag(id) ON DELETE CASCADE
+);
+
+-- 기억 간 관계 테이블
+CREATE TABLE memory_link (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  source_id TEXT NOT NULL,
+  target_id TEXT NOT NULL,
+  relation_type TEXT CHECK (relation_type IN ('cause_of', 'derived_from', 'duplicates', 'contradicts')),
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  FOREIGN KEY (source_id) REFERENCES memory_item(id) ON DELETE CASCADE,
+  FOREIGN KEY (target_id) REFERENCES memory_item(id) ON DELETE CASCADE
+);
+
+-- 피드백 이벤트 테이블
+CREATE TABLE feedback_event (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  memory_id TEXT NOT NULL,
+  event_type TEXT CHECK (event_type IN ('used', 'edited', 'neglected', 'helpful', 'not_helpful')),
+  score REAL,
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  FOREIGN KEY (memory_id) REFERENCES memory_item(id) ON DELETE CASCADE
+);
+
+-- 작업기억 버퍼 테이블
+CREATE TABLE wm_buffer (
+  session_id TEXT PRIMARY KEY,
+  items TEXT NOT NULL, -- JSON 형태
+  token_budget INTEGER DEFAULT 4000,
+  expires_at TIMESTAMP NOT NULL
+);
+```
+
+### 인덱스 설정
+```sql
+-- FTS5 텍스트 검색 인덱스
+CREATE VIRTUAL TABLE memory_item_fts USING fts5(
+  content,
+  content='memory_item',
+  content_rowid='rowid'
+);
+
+-- VSS 벡터 검색 인덱스 (1536차원)
+CREATE VIRTUAL TABLE memory_item_vss USING vss0(
+  embedding(1536)
+);
+
+-- 일반 인덱스
+CREATE INDEX idx_memory_item_type ON memory_item(type);
+CREATE INDEX idx_memory_item_created_at ON memory_item(created_at);
+CREATE INDEX idx_memory_item_last_accessed ON memory_item(last_accessed);
+CREATE INDEX idx_memory_item_importance ON memory_item(importance);
+CREATE INDEX idx_memory_item_pinned ON memory_item(pinned);
+CREATE INDEX idx_memory_item_user_id ON memory_item(user_id);
+CREATE INDEX idx_memory_item_project_id ON memory_item(project_id);
+```
+
+## 📋 M3+ (PostgreSQL) 스키마
+
+### 메인 테이블
+```sql
+-- 기억 아이템 테이블
+CREATE TABLE memory_item (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  type TEXT CHECK (type IN ('working','episodic','semantic','procedural')),
+  content TEXT NOT NULL,
+  importance REAL CHECK (importance >= 0 AND importance <= 1) DEFAULT 0.5,
+  privacy_scope TEXT CHECK (privacy_scope IN ('private','team','public')) DEFAULT 'private',
+  created_at TIMESTAMPTZ DEFAULT now(),
+  last_accessed TIMESTAMPTZ,
+  pinned BOOLEAN DEFAULT FALSE,
+  source TEXT,
+  agent_id TEXT,
+  user_id TEXT NOT NULL,
+  project_id TEXT,
+  origin_trace JSONB,
+  -- 자동 생성 컬럼
+  content_tsv tsvector GENERATED ALWAYS AS (to_tsvector('english', content)) STORED
+);
+
+-- 임베딩 테이블 (pgvector 사용)
+CREATE TABLE memory_embedding (
+  memory_id UUID PRIMARY KEY,
+  embedding vector(1536), -- pgvector 확장
+  FOREIGN KEY (memory_id) REFERENCES memory_item(id) ON DELETE CASCADE
+);
+
+-- 태그 테이블
+CREATE TABLE memory_tag (
+  id SERIAL PRIMARY KEY,
+  name TEXT UNIQUE NOT NULL
+);
+
+-- 기억-태그 관계 테이블
+CREATE TABLE memory_item_tag (
+  memory_id UUID,
+  tag_id INTEGER,
+  PRIMARY KEY (memory_id, tag_id),
+  FOREIGN KEY (memory_id) REFERENCES memory_item(id) ON DELETE CASCADE,
+  FOREIGN KEY (tag_id) REFERENCES memory_tag(id) ON DELETE CASCADE
+);
+
+-- 기억 간 관계 테이블
+CREATE TABLE memory_link (
+  id SERIAL PRIMARY KEY,
+  source_id UUID NOT NULL,
+  target_id UUID NOT NULL,
+  relation_type TEXT CHECK (relation_type IN ('cause_of', 'derived_from', 'duplicates', 'contradicts')),
+  created_at TIMESTAMPTZ DEFAULT now(),
+  FOREIGN KEY (source_id) REFERENCES memory_item(id) ON DELETE CASCADE,
+  FOREIGN KEY (target_id) REFERENCES memory_item(id) ON DELETE CASCADE
+);
+
+-- 피드백 이벤트 테이블
+CREATE TABLE feedback_event (
+  id SERIAL PRIMARY KEY,
+  memory_id UUID NOT NULL,
+  event_type TEXT CHECK (event_type IN ('used', 'edited', 'neglected', 'helpful', 'not_helpful')),
+  score REAL,
+  created_at TIMESTAMPTZ DEFAULT now(),
+  FOREIGN KEY (memory_id) REFERENCES memory_item(id) ON DELETE CASCADE
+);
+
+-- 작업기억 버퍼 테이블
+CREATE TABLE wm_buffer (
+  session_id TEXT PRIMARY KEY,
+  items JSONB NOT NULL,
+  token_budget INTEGER DEFAULT 4000,
+  expires_at TIMESTAMPTZ NOT NULL
+);
+```
+
+### 인덱스 설정
+```sql
+-- pgvector 인덱스
+CREATE INDEX ON memory_embedding USING ivfflat (embedding vector_cosine_ops) WITH (lists = 100);
+
+-- GIN 인덱스 (tsvector)
+CREATE INDEX ON memory_item USING GIN (content_tsv);
+
+-- 일반 인덱스
+CREATE INDEX idx_memory_item_type ON memory_item(type);
+CREATE INDEX idx_memory_item_created_at ON memory_item(created_at);
+CREATE INDEX idx_memory_item_last_accessed ON memory_item(last_accessed);
+CREATE INDEX idx_memory_item_importance ON memory_item(importance);
+CREATE INDEX idx_memory_item_pinned ON memory_item(pinned);
+CREATE INDEX idx_memory_item_user_id ON memory_item(user_id);
+CREATE INDEX idx_memory_item_project_id ON memory_item(project_id);
+
+-- 복합 인덱스
+CREATE INDEX idx_memory_item_user_type ON memory_item(user_id, type);
+CREATE INDEX idx_memory_item_project_type ON memory_item(project_id, type);
+CREATE INDEX idx_memory_item_created_type ON memory_item(created_at, type);
+```
+
+## 🔄 마이그레이션 가이드
+
+### SQLite → PostgreSQL 마이그레이션
+```typescript
+class DatabaseMigrator {
+  async migrateFromSQLite(sqlitePath: string, postgresUrl: string): Promise<void> {
+    // 1. SQLite에서 데이터 추출
+    const sqliteData = await this.extractSQLiteData(sqlitePath);
+    
+    // 2. PostgreSQL 스키마 생성
+    await this.createPostgreSQLSchema(postgresUrl);
+    
+    // 3. 데이터 변환 및 삽입
+    await this.transformAndInsertData(sqliteData, postgresUrl);
+    
+    // 4. 임베딩 재계산
+    await this.recalculateEmbeddings(postgresUrl);
+  }
+  
+  private async extractSQLiteData(sqlitePath: string): Promise<any> {
+    // SQLite 데이터 추출 로직
+  }
+  
+  private async createPostgreSQLSchema(postgresUrl: string): Promise<void> {
+    // PostgreSQL 스키마 생성 로직
+  }
+  
+  private async transformAndInsertData(data: any, postgresUrl: string): Promise<void> {
+    // 데이터 변환 및 삽입 로직
+  }
+  
+  private async recalculateEmbeddings(postgresUrl: string): Promise<void> {
+    // 임베딩 재계산 로직
+  }
+}
+```
+
+### 마이그레이션 스크립트
+```sql
+-- 1. SQLite 데이터 추출
+.mode csv
+.headers on
+.output memory_items.csv
+SELECT * FROM memory_item;
+
+-- 2. PostgreSQL 데이터 삽입
+\copy memory_item FROM 'memory_items.csv' WITH CSV HEADER;
+
+-- 3. 임베딩 재계산 (Python 스크립트)
+-- python recalculate_embeddings.py
+```
+
+## 🔍 검색 최적화
+
+### SQLite 검색 쿼리
+```sql
+-- FTS5 + VSS 결합 검색
+WITH vector_search AS (
+  SELECT memory_id, similarity
+  FROM memory_item_vss
+  WHERE vss_search(embedding, ?)
+  ORDER BY similarity DESC
+  LIMIT 50
+),
+text_search AS (
+  SELECT rowid, rank
+  FROM memory_item_fts
+  WHERE memory_item_fts MATCH ?
+  ORDER BY rank
+  LIMIT 50
+)
+SELECT mi.*, 
+       COALESCE(vs.similarity, 0) as vector_score,
+       COALESCE(ts.rank, 0) as text_score
+FROM memory_item mi
+LEFT JOIN vector_search vs ON mi.id = vs.memory_id
+LEFT JOIN text_search ts ON mi.rowid = ts.rowid
+WHERE vs.memory_id IS NOT NULL OR ts.rowid IS NOT NULL
+ORDER BY (vector_score + text_score) DESC;
+```
+
+### PostgreSQL 검색 쿼리
+```sql
+-- pgvector + tsvector 결합 검색
+WITH vector_search AS (
+  SELECT id, 1 - (embedding <=> ?) as similarity
+  FROM memory_embedding
+  ORDER BY embedding <=> ?
+  LIMIT 50
+),
+text_search AS (
+  SELECT id, ts_rank(content_tsv, plainto_tsquery('english', ?)) as rank
+  FROM memory_item
+  WHERE content_tsv @@ plainto_tsquery('english', ?)
+  ORDER BY rank DESC
+  LIMIT 50
+)
+SELECT mi.*,
+       COALESCE(vs.similarity, 0) as vector_score,
+       COALESCE(ts.rank, 0) as text_score
+FROM memory_item mi
+LEFT JOIN vector_search vs ON mi.id = vs.id
+LEFT JOIN text_search ts ON mi.id = ts.id
+WHERE vs.id IS NOT NULL OR ts.id IS NOT NULL
+ORDER BY (vector_score + text_score) DESC;
+```
+
+## 🧹 데이터 정리 정책
+
+### 망각 정책 구현
+```sql
+-- 소프트 삭제 후보 선정
+CREATE VIEW forget_candidates AS
+SELECT id, type, created_at, last_accessed, importance, pinned,
+       CASE 
+         WHEN type = 'working' AND created_at < now() - interval '2 days' THEN true
+         WHEN type = 'episodic' AND created_at < now() - interval '90 days' THEN true
+         ELSE false
+       END as should_forget
+FROM memory_item
+WHERE pinned = false
+  AND (type = 'working' OR type = 'episodic');
+
+-- 하드 삭제 실행
+DELETE FROM memory_item 
+WHERE id IN (
+  SELECT id FROM forget_candidates 
+  WHERE should_forget = true
+);
+```
+
+### 백업 및 복원
+```sql
+-- 백업
+pg_dump -h localhost -U username -d memory_db > backup.sql
+
+-- 복원
+psql -h localhost -U username -d memory_db < backup.sql
+```
+
+