claude-memory-layer 1.0.0

package/specs/evidence-aligner-v2/spec.md

@@ -0,0 +1,312 @@
+# Evidence Aligner V2 Specification
+
+> **Version**: 2.0.0
+> **Status**: Draft
+> **Created**: 2026-01-31
+
+## 1. 개요
+
+### 1.1 문제 정의
+
+현재 시스템에서 LLM이 evidence의 spanStart/spanEnd를 직접 계산하는 방식의 문제:
+
+1. **부정확한 오프셋**: LLM이 문자 위치를 정확히 계산하기 어려움
+2. **환각 가능성**: 원문에 없는 내용을 증거로 제시할 수 있음
+3. **검증 불가**: LLM이 준 오프셋이 실제 원문과 일치하는지 확인 어려움
+
+### 1.2 해결 방향
+
+**Quote-only 방식**:
+- LLM은 **quote(인용문)**만 제공
+- Pipeline(EvidenceAligner)이 원문에서 정확한 span 계산
+- 매칭 실패 시 `evidenceAligned=false`로 표시 → Verified 승격 금지
+
+## 2. 핵심 개념
+
+### 2.1 Evidence 흐름
+
+```
+LLM Extractor                    EvidenceAligner               Database
+     │                                  │                          │
+     │  { quote: "JSONB 제거" }         │                          │
+     ├─────────────────────────────────▶│                          │
+     │                                  │  원문에서 검색            │
+     │                                  │  ─────────────           │
+     │                                  │                          │
+     │  { spanStart: 142,               │                          │
+     │    spanEnd: 150,                 │                          │
+     │    confidence: 1.0 }             │                          │
+     │◀─────────────────────────────────┤                          │
+     │                                  │                          │
+     │                                  │  evidence_aligned 이벤트  │
+     │                                  ├─────────────────────────▶│
+```
+
+### 2.2 Extractor 출력 스키마 변경
+
+**기존 (금지)**:
+```json
+{
+  "evidence": [{
+    "messageIndex": 3,
+    "spanStart": 142,
+    "spanEnd": 150
+  }]
+}
+```
+
+**신규 (권장)**:
+```json
+{
+  "evidence": [{
+    "messageIndex": 3,
+    "quote": "content JSONB → JSON"
+  }]
+}
+```
+
+### 2.3 정렬 알고리즘
+
+```typescript
+interface AlignmentStep {
+  method: 'exact' | 'normalized' | 'fuzzy';
+  description: string;
+}
+
+const ALIGNMENT_STEPS: AlignmentStep[] = [
+  { method: 'exact', description: '정확한 substring 매칭' },
+  { method: 'normalized', description: '공백/개행 정규화 후 매칭' },
+  { method: 'fuzzy', description: 'Levenshtein 거리 기반 유사 매칭 (threshold: 0.85)' }
+];
+```
+
+## 3. 입출력 스키마
+
+### 3.1 입력
+
+```typescript
+interface AlignInput {
+  sessionMessages: string[];      // 원문 메시지 배열
+  extractedJson: ExtractedData;   // LLM 추출 결과
+}
+
+interface ExtractedEvidence {
+  messageIndex: number;
+  quote: string;                  // 30~200자 권장
+}
+```
+
+### 3.2 출력
+
+```typescript
+interface AlignedEvidence {
+  messageIndex: number;
+  quote: string;
+  quoteHash: string;              // SHA256(quote)
+  spanStart: number;              // 원문 내 시작 위치
+  spanEnd: number;                // 원문 내 끝 위치
+  confidence: number;             // 0.0 ~ 1.0
+  matchMethod: 'exact' | 'normalized' | 'fuzzy' | 'none';
+}
+
+interface AlignResult {
+  evidenceAligned: boolean;       // 모든 evidence가 정렬됨
+  alignedEvidence: AlignedEvidence[];
+  failedQuotes: string[];         // 정렬 실패한 quote 목록
+}
+```
+
+## 4. 정렬 로직 상세
+
+### 4.1 Exact Match
+
+```typescript
+function exactMatch(quote: string, source: string): AlignedSpan | null {
+  const index = source.indexOf(quote);
+  if (index === -1) return null;
+
+  return {
+    spanStart: index,
+    spanEnd: index + quote.length,
+    confidence: 1.0,
+    matchMethod: 'exact'
+  };
+}
+```
+
+### 4.2 Normalized Match
+
+```typescript
+function normalizedMatch(quote: string, source: string): AlignedSpan | null {
+  const normalizedQuote = normalize(quote);
+  const normalizedSource = normalize(source);
+
+  const index = normalizedSource.indexOf(normalizedQuote);
+  if (index === -1) return null;
+
+  // 원본 source에서 실제 위치 역추적 필요
+  const originalSpan = mapToOriginal(source, normalizedSource, index, normalizedQuote.length);
+
+  return {
+    ...originalSpan,
+    confidence: 0.95,
+    matchMethod: 'normalized'
+  };
+}
+
+function normalize(text: string): string {
+  return text
+    .replace(/\s+/g, ' ')     // 연속 공백 → 단일 공백
+    .replace(/\n+/g, ' ')     // 개행 → 공백
+    .trim()
+    .toLowerCase();
+}
+```
+
+### 4.3 Fuzzy Match
+
+```typescript
+function fuzzyMatch(
+  quote: string,
+  source: string,
+  threshold: number = 0.85
+): AlignedSpan | null {
+  const normalizedQuote = normalize(quote);
+  const windowSize = Math.ceil(normalizedQuote.length * 1.2);
+
+  let bestMatch: { start: number; end: number; score: number } | null = null;
+
+  // 슬라이딩 윈도우로 유사도 검사
+  for (let i = 0; i <= source.length - windowSize; i++) {
+    const window = normalize(source.slice(i, i + windowSize));
+    const score = levenshteinSimilarity(normalizedQuote, window);
+
+    if (score >= threshold && (!bestMatch || score > bestMatch.score)) {
+      bestMatch = { start: i, end: i + windowSize, score };
+    }
+  }
+
+  if (!bestMatch) return null;
+
+  return {
+    spanStart: bestMatch.start,
+    spanEnd: bestMatch.end,
+    confidence: bestMatch.score,
+    matchMethod: 'fuzzy'
+  };
+}
+```
+
+## 5. 이벤트 스키마
+
+### 5.1 evidence_aligned 이벤트
+
+```typescript
+interface EvidenceAlignedEvent {
+  event_type: 'evidence_aligned';
+  session_id: string;
+  payload: {
+    source_event_id: string;        // session_ingested event
+    extraction_event_id: string;    // memory_extracted event
+    entry_id: string;
+    aligned_count: number;
+    failed_count: number;
+    evidence: AlignedEvidence[];
+    failed_quotes: string[];
+  };
+}
+```
+
+## 6. Idris2 영감 적용
+
+### 6.1 증거 기반 타입 (Proof-Carrying)
+
+**Idris2 개념**:
+```idris
+-- 타입이 증거를 포함
+data EvidencedFact : Type where
+  MkFact : (claim : String) -> (proof : Span) -> EvidencedFact
+```
+
+**TypeScript 적용**:
+```typescript
+// Discriminated Union으로 증거 유무 구분
+type Evidence =
+  | { aligned: true; span: AlignedSpan }
+  | { aligned: false; failureReason: string };
+
+// 증거가 있는 entry만 Verified로 승격 가능
+type VerifiedEntry = {
+  evidence: Extract<Evidence, { aligned: true }>[];  // 모든 evidence가 aligned
+};
+```
+
+### 6.2 불변식
+
+```typescript
+// Zod로 불변식 검증
+const AlignedEvidenceSchema = z.object({
+  confidence: z.number().min(0).max(1),
+  matchMethod: z.enum(['exact', 'normalized', 'fuzzy']),
+  // fuzzy면 confidence < 1.0
+}).refine(
+  (e) => e.matchMethod !== 'exact' || e.confidence === 1.0,
+  { message: 'Exact match must have confidence 1.0' }
+);
+```
+
+## 7. 승격 정책
+
+### 7.1 Evidence 기반 승격 조건
+
+| Stage | Evidence 요구사항 |
+|-------|------------------|
+| raw → working | 없음 |
+| working → candidate | 없음 |
+| candidate → verified | **evidenceAligned=true** 필수 |
+| verified → certified | 추가 검증 필요 |
+
+### 7.2 실패 처리
+
+```typescript
+async function processEntry(entry: Entry): Promise<void> {
+  const alignResult = await aligner.align(sessionMessages, entry.evidence);
+
+  if (!alignResult.evidenceAligned) {
+    // Verified 승격 금지
+    entry.meta.promotionBlocked = true;
+    entry.meta.promotionBlockReason = 'Evidence alignment failed';
+    entry.meta.failedQuotes = alignResult.failedQuotes;
+  }
+}
+```
+
+## 8. 기존 EvidenceAligner와 차이점
+
+### 8.1 현재 구현 (src/core/evidence-aligner.ts)
+
+```typescript
+// 현재: quote 기반 정렬 지원
+align(claims: string[], sourceContent: string): AlignmentResult {
+  // exact match만 지원
+  const exactSpan = this.findExactMatch(claim, sourceContent);
+}
+```
+
+### 8.2 V2 개선사항
+
+| 항목 | 현재 | V2 |
+|------|-----|-----|
+| 정규화 매칭 | 없음 | 공백/개행 정규화 |
+| Fuzzy 매칭 | 없음 | Levenshtein 기반 (threshold 0.85) |
+| 이벤트 기록 | 없음 | evidence_aligned 이벤트 발행 |
+| 승격 연동 | 없음 | evidenceAligned → Verified 조건 |
+| 메시지 인덱스 | 없음 | messageIndex 기반 정확한 소스 식별 |
+
+## 9. 성공 기준
+
+- [ ] LLM Extractor가 quote만 출력하도록 프롬프트 수정
+- [ ] EvidenceAligner가 3단계 정렬 (exact → normalized → fuzzy) 수행
+- [ ] 정렬 결과가 evidence_aligned 이벤트로 기록됨
+- [ ] evidenceAligned=false인 entry는 Verified 승격 불가
+- [ ] 기존 evidence-aligner.ts와 호환 유지

package/specs/mcp-desktop-integration/context.md

@@ -0,0 +1,278 @@
+# MCP Desktop Integration Context
+
+> **Version**: 1.0.0
+> **Created**: 2026-02-01
+
+## 1. 배경
+
+### 1.1 claude-mem의 접근 방식
+
+claude-mem은 MCP (Model Context Protocol)를 통해 Claude Desktop 통합 제공:
+
+```
+Claude Desktop → MCP Client → claude-mem MCP Server → Memory Storage
+```
+
+**특징**:
+- `mem-search` 도구로 자연어 검색
+- Progressive disclosure 패턴 지원
+- 동일한 메모리 저장소 공유
+
+### 1.2 MCP란?
+
+**Model Context Protocol (MCP)**:
+- Anthropic이 개발한 표준 프로토콜
+- AI 모델과 외부 도구/데이터 연결
+- JSON-RPC 기반 통신
+- stdio 또는 HTTP 전송
+
+### 1.3 현재 code-memory의 상황
+
+현재 Claude Code CLI 전용:
+
+```
+Claude Code CLI → Hooks → Memory Storage
+                    ↓
+              (Desktop 접근 불가)
+```
+
+**문제**:
+1. Claude Desktop에서 메모리 활용 불가
+2. CLI 없이는 검색 불가
+3. 환경 간 메모리 분리
+
+## 2. MCP 프로토콜 이해
+
+### 2.1 핵심 개념
+
+```
+┌─────────────────┐       ┌─────────────────┐
+│   MCP Client    │◀─────▶│   MCP Server    │
+│ (Claude Desktop)│ JSON  │ (code-memory)   │
+└─────────────────┘  RPC  └─────────────────┘
+```
+
+**Client**: Claude Desktop, Claude.ai
+**Server**: 도구/데이터 제공자
+**Transport**: stdio (로컬), HTTP (원격)
+
+### 2.2 메시지 형식
+
+```typescript
+// 요청
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "tools/call",
+  "params": {
+    "name": "mem-search",
+    "arguments": { "query": "..." }
+  }
+}
+
+// 응답
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "result": {
+    "content": [{ "type": "text", "text": "..." }]
+  }
+}
+```
+
+### 2.3 도구 정의
+
+```typescript
+interface Tool {
+  name: string;           // 도구 이름
+  description: string;    // Claude에게 보여질 설명
+  inputSchema: JSONSchema; // 입력 스키마
+}
+```
+
+## 3. 기존 코드와의 관계
+
+### 3.1 MemoryService 재사용
+
+MCP 서버는 동일한 MemoryService 사용:
+
+```typescript
+// CLI
+const service = await MemoryService.getInstance();
+await service.search(query);
+
+// MCP Server
+const service = await MemoryService.getInstance();
+await service.search(query);  // 동일한 코드
+```
+
+### 3.2 Progressive Retriever 재사용
+
+```typescript
+// MCP mem-search → ProgressiveRetriever.smartSearch()
+// MCP mem-timeline → ProgressiveRetriever.getTimeline()
+// MCP mem-details → ProgressiveRetriever.getDetails()
+```
+
+### 3.3 저장소 공유
+
+```
+~/.claude-code/memory/
+├── events.duckdb    ← CLI, MCP 모두 접근
+└── vectors/         ← CLI, MCP 모두 접근
+```
+
+## 4. 설계 결정 사항
+
+### 4.1 패키지 구조
+
+**옵션 1: 단일 패키지**
+```
+code-memory/
+├── src/
+│   ├── cli/
+│   ├── core/
+│   └── mcp/
+```
+
+**옵션 2: 별도 패키지 (선택)**
+```
+code-memory/
+├── packages/
+│   ├── core/       # 공유 로직
+│   ├── cli/        # CLI
+│   └── mcp-server/ # MCP 서버
+```
+
+**선택 이유**:
+- 독립적 버전 관리
+- npm 별도 배포 가능
+- 의존성 분리
+
+### 4.2 전송 방식
+
+**stdio (선택)**:
+- Claude Desktop 기본 지원
+- 로컬 실행, 보안 이점
+- 설정 간단
+
+**HTTP**:
+- 원격 접근 가능
+- 추가 보안 필요
+- 포트 충돌 가능
+
+### 4.3 도구 설계
+
+**Progressive Disclosure 패턴**:
+1. `mem-search`: Layer 1 (인덱스)
+2. `mem-timeline`: Layer 2 (타임라인)
+3. `mem-details`: Layer 3 (상세)
+
+**이유**:
+- 토큰 효율성
+- 단계적 정보 제공
+- 필요한 것만 조회
+
+## 5. Claude Desktop 설정
+
+### 5.1 설정 파일 위치
+
+| OS | 경로 |
+|------|------|
+| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
+| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
+| Linux | `~/.config/claude/claude_desktop_config.json` |
+
+### 5.2 설정 형식
+
+```json
+{
+  "mcpServers": {
+    "server-name": {
+      "command": "실행 명령",
+      "args": ["인자들"],
+      "env": {
+        "환경변수": "값"
+      }
+    }
+  }
+}
+```
+
+### 5.3 자동 설치의 이점
+
+```bash
+$ code-memory mcp install
+```
+
+**수동 설정 시 문제**:
+- JSON 문법 오류 가능
+- 경로 오타
+- 플랫폼별 차이
+
+**자동 설치 이점**:
+- 오류 방지
+- 플랫폼 자동 감지
+- 설정 검증
+
+## 6. 보안 고려사항
+
+### 6.1 로컬 전용
+
+```typescript
+// stdio 전송만 사용 (네트워크 노출 없음)
+const transport = new StdioServerTransport();
+```
+
+### 6.2 경로 제한
+
+```typescript
+// 홈 디렉토리 외부 접근 차단
+const memoryPath = process.env.MEMORY_PATH;
+if (!memoryPath.startsWith(os.homedir())) {
+  throw new Error('Invalid memory path');
+}
+```
+
+### 6.3 Privacy 필터 적용
+
+```typescript
+// MCP 응답에도 privacy 필터 적용
+const filtered = applyPrivacyFilter(content, config.privacy);
+```
+
+## 7. 사용 시나리오
+
+### 7.1 Claude Desktop에서 검색
+
+```
+User: "지난번에 DuckDB 스키마 어떻게 설계했었지?"
+
+Claude: [mem-search 도구 호출]
+        query: "DuckDB 스키마 설계"
+
+        Found 2 relevant memories:
+
+        1. [mem:a7Bc3x] (0.94)
+           DuckDB를 사용하여 이벤트 소싱 패턴을...
+
+        지난번에 이벤트 소싱 패턴으로 설계하셨네요.
+        자세한 내용을 보시려면 말씀해주세요.
+```
+
+### 7.2 상세 조회
+
+```
+User: "첫 번째 결과 자세히 보여줘"
+
+Claude: [mem-details 도구 호출]
+        ids: ["a7Bc3x"]
+
+        [전체 내용 표시]
+```
+
+## 8. 참고 자료
+
+- **MCP 공식 문서**: https://modelcontextprotocol.io/
+- **claude-mem MCP**: Desktop integration via MCP
+- **Anthropic SDK**: @modelcontextprotocol/sdk