claude-memory-layer 1.0.11 → 1.0.13

package/memory/specs/mcp-desktop-integration/2026-02-25.md

@@ -0,0 +1,1334 @@
+
+## 2026-02-25T12:31:26.330Z | 5a29de82-7227-4961-ae38-ece8700e43f5
+- type: session_summary
+- session: import:organized
+# 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
+
+## 2026-02-25T12:31:26.337Z | e718c82b-3d4e-4d40-9f17-3f9e41a1c161
+- type: session_summary
+- session: import:organized
+# MCP Desktop Integration Implementation Plan
+
+> **Version**: 1.0.0
+> **Status**: Draft
+> **Created**: 2026-02-01
+
+## Phase 1: MCP 서버 기본 구조 (P0)
+
+### 1.1 프로젝트 설정
+
+**파일**: `packages/mcp-server/package.json` (신규)
+
+```json
+{
+  "name": "code-memory-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for code-memory",
+  "main": "dist/index.js",
+  "bin": {
+    "code-memory-mcp": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "esbuild src/index.ts --bundle --platform=node --outfile=dist/index.js",
+    "dev": "tsx src/index.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "code-memory-core": "workspace:*"
+  }
+}
+```
+
+**작업 항목**:
+- [ ] MCP 서버 패키지 생성
+- [ ] dependencies 설정
+- [ ] 빌드 스크립트 설정
+
+### 1.2 서버 진입점
+
+**파일**: `packages/mcp-server/src/index.ts` (신규)
+
+```typescript
+#!/usr/bin/env node
+import { Server } from '@modelcontextprotocol/sdk/server';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio';
+import {
+  ListToolsRequestSchema,
+  CallToolRequestSchema
+} from '@modelcontextprotocol/sdk/types';
+
+import { tools } from './tools';
+import { handleToolCall } from './handlers';
+
+const server = new Server(
+  {
+    name: 'code-memory-mcp',
+    version: '1.0.0'
+  },
+  {
+    capabilities: {
+      tools: {}
+    }
+  }
+);
+
+// 도구 목록 핸들러
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return { tools };
+});
+
+// 도구 호출 핸들러
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+  return handleToolCall(name, args || {});
+});
+
+// stdio 연결 및 시작
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error('code-memory MCP server started');
+}
+
+main().catch(console.error);
+```
+
+**작업 항목**:
+- [ ] 서버 초기화
+- [ ] 핸들러 등록
+- [ ] stdio 연결
+
+### 1.3 도구 정의
+
+**파일**: `packages/mcp-server/src/tools.ts` (신규)
+
+```typescript
+import { Tool } from '@modelcontextprotocol/sdk/types';
+
+export const tools: Tool[] = [
+  {
+    name: 'mem-search',
+    description: 'Search code-memory for relevant past conversations and insights. Returns a compact index of results - use mem-details to get full content.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        query: {
+          type: 'string',
+          description: 'Natural language search query'
+        },
+        topK: {
+          type: 'number',
+          description: 'Maximum number of results (default: 5, max: 20)'
+        },
+        sessionId: {
+          type: 'string',
+          description: 'Optional: filter by specific session ID'
+        },
+        eventType: {
+          type: 'string',
+          enum: ['prompt', 'response', 'tool', 'insight'],
+          description: 'Optional: filter by event type'
+        }
+      },
+      required: ['query']
+    }
+  },
+  {
+    name: 'mem-timeline',
+    description: 'Get chronological context around specific memories. Useful for understanding the conversation flow.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        ids: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Memory IDs (from mem-search) to get timeline for'
+        },
+        windowSize: {
+          type: 'number',
+          description: 'Number of items before/after each ID (default: 3)'
+        }
+      },
+      required: ['ids']
+    }
+  },
+  {
+    name: 'mem-details',
+    description: 'Get full content of specific memories. Use after mem-search to get complete information.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        ids: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Memory IDs to fetch full details for'
+        }
+      },
+      required: ['ids']
+    }
+  },
+  {
+    name: 'mem-stats',
+    description: 'Get statistics about the memory storage (total events, sessions, etc.)',
+    inputSchema: {
+      type: 'object',
+      properties: {}
+    }
+  }
+];
+```
+
+**작업 항목**:
+- [ ] mem-search 도구 정의
+- [ ] mem-timeline 도구 정의
+- [ ] mem-details 도구 정의
+- [ ] mem-stats 도구 정의
+
+## Phase 2: 핸들러 구현 (P0)
+
+### 2.1 도구 핸들러
+
+**파일**: `packages/mcp-server/src/handlers.ts` (신규)
+
+```typescript
+import { ToolResult } from '@modelcontextprotocol/sdk/types';
+import { MemoryService } from 'code-memory-core';
+import { formatSearchResults, formatTimeline, formatDetails, formatStats } from './formatters';
+
+let memoryService: MemoryService | null = null;
+
+async function getMemoryService(): Promise<MemoryService> {
+  if (!memoryService) {
+    memoryService = await MemoryService.getInstance({
+      storagePath: process.env.MEMORY_PATH || '~/.claude-code/memory'
+    });
+  }
+  return memoryService;
+}
+
+export async function handleToolCall(
+  name: string,
+  args: Record<string, unknown>
+): Promise<ToolResult> {
+  try {
+    const service = await getMemoryService();
+
+    switch (name) {
+      case 'mem-search':
+        return await handleMemSearch(service, args);
+
+      case 'mem-timeline':
+        return await handleMemTimeline(service, args);
+
+      case 'mem-details':
+        return await handleMemDetails(service, args);
+
+      case 'mem-stats':
+        return await handleMemStats(service);
+
+      default:
+        return {
+          content: [{ type: 'text', text: `Unknown tool: ${name}` }],
+          isError: true
+        };
+    }
+  } catch (error) {
+    return {
+      content: [{ type: 'text', text: `Error: ${(error as Error).message}` }],
+      isError: true
+    };
+  }
+}
+
+async function handleMemSearch(
+  service: MemoryService,
+  args: Record<string, unknown>
+): Promise<ToolResult> {
+  const query = args.query as string;
+  const topK = Math.min((args.topK as number) || 5, 20);
+
+  const results = await service.progressiveSearch(query, {
+    topK,
+    filter: {
+      sessionId: args.sessionId as string,
+      eventType: args.eventType as string
+    }
+  });
+
+  return {
+    content: [{
+      type: 'text',
+      text: formatSearchResults(results)
+    }]
+  };
+}
+
+// 다른 핸들러들도 유사하게 구현
+```
+
+**작업 항목**:
+- [ ] handleMemSearch 구현
+- [ ] handleMemTimeline 구현
+- [ ] handleMemDetails 구현
+- [ ] handleMemStats 구현
+- [ ] 에러 처리
+
+### 2.2 포맷터
+
+**파일**: `packages/mcp-server/src/formatters.ts` (신규)
+
+```typescript
+import { ProgressiveSearchResult, TimelineItem, FullDetail, Stats } from 'code-memory-core';
+
+export function formatSearchResults(results: ProgressiveSearchResult): string {
+  const lines: string[] = [
+    '## Memory Search Results',
+    '',
+    `Found ${results.index.length} relevant memories:`,
+    ''
+  ];
+
+  for (let i = 0; i < results.index.length; i++) {
+    const item = results.index[i];
+    const score = item.score.toFixed(2);
+    const date = new Date(item.timestamp).toLocaleDateString();
+
+    lines.push(`### ${i + 1}. [mem:${item.id}] (${score})`);
+    lines.push(`**Session**: ${item.sessionId.slice(0, 8)} | **Date**: ${date}`);
+    lines.push(`> ${item.summary}`);
+    lines.push('');
+  }
+
+  lines.push('---');
+  lines.push('*Use `mem-details` with IDs for full content.*');
+  lines.push('*Use `mem-timeline` for context around these memories.*');
+
+  return lines.join('\n');
+}
+
+export function formatTimeline(items: TimelineItem[]): string {
+  const lines: string[] = [
+    '## Timeline Context',
+    '',
+    '| Time | Type | Preview |',
+    '|------|------|---------|'
+  ];
+
+  for (const item of items) {
+    const time = new Date(item.timestamp).toLocaleTimeString();
+    const marker = item.isTarget ? '**' : '';
+    const preview = item.preview.slice(0, 50) + (item.preview.length > 50 ? '...' : '');
+
+    lines.push(`| ${marker}${time}${marker} | ${item.type} | ${marker}${preview}${marker} |`);
+  }
+
+  return lines.join('\n');
+}
+
+export function formatDetails(details: FullDetail[]): string {
+  return details.map(detail => {
+    const date = new Date(detail.timestamp).toLocaleString();
+
+    return [
+      `## Memory Details: [mem:${detail.id}]`,
+      '',
+      `**Session**: ${detail.sessionId}`,
+      `**Date**: ${date}`,
+      `**Type**: ${detail.type}`,
+      '',
+      '**Content**:',
+      '```',
+      detail.content,
+      '```',
+      ''
+    ].join('\n');
+  }).join('\n---\n\n');
+}
+
+export function formatStats(stats: Stats): string {
+  return [
+    '## Memory Statistics',
+    '',
+    `- **Total Events**: ${stats.eventCount}`,
+    `- **Total Vectors**: ${stats.vectorCount}`,
+    `- **Sessions**: ${stats.sessionCount}`,
+    `- **Storage Size**: ${(stats.storageSize / 1024 / 1024).toFixed(2)} MB`,
+    ''
+  ].join('\n');
+}
+```
+
+**작업 항목**:
+- [ ] formatSearchResults 구현
+- [ ] formatTimeline 구현
+- [ ] formatDetails 구현
+- [ ] formatStats 구현
+
+## Phase 3: 설치 CLI (P0)
+
+### 3.1 MCP 설치 명령
+
+**파일**: `src/cli/commands/mcp.ts` (신규)
+
+```typescript
+import { Command } from 'commander';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+
+export const mcpCommand = new Command('mcp')
+  .description('Manage MCP server for Claude Desktop');
+
+mcpCommand
+  .command('install')
+  .description('Install MCP server for Claude Desktop')
+  .action(async () => {
+    const configPath = getClaudeDesktopConfigPath();
+    const config = loadOrCreateConfig(configPath);
+
+    // MCP 서버 설정 추가
+    config.mcpServers = config.mcpServers || {};
+    config.mcpServers['code-memory'] = {
+      command: 'npx',
+      args: ['code-memory-mcp'],
+      env: {
+        MEMORY_PATH: path.join(os.homedir(), '.claude-code', 'memory')
+      }
+    };
+
+    // 설정 저장
+    fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
+
+    console.log('✓ MCP server configuration added');
+    console.log('');
+    console.log('Restart Claude Desktop to use memory search.');
+    console.log('');
+    console.log('Available tools:');
+    console.log('  - mem-search: Search past conversations');
+    console.log('  - mem-timeline: Get context around memories');
+    console.log('  - mem-details: Get full memory content');
+    console.log('  - mem-stats: View storage statistics');
+  });
+
+mcpCommand
+  .command('uninstall')
+  .description('Remove MCP server from Claude Desktop')
+  .action(async () => {
+    const configPath = getClaudeDesktopConfigPath();
+    const config = loadOrCreateConfig(configPath);
+
+    if (config.mcpServers?.['code-memory']) {
+      delete config.mcpServers['code-memory'];
+      fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
+      console.log('✓ MCP server configuration removed');
+    } else {
+      console.log('MCP server was not installed');
+    }
+  });
+
+mcpCommand
+  .command('status')
+  .description('Check MCP server installation status')
+  .action(async () => {
+    const configPath = getClaudeDesktopConfigPath();
+
+    if (!fs.existsSync(configPath)) {
+      console.log('Claude Desktop config not found');
+      return;
+    }
+
+    const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+
+    if (config.mcpServers?.['code-memory']) {
+      console.log('✓ MCP server is installed');
+      console.log('');
+      console.log('Configuration:');
+      console.log(JSON.stringify(config.mcpServers['code-memory'], null, 2));
+    } else {
+      console.log('✗ MCP server is not installed');
+      console.log('');
+      console.log('Run "code-memory mcp install" to install');
+    }
+  });
+
+function getClaudeDesktopConfigPath(): string {
+  if (process.platform === 'darwin') {
+    return path.join(os.homedir(), 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json');
+  } else if (process.platform === 'win32') {
+    return path.join(process.env.APPDATA || '', 'Claude', 'claude_desktop_config.json');
+  } else {
+    return path.join(os.homedir(), '.config', 'claude', 'claude_desktop_config.json');
+  }
+}
+
+function loadOrCreateConfig(configPath: string): any {
+  const dir = path.dirname(configPath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+
+  if (fs.existsSync(configPath)) {
+    return JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+  }
+
+  return {};
+}
+```
+
+**작업 항목**:
+- [ ] install 명령 구현
+- [ ] uninstall 명령 구현
+- [ ] status 명령 구현
+- [ ] 플랫폼별 경로 처리
+
+## Phase 4: 테스트 및 문서 (P1)
+
+### 4.1 통합 테스트
+
+**파일**: `packages/mcp-server/tests/integration.test.ts` (신규)
+
+```typescript
+import { handleToolCall } from '../src/handlers';
+
+describe('MCP Server', () => {
+  test('mem-search returns results', async () => {
+    const result = await handleToolCall('mem-search', {
+      query: 'test query'
+    });
+
+    expect(result.isError).toBeFalsy();
+    expect(result.content[0].type).toBe('text');
+  });
+
+  test('mem-details returns full content', async () => {
+    const result = await handleToolCall('mem-details', {
+      ids: ['test-id']
+    });
+
+    expect(result.isError).toBeFalsy();
+  });
+
+  test('invalid tool returns error', async () => {
+    const result = await handleToolCall('invalid-tool', {});
+
+    expect(result.isError).toBe(true);
+  });
+});
+```
+
+**작업 항목**:
+- [ ] 도구별 테스트
+- [ ] 에러 케이스 테스트
+- [ ] E2E 테스트 (실제 Claude Desktop)
+
+## 파일 목록
+
+### 신규 파일
+```
+packages/mcp-server/
+├── package.json
+├── tsconfig.json
+├── src/
+│   ├── index.ts           # 서버 진입점
+│   ├── tools.ts           # 도구 정의
+│   ├── handlers.ts        # 도구 핸들러
+│   └── formatters.ts      # 출력 포맷터
+└── tests/
+    └── integration.test.ts
+
+src/cli/commands/mcp.ts    # CLI 명령
+```
+
+### 수정 파일
+```
+package.json               # 워크스페이스 설정
+src/cli/index.ts           # mcp 명령 등록
+```
+
+## 마일스톤
+
+| 단계 | 완료 기준 |
+|------|----------|
+| M1 | MCP 서버 패키지 구조 |
+| M2 | 도구 정의 |
+| M3 | 핸들러 구현 |
+| M4 | 포맷터 구현 |
+| M5 | CLI 설치 명령 |
+| M6 | 테스트 |
+| M7 | 문서화 |
+| M8 | npm 배포 |
+
+## 2026-02-25T12:31:26.344Z | c1410cb5-9d74-454b-a514-0b601bf3807d
+- type: session_summary
+- session: import:organized
+# MCP Desktop Integration Specification
+
+> **Version**: 1.0.0
+> **Status**: Draft
+> **Created**: 2026-02-01
+> **Reference**: claude-mem (thedotmack/claude-mem)
+
+## 1. 개요
+
+### 1.1 문제 정의
+
+현재 code-memory는 Claude Code CLI 전용:
+
+1. **Claude Desktop 미지원**: 데스크톱 앱에서 메모리 검색 불가
+2. **환경 분리**: CLI와 Desktop 간 메모리 공유 안 됨
+3. **접근성 제한**: 터미널 없이는 메모리 활용 불가
+
+### 1.2 해결 방향
+
+**MCP (Model Context Protocol) 서버**:
+- Claude Desktop에서 메모리 검색 도구 제공
+- CLI와 동일한 메모리 저장소 공유
+- 표준 MCP 프로토콜 준수
+
+## 2. 핵심 개념
+
+### 2.1 MCP 아키텍처
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    Claude Desktop                            │
+│  ┌─────────────────────────────────────────────────────┐   │
+│  │  MCP Client                                          │   │
+│  │  - Tool Discovery                                    │   │
+│  │  - Tool Invocation                                   │   │
+│  └────────────────────────┬────────────────────────────┘   │
+└───────────────────────────┼─────────────────────────────────┘
+                            │ stdio / HTTP
+                            ▼
+┌─────────────────────────────────────────────────────────────┐
+│                    MCP Server                                │
+│  ┌─────────────────────────────────────────────────────┐   │
+│  │  code-memory-mcp                                     │   │
+│  │  - mem-search tool                                   │   │
+│  │  - mem-timeline tool                                 │   │
+│  │  - mem-details tool                                  │   │
+│  └────────────────────────┬────────────────────────────┘   │
+└───────────────────────────┼─────────────────────────────────┘
+                            │
+                            ▼
+┌─────────────────────────────────────────────────────────────┐
+│                    Memory Storage                            │
+│  ┌──────────────┐    ┌──────────────┐                      │
+│  │   DuckDB     │    │   LanceDB    │                      │
+│  │   Events     │    │   Vectors    │                      │
+│  └──────────────┘    └──────────────┘                      │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### 2.2 제공할 MCP 도구
+
+| 도구 | 설명 | 입력 |
+|------|------|------|
+| `mem-search` | 메모리 검색 | query, filters |
+| `mem-timeline` | 타임라인 조회 | ids, windowSize |
+| `mem-details` | 상세 정보 조회 | ids |
+| `mem-stats` | 통계 조회 | - |
+
+### 2.3 MCP 프로토콜 버전
+
+```typescript
+const MCP_VERSION = '2024-11-05';  // 최신 MCP 사양
+```
+
+## 3. MCP 서버 구현
+
+### 3.1 서버 메타데이터
+
+```typescript
+const serverInfo = {
+  name: 'code-memory-mcp',
+  version: '1.0.0',
+  protocolVersion: MCP_VERSION,
+  capabilities: {
+    tools: {
+      listChanged: false
+    }
+  }
+};
+```
+
+### 3.2 도구 정의
+
+```typescript
+const tools = [
+  {
+    name: 'mem-search',
+    description: 'Search code-memory for relevant past conversations and insights',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        query: {
+          type: 'string',
+          description: 'Search query'
+        },
+        topK: {
+          type: 'number',
+          description: 'Maximum results (default: 5)'
+        },
+        sessionId: {
+          type: 'string',
+          description: 'Filter by session ID'
+        },
+        eventType: {
+          type: 'string',
+          enum: ['prompt', 'response', 'tool', 'insight'],
+          description: 'Filter by event type'
+        }
+      },
+      required: ['query']
+    }
+  },
+  {
+    name: 'mem-timeline',
+    description: 'Get timeline context around specific memories',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        ids: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Memory IDs to get timeline for'
+        },
+        windowSize: {
+          type: 'number',
+          description: 'Number of items before/after (default: 3)'
+        }
+      },
+      required: ['ids']
+    }
+  },
+  {
+    name: 'mem-details',
+    description: 'Get full details of specific memories',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        ids: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Memory IDs to fetch'
+        }
+      },
+      required: ['ids']
+    }
+  },
+  {
+    name: 'mem-stats',
+    description: 'Get memory storage statistics',
+    inputSchema: {
+      type: 'object',
+      properties: {}
+    }
+  }
+];
+```
+
+### 3.3 도구 실행
+
+```typescript
+async function handleToolCall(
+  name: string,
+  args: Record<string, unknown>
+): Promise<ToolResult> {
+  const memoryService = await MemoryService.getInstance();
+
+  switch (name) {
+    case 'mem-search': {
+      const results = await memoryService.progressiveSearch(
+        args.query as string,
+        {
+          topK: args.topK as number,
+          filter: {
+            sessionId: args.sessionId as string,
+            eventType: args.eventType as string
+          }
+        }
+      );
+
+      return {
+        content: [
+          {
+            type: 'text',
+            text: formatSearchResults(results)
+          }
+        ]
+      };
+    }
+
+    case 'mem-timeline': {
+      const timeline = await memoryService.getTimeline(
+        args.ids as string[],
+        { windowSize: args.windowSize as number }
+      );
+
+      return {
+        content: [
+          {
+            type: 'text',
+            text: formatTimeline(timeline)
+          }
+        ]
+      };
+    }
+
+    case 'mem-details': {
+      const details = await memoryService.getDetails(args.ids as string[]);
+
+      return {
+        content: [
+          {
+            type: 'text',
+            text: formatDetails(details)
+          }
+        ]
+      };
+    }
+
+    case 'mem-stats': {
+      const stats = await memoryService.getStats();
+
+      return {
+        content: [
+          {
+            type: 'text',
+            text: formatStats(stats)
+          }
+        ]
+      };
+    }
+
+    default:
+      throw new Error(`Unknown tool: ${name}`);
+  }
+}
+```
+
+## 4. 설치 및 설정
+
+### 4.1 Claude Desktop 설정
+
+**파일**: `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
+
+```json
+{
+  "mcpServers": {
+    "code-memory": {
+      "command": "npx",
+      "args": ["code-memory-mcp"],
+      "env": {
+        "MEMORY_PATH": "~/.claude-code/memory"
+      }
+    }
+  }
+}
+```
+
+### 4.2 Windows 설정
+
+**파일**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "code-memory": {
+      "command": "npx.cmd",
+      "args": ["code-memory-mcp"],
+      "env": {
+        "MEMORY_PATH": "%USERPROFILE%\\.claude-code\\memory"
+      }
+    }
+  }
+}
+```
+
+### 4.3 자동 설치 CLI
+
+```bash
+# 설치 명령
+$ code-memory mcp install
+
+Installing MCP server for Claude Desktop...
+✓ Created MCP server configuration
+✓ Updated Claude Desktop config
+
+Restart Claude Desktop to use memory search.
+
+# 제거 명령
+$ code-memory mcp uninstall
+```
+
+## 5. 통신 프로토콜
+
+### 5.1 stdio 기반 통신
+
+```typescript
+// MCP 서버 진입점
+import { Server } from '@modelcontextprotocol/sdk/server';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio';
+
+const server = new Server(serverInfo, {
+  capabilities: {
+    tools: {}
+  }
+});
+
+// 도구 핸들러 등록
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return { tools };
+});
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  return handleToolCall(request.params.name, request.params.arguments);
+});
+
+// stdio 연결
+const transport = new StdioServerTransport();
+await server.connect(transport);
+```
+
+### 5.2 메시지 형식
+
+```typescript
+// 요청 예시
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "tools/call",
+  "params": {
+    "name": "mem-search",
+    "arguments": {
+      "query": "DuckDB schema design"
+    }
+  }
+}
+
+// 응답 예시
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "result": {
+    "content": [
+      {
+        "type": "text",
+        "text": "Found 3 relevant memories:\n\n1. [mem:a7Bc3x] ..."
+      }
+    ]
+  }
+}
+```
+
+## 6. 출력 포맷
+
+### 6.1 검색 결과
+
+```markdown
+## Memory Search Results
+
+Found 3 relevant memories for "DuckDB schema":
+
+### 1. [mem:a7Bc3x] (0.94)
+**Session**: abc123 | **Date**: 2026-01-30
+> DuckDB를 사용하여 이벤트 소싱 패턴을 구현하는 것이 좋습니다...
+
+### 2. [mem:b8Xc2y] (0.87)
+**Session**: def456 | **Date**: 2026-01-29
+> 스키마 설계 시 인덱싱 전략을 고려해야 합니다...
+
+---
+Use `mem-details` with IDs for full content.
+Use `mem-timeline` for context around these memories.
+```
+
+### 6.2 타임라인
+
+```markdown
+## Timeline Context
+
+### Around [mem:a7Bc3x]
+
+| Time | Type | Preview |
+|------|------|---------|
+| 14:00 | prompt | DB 스키마를 어떻게 설계할까요? |
+| **14:05** | **response** | **[mem:a7Bc3x] DuckDB를 사용하여...** |
+| 14:10 | prompt | 인덱스는 어떻게? |
+| 14:15 | response | 다음 인덱스들을 추천합니다... |
+```
+
+### 6.3 상세 정보
+
+```markdown
+## Memory Details
+
+### [mem:a7Bc3x]
+
+**Session**: abc123
+**Date**: 2026-01-30 14:05
+**Type**: assistant_response
+
+**Content**:
+```
+DuckDB를 사용하여 이벤트 소싱 패턴을 구현하는 것이 좋습니다.
+
+이벤트는 불변이어야 하며, append-only 방식으로 저장합니다.
+
+스키마 예시:
+CREATE TABLE events (
+  event_id VARCHAR PRIMARY KEY,
+  event_type VARCHAR NOT NULL,
+  ...
+);
+```
+
+**Related Files**: src/core/event-store.ts
+**Tools Used**: Read, Write
+```
+
+## 7. 보안
+
+### 7.1 로컬 전용
+
+```typescript
+// MCP 서버는 로컬에서만 실행
+// 네트워크 노출 없음
+const server = new Server(serverInfo);
+const transport = new StdioServerTransport();  // stdio만 사용
+```
+
+### 7.2 경로 검증
+
+```typescript
+function validateMemoryPath(path: string): boolean {
+  const resolved = path.resolve(path);
+
+  // 홈 디렉토리 하위만 허용
+  const home = os.homedir();
+  if (!resolved.startsWith(home)) {
+    throw new Error('Memory path must be under home directory');
+  }
+
+  return true;
+}
+```
+
+### 7.3 민감 정보 필터링
+
+```typescript
+// MCP 응답에서도 privacy 필터 적용
+function formatForMCP(content: string): string {
+  return applyPrivacyFilter(content, config.privacy).content;
+}
+```
+
+## 8. 에러 처리
+
+```typescript
+// MCP 에러 응답
+function handleError(error: Error): ToolResult {
+  return {
+    content: [
+      {
+        type: 'text',
+        text: `Error: ${error.message}`
+      }
+    ],
+    isError: true
+  };
+}
+
+// 일반적인 에러 케이스
+- Memory storage not found
+- Invalid query parameters
+- Permission denied
+- Storage corrupted
+```
+
+## 9. 성공 기준
+
+- [ ] `code-memory mcp install` 명령 동작
+- [ ] Claude Desktop에서 `mem-search` 도구 사용 가능
+- [ ] Progressive disclosure (search → timeline → details) 동작
+- [ ] CLI와 동일한 메모리 저장소 공유
+- [ ] Privacy 필터 적용
+- [ ] 에러 시 적절한 메시지 반환