claude-memory-layer 1.0.31 → 1.0.33

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

@@ -1,494 +0,0 @@
-# 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 필터 적용
-- [ ] 에러 시 적절한 메시지 반환

package/specs/memory-utilization-improvements/context.md

@@ -1,145 +0,0 @@
-# Context: Memory Utilization Improvements
-
-## 분석 대상
-
-- **프로젝트**: shopping_assistant
-- **프로젝트 키**: f4d5c120
-- **분석 일자**: 2026-03-04
-- **데이터 기간**: 2026-02-25 ~ 2026-03-04
-
----
-
-## 실제 측정 데이터
-
-### 전체 지표
-
-| 지표 | 값 | 상태 |
-|------|-----|------|
-| 총 이벤트 수 | 1,587 | - |
-| L0 이벤트 | **1,587 (100%)** | 🔴 심각 |
-| L1+ 이벤트 | **0** | 🔴 심각 |
-| 총 세션 수 | 40 (f4d5c120) / 55 (전체) | - |
-| 벡터 수 | 1,586 | - |
-| Retrieval Trace | **1건** | 🔴 심각 |
-| 세션 요약 | **2건** | 🔴 심각 |
-| 검색 후보 선택률 | 100% (5/5) | ⚠️ 경고 |
-
-### 이벤트 유형 분포
-
-```
-Tool Observation:  1,475건  (92.9%)  ← 노이즈 지배적
-User Prompt:          94건   (5.9%)
-Agent Response:       16건   (1.0%)
-Session Summary:       2건   (0.1%)
-```
-
-### 활동 타임라인
-
-- 2026-02-25: 521건 (피크)
-- 2026-02-26: 478건 (피크)
-- 2026-03-04: 40건 (당일)
-- 7일 누적: 1,039건
-
-### 주요 세션 샘플
-
-| 세션 ID | 이벤트 수 | 지속 시간 | 날짜 |
-|---------|---------|---------|------|
-| 5ef326be | 82 | 11분 | 02-25 |
-| 790b37f6 | 53 | 2시간 | 02-25 |
-| 7302c0af | 69 | - | 02-25 |
-| 49653e19 | 31 | 24분 | 03-04 |
-
----
-
-## 핵심 발견: 실제 증거
-
-### 발견 1: 검색은 실행되나 Trace가 기록되지 않음
-
-User Prompt 이벤트의 metadata를 보면:
-
-```json
-// Turn 1 (첫 번째 턴)
-{ "adherence": true, "reason": "first-turn" }
-
-// Turn 3
-{ "adherence": false, "reason": "skip" }
-
-// Turn 4
-{ "adherence": false, "reason": "skip" }
-
-// Turn 5
-{ "adherence": true, "reason": "interval-based" }
-```
-
-**결론**: `adherence: true`인 경우 검색이 실행됨 → 검색 자체는 작동함.
-그러나 DB에 기록된 retrieval trace는 단 1건.
-**검색 실행 ≠ Trace 기록 성공** → trace INSERT가 실패하거나 비동기 타이밍 문제.
-
-### 발견 2: Embedding 모델 반복 오류
-
-세션 로그에서 확인된 오류들:
-
-```
-"RotaryEmbedding node execution errors"
-"Unknown model class 'eurobert'"
-"8389 tokens exceeding limits"
-"Processing embeddings... ONNX Runtime errors"
-```
-
-전체 이벤트 1,587건 중 벡터 1,586개 생성 → 거의 임베딩은 됨.
-하지만 모델 오류가 지속적으로 발생 중이며 사용자에게 오류가 노출되고 있음.
-
-### 발견 3: Cascade Failure 구조
-
-```
-Trace 기록 실패
-    ↓
-access_count 미증가
-    ↓
-Graduation 미발생 (L0 고착)
-    ↓
-고품질 메모리 없음
-    ↓
-검색 품질 저하
-    ↓
-Helpfulness 측정 불가
-    ↓
-개선 피드백 루프 단절
-```
-
-### 발견 4: Tool Observation 과잉 저장
-
-93%가 tool observation이며 내용은 주로:
-- 일상적인 bash 명령 결과 (ls, grep 출력)
-- 파일 읽기 내용 (반복적)
-- Glob 검색 결과
-
-이 데이터들은 다음 세션에서 재사용 가치가 낮음.
-오히려 FTS5 검색 코퍼스를 비대화시켜 검색 노이즈 증가.
-
-### 발견 5: Stop Hook 미작동
-
-40 세션 중 세션 요약 2건 → 95%의 세션에서 Stop Hook이 발생하지 않음.
-Session-start의 백필 메커니즘도 요약을 생성하지 못하고 있음.
-
----
-
-## 시스템 환경
-
-- **OS**: Linux 5.15 (Ubuntu)
-- **런타임**: Node.js (TSX)
-- **DB**: SQLite (better-sqlite3)
-- **벡터 DB**: LanceDB
-- **임베딩 모델**: jinaai/jina-embeddings-v5-text-nano-text-matching
-- **대체 모델**: onnx-community/embeddinggemma-300m-ONNX
-- **Heap**: 116MB / 135MB (86% 사용)
-
----
-
-## 관련 기존 스펙
-
-- `specs/20260207-dashboard-upgrade/` - 대시보드 개선
-- `specs/vector-outbox-v2/` - 벡터 임베딩 파이프라인
-- `specs/endless-mode/` - 세션 연속성
-- `specs/entity-edge-model/` - 엔티티 추적
-- `specs/selective-tool-observation/` - Tool observation 선택적 저장 (부분 설계됨)