memento-mcp-server 0.1.0

package/.cursor/rules/mcp-tools-architecture.mdc

@@ -0,0 +1,205 @@
+---
+globs: *.ts,*.js
+description: MCP 도구 아키텍처 분리 가이드라인
+---
+
+# MCP 도구 아키텍처 분리 가이드라인
+
+## 🎯 아키텍처 원칙
+
+### 핵심 분리 원칙
+- **MCP 클라이언트**: AI Agent가 직접 사용하는 핵심 기능만 노출
+- **HTTP 관리 API**: 시스템 관리자용 기능은 별도 엔드포인트로 분리
+- **보안성**: 관리 기능이 클라이언트에 노출되지 않음
+- **단순성**: AI Agent는 핵심 기능에만 집중
+
+## 🛠️ MCP 클라이언트 도구 (5개만)
+
+### 핵심 메모리 관리
+```typescript
+// 1. remember - 기억 저장
+{
+  name: "remember",
+  description: "기억을 저장합니다",
+  inputSchema: {
+    content: { type: "string", required: true },
+    type: { type: "string", enum: ["working", "episodic", "semantic", "procedural"] },
+    tags: { type: "array", items: { type: "string" } },
+    importance: { type: "number", minimum: 0, maximum: 1 },
+    source: { type: "string" },
+    privacy_scope: { type: "string", enum: ["private", "team", "public"] }
+  }
+}
+
+// 2. recall - 기억 검색
+{
+  name: "recall",
+  description: "기억을 검색합니다",
+  inputSchema: {
+    query: { type: "string", required: true },
+    filters: { type: "object" },
+    limit: { type: "number", minimum: 1, maximum: 50 }
+  }
+}
+
+// 3. pin - 기억 고정
+{
+  name: "pin",
+  description: "기억을 고정합니다",
+  inputSchema: {
+    id: { type: "string", required: true }
+  }
+}
+
+// 4. unpin - 기억 고정 해제
+{
+  name: "unpin",
+  description: "기억 고정을 해제합니다",
+  inputSchema: {
+    id: { type: "string", required: true }
+  }
+}
+
+// 5. forget - 기억 삭제
+{
+  name: "forget",
+  description: "기억을 삭제합니다",
+  inputSchema: {
+    id: { type: "string", required: true },
+    hard: { type: "boolean", default: false }
+  }
+}
+```
+
+## 🌐 HTTP 관리 API 엔드포인트
+
+### 메모리 관리
+```typescript
+// 메모리 정리
+POST /admin/memory/cleanup
+Response: { message: "메모리 정리 완료" }
+
+// 망각 통계
+GET /admin/stats/forgetting
+Response: { message: "망각 통계 조회 완료" }
+```
+
+### 성능 모니터링
+```typescript
+// 성능 통계
+GET /admin/stats/performance
+Response: { message: "성능 통계 조회 완료" }
+
+// 성능 알림
+GET /admin/alerts/performance
+Response: { message: "성능 알림 조회 완료" }
+```
+
+### 에러 관리
+```typescript
+// 에러 통계
+GET /admin/stats/errors
+Response: { message: "에러 통계 조회 완료" }
+
+// 에러 해결
+POST /admin/errors/resolve
+Body: { errorId: string, resolvedBy: string, reason?: string }
+Response: { message: "에러 해결 완료" }
+```
+
+### 데이터베이스 관리
+```typescript
+// 데이터베이스 최적화
+POST /admin/database/optimize
+Response: { message: "데이터베이스 최적화 완료" }
+```
+
+## 🔧 구현 가이드라인
+
+### MCP 서버 구현
+```typescript
+// src/tools/index.ts
+const coreTools = [
+  new RememberTool(),
+  new RecallTool(),
+  new ForgetTool(),
+  new PinTool(),
+  new UnpinTool(),
+];
+
+// 핵심 도구들만 등록
+toolRegistry.registerAll(coreTools.map(tool => tool.getDefinition()));
+```
+
+### HTTP 서버 구현
+```typescript
+// src/server/http-server.ts
+// 관리자 API 엔드포인트들
+app.post('/admin/memory/cleanup', async (req, res) => {
+  // 메모리 정리 로직
+});
+
+app.get('/admin/stats/performance', async (req, res) => {
+  // 성능 통계 로직
+});
+```
+
+## 📋 도구 분류 기준
+
+### MCP 클라이언트 도구 (포함)
+- ✅ AI Agent가 직접 사용하는 기능
+- ✅ 기억의 CRUD 작업
+- ✅ 사용자 인터랙션과 직접 관련
+- ✅ 실시간으로 자주 호출되는 기능
+
+### HTTP 관리 API (제외)
+- ❌ 시스템 관리자용 기능
+- ❌ 성능 모니터링 및 통계
+- ❌ 에러 로깅 및 디버깅
+- ❌ 데이터베이스 최적화
+- ❌ 배치 작업 및 유지보수
+
+## 🚀 마이그레이션 가이드
+
+### 기존 코드에서 제거할 도구들
+```typescript
+// 제거된 관리 도구들
+- cleanup_memory
+- forgetting_stats
+- performance_stats
+- database_optimize
+- error_stats
+- resolve_error
+- performance_alerts
+```
+
+### 새로운 HTTP API 사용법
+```typescript
+// 기존 MCP 도구 대신 HTTP API 사용
+const response = await fetch('/admin/stats/performance');
+const stats = await response.json();
+```
+
+## 🔒 보안 고려사항
+
+### MCP 클라이언트 보안
+- 핵심 기능만 노출하여 공격 표면 최소화
+- AI Agent가 불필요한 시스템 접근 불가
+- 민감한 관리 기능 격리
+
+### HTTP 관리 API 보안
+- 별도 인증 메커니즘 필요 (향후)
+- 관리자 권한 검증
+- 로그 및 감사 추적
+
+## 📊 성능 최적화
+
+### MCP 클라이언트 최적화
+- 도구 수 감소로 응답 시간 단축
+- 메모리 사용량 감소
+- 네트워크 오버헤드 감소
+
+### HTTP 관리 API 최적화
+- 별도 스레드에서 처리
+- 캐싱 전략 적용
+- 비동기 처리로 메인 서비스 영향 최소화

package/.cursor/rules/memento-memory-rule.mdc

@@ -0,0 +1,8 @@
+---
+description: 
+globs: 
+alwaysApply: true
+---
+해야 하는 일과 처리해낸 일에 대한 정보를 memento를 이용하여 기억으로 저장해야 합니다.
+
+답변을 제공하거나 작업을 진행하기 전에 저장되어있는 관련 기억이 있는지 확인해보고 참고해야 합니다.

package/.cursor/rules/memory-algorithms.mdc

@@ -0,0 +1,502 @@
+---
+globs: *.ts,*.js
+description: 기억 알고리즘 및 검색 랭킹 수식 구현 규칙
+---
+
+# 기억 알고리즘 및 검색 랭킹 수식 규칙
+
+## 📊 검색 랭킹 공식 구현
+
+### 최종 점수 계산
+```typescript
+interface SearchScore {
+  relevance: number;
+  recency: number;
+  importance: number;
+  usage: number;
+  duplication_penalty: number;
+  final_score: number;
+}
+
+class SearchRanking {
+  // 기본 계수 (M1 추천값)
+  private readonly ALPHA = 0.50;  // relevance
+  private readonly BETA = 0.20;   // recency
+  private readonly GAMMA = 0.20;  // importance
+  private readonly DELTA = 0.10;  // usage
+  private readonly EPSILON = 0.15; // duplication_penalty
+
+  calculateFinalScore(score: Omit<SearchScore, 'final_score'>): number {
+    return this.ALPHA * score.relevance +
+           this.BETA * score.recency +
+           this.GAMMA * score.importance +
+           this.DELTA * score.usage -
+           this.EPSILON * score.duplication_penalty;
+  }
+}
+```
+
+### 관련성(relevance) 계산
+```typescript
+class RelevanceCalculator {
+  // 관련성 가중치 (M1 추천값)
+  private readonly WEIGHT_EMBEDDING = 0.60;
+  private readonly WEIGHT_KEYWORD = 0.30;
+  private readonly WEIGHT_TAG = 0.05;
+  private readonly WEIGHT_TITLE = 0.05;
+
+  calculateRelevance(
+    embeddingSimilarity: number,
+    bm25Score: number,
+    tagMatch: number,
+    titleHit: number
+  ): number {
+    return this.WEIGHT_EMBEDDING * embeddingSimilarity +
+           this.WEIGHT_KEYWORD * this.normalizeBM25(bm25Score) +
+           this.WEIGHT_TAG * tagMatch +
+           this.WEIGHT_TITLE * titleHit;
+  }
+
+  // BM25 정규화
+  private normalizeBM25(bm25Score: number, kNorm: number = 2.0): number {
+    return bm25Score / (bm25Score + kNorm);
+  }
+
+  // 임베딩 유사도 (코사인)
+  calculateEmbeddingSimilarity(queryEmbedding: number[], docEmbedding: number[]): number {
+    const dotProduct = this.dotProduct(queryEmbedding, docEmbedding);
+    const magnitudeA = this.magnitude(queryEmbedding);
+    const magnitudeB = this.magnitude(docEmbedding);
+    
+    const cosine = dotProduct / (magnitudeA * magnitudeB);
+    return Math.max(0, cosine); // 음수 방지
+  }
+
+  // 태그 매칭 (자카드 유사도)
+  calculateTagMatch(queryTags: string[], docTags: string[]): number {
+    const intersection = new Set(queryTags.filter(tag => docTags.includes(tag)));
+    const union = new Set([...queryTags, ...docTags]);
+    
+    return intersection.size / union.size;
+  }
+
+  // 타이틀 히트
+  calculateTitleHit(query: string, title: string): number {
+    const queryLower = query.toLowerCase();
+    const titleLower = title.toLowerCase();
+    
+    let score = 0;
+    
+    // 정확 매치
+    if (titleLower === queryLower) score += 1.0;
+    // 접두 매치
+    else if (titleLower.startsWith(queryLower)) score += 0.5;
+    // N-gram 매치
+    else if (this.hasNgramMatch(queryLower, titleLower)) score += 0.2;
+    
+    return score;
+  }
+}
+```
+
+### 최근성(recency) 계산
+```typescript
+class RecencyCalculator {
+  // 반감기 설정 (일 단위)
+  private readonly HALF_LIFE = {
+    working: 2,
+    episodic: 30,
+    semantic: 180
+  };
+
+  calculateRecency(createdAt: Date, type: string): number {
+    const ageDays = this.getAgeInDays(createdAt);
+    const halfLife = this.HALF_LIFE[type as keyof typeof this.HALF_LIFE] || 30;
+    
+    return Math.exp(-Math.log(2) * ageDays / halfLife);
+  }
+
+  private getAgeInDays(date: Date): number {
+    const now = new Date();
+    const diffTime = now.getTime() - date.getTime();
+    return diffTime / (1000 * 60 * 60 * 24);
+  }
+}
+```
+
+### 중요도(importance) 계산
+```typescript
+class ImportanceCalculator {
+  calculateImportance(
+    userImportance: number,
+    isPinned: boolean,
+    type: string
+  ): number {
+    const pinnedBoost = isPinned ? 0.20 : 0;
+    const typeBoost = this.getTypeBoost(type);
+    
+    return Math.max(0, Math.min(1, 
+      userImportance + pinnedBoost + typeBoost
+    ));
+  }
+
+  private getTypeBoost(type: string): number {
+    switch (type) {
+      case 'semantic': return 0.10;
+      case 'episodic': return 0.00;
+      case 'working': return -0.05;
+      case 'procedural': return 0.05;
+      default: return 0.00;
+    }
+  }
+}
+```
+
+### 사용성(usage) 계산
+```typescript
+class UsageCalculator {
+  calculateUsage(
+    viewCount: number,
+    citeCount: number,
+    editCount: number,
+    batchMin: number,
+    batchMax: number
+  ): number {
+    const rawUsage = 
+      Math.log(1 + viewCount) +
+      2 * Math.log(1 + citeCount) +
+      0.5 * Math.log(1 + editCount);
+    
+    return this.normalize(rawUsage, batchMin, batchMax);
+  }
+
+  private normalize(value: number, min: number, max: number, epsilon: number = 1e-6): number {
+    return (value - min) / (max - min + epsilon);
+  }
+}
+```
+
+### 중복 패널티(duplication_penalty) 계산
+```typescript
+class DuplicationPenaltyCalculator {
+  calculateDuplicationPenalty(
+    candidateEmbedding: number[],
+    selectedEmbeddings: number[][]
+  ): number {
+    if (selectedEmbeddings.length === 0) return 0;
+    
+    let maxSimilarity = 0;
+    
+    for (const selectedEmbedding of selectedEmbeddings) {
+      const similarity = this.cosineSimilarity(candidateEmbedding, selectedEmbedding);
+      maxSimilarity = Math.max(maxSimilarity, similarity);
+    }
+    
+    return maxSimilarity;
+  }
+
+  private cosineSimilarity(a: number[], b: number[]): number {
+    const dotProduct = this.dotProduct(a, b);
+    const magnitudeA = this.magnitude(a);
+    const magnitudeB = this.magnitude(b);
+    
+    return dotProduct / (magnitudeA * magnitudeB);
+  }
+}
+```
+
+## 🧠 망각 알고리즘 구현
+
+### 망각 점수 계산
+```typescript
+class ForgetScoreCalculator {
+  // 망각 점수 계수 (M1 추천값)
+  private readonly U1 = 0.35; // recency 가중치
+  private readonly U2 = 0.25; // usage 가중치
+  private readonly U3 = 0.20; // duplication 가중치
+  private readonly U4 = 0.15; // importance 가중치
+  private readonly U5 = 0.30; // pinned 가중치
+
+  calculateForgetScore(
+    recency: number,
+    usage: number,
+    dupRatio: number,
+    importance: number,
+    isPinned: boolean
+  ): number {
+    return this.U1 * (1 - recency) +
+           this.U2 * (1 - usage) +
+           this.U3 * dupRatio -
+           this.U4 * importance -
+           this.U5 * (isPinned ? 1 : 0);
+  }
+}
+```
+
+### 망각 정책 적용
+```typescript
+class ForgetPolicy {
+  // TTL 설정 (일 단위)
+  private readonly TTL_SOFT = {
+    working: 2,
+    episodic: 30,
+    semantic: Infinity
+  };
+  
+  private readonly TTL_HARD = {
+    working: 7,
+    episodic: 180,
+    semantic: Infinity
+  };
+
+  // 소프트 삭제 후보 선정
+  isSoftDeleteCandidate(
+    memory: MemoryItem,
+    forgetScore: number
+  ): boolean {
+    const ageDays = this.getAgeInDays(memory.created_at);
+    const ttl = this.TTL_SOFT[memory.type as keyof typeof this.TTL_SOFT];
+    
+    return forgetScore >= 0.6 && 
+           ageDays >= ttl && 
+           !memory.pinned;
+  }
+
+  // 하드 삭제 후보 선정
+  isHardDeleteCandidate(
+    memory: MemoryItem,
+    forgetScore: number
+  ): boolean {
+    const ageDays = this.getAgeInDays(memory.created_at);
+    const ttl = this.TTL_HARD[memory.type as keyof typeof this.TTL_HARD];
+    
+    return forgetScore >= 0.8 && 
+           ageDays >= ttl && 
+           !memory.pinned;
+  }
+}
+```
+
+## 🔄 간격 반복 알고리즘
+
+### 간격 반복 스케줄러
+```typescript
+class SpacedReviewScheduler {
+  // 간격 반복 계수
+  private readonly A1 = 0.6; // importance 가중치
+  private readonly A2 = 0.4; // usage 가중치
+  private readonly A3 = 0.5; // helpful feedback 가중치
+  private readonly A4 = 0.7; // bad feedback 가중치
+
+  calculateNextReviewInterval(
+    currentInterval: number,
+    importance: number,
+    usage: number,
+    helpfulFeedback: number,
+    badFeedback: number
+  ): number {
+    const multiplier = 1 + 
+      this.A1 * importance +
+      this.A2 * usage +
+      this.A3 * helpfulFeedback -
+      this.A4 * badFeedback;
+    
+    return Math.ceil(currentInterval * multiplier);
+  }
+
+  // 리뷰 확률 계산
+  calculateRecallProbability(
+    timeSinceLastReview: number,
+    interval: number
+  ): number {
+    return Math.exp(-timeSinceLastReview / interval);
+  }
+
+  // 리뷰 필요 여부 판단
+  needsReview(
+    timeSinceLastReview: number,
+    interval: number,
+    threshold: number = 0.7
+  ): boolean {
+    const recallProb = this.calculateRecallProbability(timeSinceLastReview, interval);
+    return recallProb <= threshold;
+  }
+}
+```
+
+## 🔍 2단계 검색 파이프라인
+
+### 검색 파이프라인 구현
+```typescript
+class SearchPipeline {
+  constructor(
+    private vectorSearch: VectorSearchService,
+    private textSearch: TextSearchService,
+    private rankingCalculator: SearchRanking
+  ) {}
+
+  async search(
+    query: string,
+    filters: SearchFilters,
+    limit: number = 10
+  ): Promise<SearchResult[]> {
+    // 1. 후보 생성
+    const candidates = await this.generateCandidates(query, filters);
+    
+    // 2. 특징 계산
+    const features = await this.computeFeatures(candidates, query);
+    
+    // 3. 점수 계산
+    const scoredResults = this.calculateScores(candidates, features);
+    
+    // 4. 다양화 (MMR)
+    const diversifiedResults = this.diversifyResults(scoredResults, limit);
+    
+    // 5. 임계값 필터링
+    return this.filterByThreshold(diversifiedResults, 0.35);
+  }
+
+  private async generateCandidates(
+    query: string,
+    filters: SearchFilters
+  ): Promise<MemoryItem[]> {
+    // 벡터 검색 (ANN)
+    const vectorResults = await this.vectorSearch.search(query, 50);
+    
+    // 텍스트 검색 (BM25)
+    const textResults = await this.textSearch.search(query, 50);
+    
+    // 합집합 생성
+    const candidateMap = new Map<string, MemoryItem>();
+    
+    vectorResults.forEach(item => candidateMap.set(item.id, item));
+    textResults.forEach(item => candidateMap.set(item.id, item));
+    
+    return Array.from(candidateMap.values());
+  }
+
+  private async computeFeatures(
+    candidates: MemoryItem[],
+    query: string
+  ): Promise<FeatureVector[]> {
+    // 각 후보에 대해 특징 계산
+    return Promise.all(candidates.map(async (candidate) => {
+      const relevance = await this.calculateRelevance(candidate, query);
+      const recency = this.calculateRecency(candidate.created_at, candidate.type);
+      const importance = this.calculateImportance(candidate);
+      const usage = await this.calculateUsage(candidate.id);
+      
+      return {
+        memory_id: candidate.id,
+        relevance,
+        recency,
+        importance,
+        usage,
+        duplication_penalty: 0 // 초기값
+      };
+    }));
+  }
+}
+```
+
+## 📈 성능 최적화
+
+### 배치 정규화
+```typescript
+class BatchNormalizer {
+  normalizeFeatures(features: FeatureVector[]): FeatureVector[] {
+    const normalized = [...features];
+    
+    // usage 정규화
+    const usageValues = features.map(f => f.usage);
+    const usageMin = Math.min(...usageValues);
+    const usageMax = Math.max(...usageValues);
+    
+    normalized.forEach(feature => {
+      feature.usage = this.normalize(feature.usage, usageMin, usageMax);
+    });
+    
+    return normalized;
+  }
+
+  private normalize(value: number, min: number, max: number): number {
+    return (value - min) / (max - min + 1e-6);
+  }
+}
+```
+
+### MMR 다양화
+```typescript
+class MMRDiversifier {
+  diversify(
+    results: ScoredResult[],
+    limit: number,
+    lambda: number = 0.8
+  ): ScoredResult[] {
+    const selected: ScoredResult[] = [];
+    const remaining = [...results];
+    
+    while (selected.length < limit && remaining.length > 0) {
+      let bestIndex = 0;
+      let bestScore = -Infinity;
+      
+      remaining.forEach((candidate, index) => {
+        const mmrScore = this.calculateMMRScore(
+          candidate,
+          selected,
+          lambda
+        );
+        
+        if (mmrScore > bestScore) {
+          bestScore = mmrScore;
+          bestIndex = index;
+        }
+      });
+      
+      selected.push(remaining[bestIndex]);
+      remaining.splice(bestIndex, 1);
+    }
+    
+    return selected;
+  }
+
+  private calculateMMRScore(
+    candidate: ScoredResult,
+    selected: ScoredResult[],
+    lambda: number
+  ): number {
+    const relevanceScore = candidate.final_score;
+    const maxSimilarity = this.getMaxSimilarity(candidate, selected);
+    
+    return lambda * relevanceScore - (1 - lambda) * maxSimilarity;
+  }
+}
+```
+
+## 🧪 테스트 가이드
+
+### 단위 테스트 예시
+```typescript
+describe('SearchRanking', () => {
+  let ranking: SearchRanking;
+  
+  beforeEach(() => {
+    ranking = new SearchRanking();
+  });
+  
+  it('should calculate final score correctly', () => {
+    const score = {
+      relevance: 0.8,
+      recency: 0.6,
+      importance: 0.7,
+      usage: 0.5,
+      duplication_penalty: 0.2
+    };
+    
+    const result = ranking.calculateFinalScore(score);
+    expect(result).toBeCloseTo(0.8 * 0.5 + 0.6 * 0.2 + 0.7 * 0.2 + 0.5 * 0.1 - 0.2 * 0.15);
+  });
+});
+```
+
+