claude-memory-layer 1.0.0

package/specs/private-tags/spec.md

@@ -0,0 +1,345 @@
+# Private Tags Specification
+
+> **Version**: 1.0.0
+> **Status**: Draft
+> **Created**: 2026-02-01
+> **Reference**: claude-mem (thedotmack/claude-mem)
+
+## 1. 개요
+
+### 1.1 문제 정의
+
+현재 프라이버시 필터링의 한계:
+
+1. **패턴 기반만 지원**: `password`, `api_key` 등 고정 패턴만 필터링
+2. **사용자 제어 부족**: 특정 내용을 명시적으로 제외할 방법 없음
+3. **컨텍스트 무시**: 의도적으로 공유하고 싶지 않은 대화 부분 지정 불가
+
+### 1.2 해결 방향
+
+**명시적 `<private>` 태그 지원**:
+- 사용자가 직접 비공개 영역 지정
+- 태그 내 내용은 메모리에 저장되지 않음
+- 패턴 기반 필터링과 병행
+
+## 2. 핵심 개념
+
+### 2.1 태그 문법
+
+```markdown
+이것은 저장됩니다.
+
+<private>
+이 부분은 메모리에 저장되지 않습니다.
+API_KEY=sk-xxxx
+SECRET_TOKEN=abc123
+</private>
+
+이것도 저장됩니다.
+```
+
+### 2.2 태그 변형
+
+```typescript
+// 지원하는 태그 형식
+const PRIVATE_TAG_PATTERNS = [
+  /<private>[\s\S]*?<\/private>/gi,           // 기본
+  /<private\s*\/>[\s\S]*?<\/private>/gi,      // self-closing 시작
+  /\[private\][\s\S]*?\[\/private\]/gi,       // 대괄호 형식
+  /<!--\s*private\s*-->[\s\S]*?<!--\s*\/private\s*-->/gi  // HTML 주석 형식
+];
+```
+
+### 2.3 중첩 처리
+
+```markdown
+<private>
+외부 비공개
+  <private>
+  중첩된 비공개 (지원하지 않음 - 외부 태그만 처리)
+  </private>
+내용 계속
+</private>
+```
+
+## 3. 처리 로직
+
+### 3.1 파싱 알고리즘
+
+```typescript
+interface PrivateSection {
+  start: number;
+  end: number;
+  content: string;
+}
+
+function findPrivateSections(text: string): PrivateSection[] {
+  const sections: PrivateSection[] = [];
+  const regex = /<private>([\s\S]*?)<\/private>/gi;
+
+  let match;
+  while ((match = regex.exec(text)) !== null) {
+    sections.push({
+      start: match.index,
+      end: match.index + match[0].length,
+      content: match[1]
+    });
+  }
+
+  return sections;
+}
+
+function removePrivateSections(text: string): string {
+  return text.replace(/<private>[\s\S]*?<\/private>/gi, '[PRIVATE]');
+}
+```
+
+### 3.2 저장 전 필터링
+
+```typescript
+async function storeWithPrivacyFilter(content: string): Promise<string> {
+  // 1. <private> 태그 제거
+  let filtered = removePrivateSections(content);
+
+  // 2. 패턴 기반 필터링 (기존)
+  filtered = maskSensitivePatterns(filtered);
+
+  // 3. 빈 줄 정리
+  filtered = filtered.replace(/\n{3,}/g, '\n\n');
+
+  return filtered;
+}
+```
+
+### 3.3 마커 옵션
+
+```typescript
+interface PrivacyConfig {
+  privateTag: {
+    enabled: boolean;
+    marker: '[PRIVATE]' | '[REDACTED]' | '';  // 대체 텍스트
+    preserveStructure: boolean;  // 줄바꿈 유지 여부
+  };
+}
+
+// preserveStructure: true
+"Before\n<private>\nSecret\nData\n</private>\nAfter"
+→ "Before\n[PRIVATE]\n\n\nAfter"
+
+// preserveStructure: false
+"Before\n<private>\nSecret\nData\n</private>\nAfter"
+→ "Before\n[PRIVATE]\nAfter"
+```
+
+## 4. 데이터 스키마
+
+### 4.1 이벤트 메타데이터
+
+```typescript
+const EventPayloadSchema = z.object({
+  content: z.string(),
+  // 프라이버시 메타데이터 추가
+  privacy: z.object({
+    hasPrivateSections: z.boolean(),
+    privateCount: z.number(),
+    originalLength: z.number(),
+    filteredLength: z.number()
+  }).optional()
+});
+```
+
+### 4.2 통계
+
+```typescript
+interface PrivacyStats {
+  totalPrivateSections: number;
+  totalCharactersFiltered: number;
+  sessionsWithPrivate: number;
+}
+```
+
+## 5. 사용 시나리오
+
+### 5.1 API 키 보호
+
+```markdown
+User: 이 API 키로 요청해줘
+
+<private>
+OPENAI_API_KEY=sk-proj-xxxxxxxxxxxxxxxxxxxx
+</private>
+
+응답 형식은 JSON으로 해줘.
+```
+
+**저장 결과**:
+```
+User: 이 API 키로 요청해줘
+
+[PRIVATE]
+
+응답 형식은 JSON으로 해줘.
+```
+
+### 5.2 민감한 비즈니스 로직
+
+```markdown
+User: 다음 알고리즘을 최적화해줘
+
+<private>
+// 회사 기밀 알고리즘
+function proprietaryAlgorithm() {
+  // ...
+}
+</private>
+
+특히 시간 복잡도를 개선하고 싶어.
+```
+
+### 5.3 개인 정보
+
+```markdown
+User: 이메일 템플릿 작성해줘
+
+<private>
+받는 사람: john.doe@company.com
+참조: secret-team@company.com
+</private>
+
+공식적인 톤으로 작성해줘.
+```
+
+## 6. 검색 영향
+
+### 6.1 벡터 검색
+
+- `[PRIVATE]` 마커는 임베딩에 포함
+- 원본 private 내용은 검색 불가
+- 주변 컨텍스트는 검색 가능
+
+### 6.2 전문 검색 (FTS)
+
+```sql
+-- [PRIVATE] 마커 제외 검색
+SELECT * FROM events_fts
+WHERE content MATCH :query
+  AND content NOT LIKE '%[PRIVATE]%';
+
+-- 또는 마커 포함 결과도 표시
+SELECT * FROM events_fts
+WHERE content MATCH :query;
+```
+
+## 7. UI 표시
+
+### 7.1 CLI 출력
+
+```
+$ code-memory history
+
+[2026-02-01 14:00] User Prompt
+  이 API 키로 요청해줘
+  [🔒 PRIVATE CONTENT REDACTED]
+  응답 형식은 JSON으로 해줘.
+```
+
+### 7.2 Web Viewer
+
+```html
+<div class="event-content">
+  <p>이 API 키로 요청해줘</p>
+  <div class="private-marker">
+    <span class="icon">🔒</span>
+    <span>Private content (not stored)</span>
+  </div>
+  <p>응답 형식은 JSON으로 해줘.</p>
+</div>
+```
+
+## 8. 설정
+
+### 8.1 설정 스키마
+
+```typescript
+const PrivacyConfigSchema = z.object({
+  // 기존 패턴 기반 필터링
+  excludePatterns: z.array(z.string()).default([
+    'password', 'secret', 'api_key', 'token', 'bearer'
+  ]),
+
+  // 새로운 태그 기반 필터링
+  privateTags: z.object({
+    enabled: z.boolean().default(true),
+    marker: z.enum(['[PRIVATE]', '[REDACTED]', '']).default('[PRIVATE]'),
+    preserveLineCount: z.boolean().default(false),
+    supportedFormats: z.array(z.enum([
+      'xml',      // <private>
+      'bracket',  // [private]
+      'comment'   // <!-- private -->
+    ])).default(['xml'])
+  }),
+
+  // 자동 감지
+  autoDetect: z.object({
+    enabled: z.boolean().default(true),
+    patterns: z.array(z.string())  // 정규식
+  }).optional()
+});
+```
+
+### 8.2 설정 예시
+
+```json
+{
+  "privacy": {
+    "excludePatterns": ["password", "secret", "api_key"],
+    "privateTags": {
+      "enabled": true,
+      "marker": "[PRIVATE]",
+      "supportedFormats": ["xml", "bracket"]
+    }
+  }
+}
+```
+
+## 9. 경계 케이스
+
+### 9.1 불완전한 태그
+
+```markdown
+<private>
+시작은 있지만 끝이 없음
+```
+→ 끝까지 private로 처리? 또는 무시?
+
+**결정**: 불완전한 태그는 무시 (보수적 접근)
+
+### 9.2 코드 블록 내 태그
+
+```markdown
+```python
+# 예시 코드
+print("<private>not actually private</private>")
+```
+```
+
+**결정**: 코드 블록 내 태그는 무시 (리터럴로 취급)
+
+### 9.3 빈 태그
+
+```markdown
+<private></private>
+<private>   </private>
+```
+
+**결정**: 빈 태그는 완전히 제거 (마커도 남기지 않음)
+
+## 10. 성공 기준
+
+- [ ] `<private>` 태그 내 내용이 메모리에 저장되지 않음
+- [ ] `[PRIVATE]` 마커로 대체됨
+- [ ] 기존 패턴 기반 필터링과 병행 동작
+- [ ] 불완전한 태그 안전하게 처리
+- [ ] 코드 블록 내 태그 무시
+- [ ] 통계에 필터링 정보 포함
+- [ ] CLI와 Web UI에서 적절히 표시

package/specs/progressive-disclosure/context.md

@@ -0,0 +1,346 @@
+# Progressive Disclosure Context
+
+> **Version**: 1.0.0
+> **Created**: 2026-02-01
+
+## 1. 배경
+
+### 1.1 claude-mem의 접근 방식
+
+claude-mem은 토큰 효율성을 위해 3-Layer Progressive Disclosure 패턴을 사용:
+
+```
+Layer 1: Search Index (~50-100 tokens per result)
+    ↓ (필터링)
+Layer 2: Timeline (~200 tokens)
+    ↓ (선택)
+Layer 3: Full Details (~500-1000 tokens per result)
+```
+
+**주요 특징**:
+- "필터링 후 상세 조회" 전략
+- 약 10배 토큰 절약
+- 사용자/AI가 필요한 것만 확장
+
+**구현 방식**:
+- MCP 도구로 각 레이어 노출
+- `search` → `timeline` → `get_observations` 순서
+- `__IMPORTANT` 도구로 워크플로우 문서화
+
+### 1.2 현재 code-memory의 상황
+
+현재 검색은 단일 레이어:
+
+```typescript
+// 현재 Retriever.search()
+async search(query: string): Promise<SearchResult[]> {
+  const vectorResults = await this.vectorStore.search(query, { topK: 5 });
+  const events = await this.enrichWithEvents(vectorResults);
+  return events;  // 전체 내용 반환
+}
+```
+
+**문제점**:
+1. 모든 결과의 전체 내용을 가져옴
+2. 컨텍스트 크기가 토큰 제한에 쉽게 도달
+3. 관련성 낮은 내용도 포함됨
+
+### 1.3 토큰 비용 분석
+
+| 시나리오 | 현재 방식 | Progressive 방식 |
+|----------|----------|-----------------|
+| 5개 결과, 1개만 관련 | ~5,000 tokens | ~600 tokens |
+| 10개 결과, 2개만 관련 | ~10,000 tokens | ~1,200 tokens |
+| 20개 결과, 3개만 관련 | ~20,000 tokens | ~2,000 tokens |
+
+**절약 효과**: 평균 80-90% 토큰 감소
+
+## 2. MCP 도구 설계 참고
+
+### 2.1 claude-mem의 MCP 도구
+
+```typescript
+// claude-mem MCP tools (추정)
+{
+  tools: [
+    {
+      name: 'search',
+      description: 'Search memories, returns index only',
+      input_schema: {
+        query: 'string',
+        filters: { type: 'string', date: 'string' }
+      },
+      output: 'SearchIndexItem[]'
+    },
+    {
+      name: 'timeline',
+      description: 'Get timeline context around observations',
+      input_schema: {
+        observation_ids: 'string[]',
+        window_size: 'number'
+      },
+      output: 'TimelineItem[]'
+    },
+    {
+      name: 'get_observations',
+      description: 'Get full observation details by IDs',
+      input_schema: {
+        ids: 'string[]'
+      },
+      output: 'Observation[]'
+    },
+    {
+      name: '__IMPORTANT',
+      description: 'Workflow documentation for Claude',
+      // Claude가 이 도구를 보고 검색 워크플로우를 이해
+    }
+  ]
+}
+```
+
+### 2.2 워크플로우 문서화
+
+```markdown
+# Memory Search Workflow
+
+1. **Always start with `search`** to get compact index
+2. **Review scores** before expanding
+3. **Use `timeline`** if context is needed
+4. **Only call `get_observations`** for selected IDs
+5. **Never** fetch all details at once
+```
+
+## 3. 기존 코드와의 관계
+
+### 3.1 retriever.ts
+
+현재 Retriever 구조:
+
+```typescript
+export class Retriever {
+  async search(query: string): Promise<SearchResult[]> {
+    // 1. 벡터 검색
+    const vectorResults = await this.vectorStore.search(query);
+
+    // 2. 이벤트 enrichment (전체 로드)
+    const enriched = await Promise.all(
+      vectorResults.map(async (r) => {
+        const event = await this.eventStore.findById(r.id);
+        return { ...r, content: event.payload.content };  // 전체 내용
+      })
+    );
+
+    return enriched;
+  }
+}
+```
+
+**수정 방향**:
+- `search()` → `searchIndex()` (Layer 1)
+- `getTimeline()` 추가 (Layer 2)
+- `getDetails()` 추가 (Layer 3)
+- `smartSearch()` 추가 (자동 확장)
+
+### 3.2 matcher.ts
+
+현재 Matcher는 confidence 기반 분류:
+
+```typescript
+export function matchSearchResults(results: SearchResult[]): MatchResult {
+  const high = results.filter(r => r.score >= 0.92);
+  const suggested = results.filter(r => r.score >= 0.75 && r.score < 0.92);
+
+  return { high, suggested, none: [] };
+}
+```
+
+**확장 방향**:
+- 기존 Matcher 로직을 확장 규칙에 통합
+- `high` → 자동 확장 대상
+- `suggested` → Layer 1만 표시
+
+### 3.3 vector-store.ts
+
+현재 VectorStore 검색:
+
+```typescript
+async search(query: string, options: { topK: number }): Promise<VectorSearchResult[]> {
+  const queryVector = await this.embedder.embed(query);
+  return this.db.search(queryVector, options.topK);
+}
+```
+
+**변경 불필요** - 기존 벡터 검색 그대로 사용
+
+### 3.4 event-store.ts
+
+필요한 추가 메서드:
+
+```typescript
+// 주변 이벤트 조회 (타임라인용)
+async findSurrounding(
+  sessionId: string,
+  timestamp: Date,
+  windowSize: number
+): Promise<Event[]> {
+  return this.db.query(`
+    SELECT * FROM events
+    WHERE session_id = ?
+      AND timestamp BETWEEN
+        datetime(?, '-${windowSize} hours') AND
+        datetime(?, '+${windowSize} hours')
+    ORDER BY timestamp
+  `, [sessionId, timestamp, timestamp]);
+}
+```
+
+## 4. 설계 결정 사항
+
+### 4.1 왜 3개 레이어인가?
+
+**대안 1: 2개 레이어 (Index + Detail)**
+- 단점: 시간 맥락 파악 어려움
+- 단점: 모호한 결과 처리 어려움
+
+**대안 2: 4개 이상 레이어**
+- 단점: 복잡도 증가
+- 단점: 실용적 이점 미미
+
+**선택: 3개 레이어**
+- Layer 1: What (무엇이 있는지)
+- Layer 2: When (언제 발생했는지)
+- Layer 3: How (구체적으로 어떻게)
+
+### 4.2 자동 확장 vs 수동 확장
+
+**자동 확장 장점**:
+- 사용자 경험 향상
+- "자세히 알려줘" 명령 불필요
+- 높은 신뢰도 결과 즉시 제공
+
+**자동 확장 단점**:
+- 토큰 예측 어려움
+- 때로는 불필요한 확장
+
+**결론: 하이브리드 접근**
+- 높은 신뢰도 → 자동 확장
+- 중간 신뢰도 → Index만 제공 + 힌트
+- 낮은 신뢰도 → Index만 제공
+
+### 4.3 요약 생성 전략
+
+**Option 1: LLM 요약**
+- 장점: 고품질 요약
+- 단점: 비용, 지연시간
+
+**Option 2: 규칙 기반 추출**
+- 장점: 빠름, 무료
+- 단점: 품질 제한
+
+**선택: 규칙 기반 + 캐싱**
+- 첫 문장 추출
+- 코드 블록 축약
+- 결과 캐싱
+
+### 4.4 토큰 추정 방식
+
+```typescript
+// 간단한 추정 (정확도 ~85%)
+function estimateTokens(text: string): number {
+  return Math.ceil(text.length / 4);
+}
+
+// 또는 정확한 추정 (tiktoken 사용)
+import { encoding_for_model } from 'tiktoken';
+const enc = encoding_for_model('gpt-4');
+function estimateTokens(text: string): number {
+  return enc.encode(text).length;
+}
+```
+
+**결론**: 간단한 추정 사용 (성능 우선)
+
+## 5. 성능 고려사항
+
+### 5.1 검색 지연시간
+
+| 레이어 | 목표 지연시간 | 병목 |
+|--------|-------------|------|
+| Layer 1 | < 100ms | 벡터 검색 |
+| Layer 2 | < 200ms | DB 쿼리 |
+| Layer 3 | < 500ms | 다중 조회 |
+
+**최적화 전략**:
+- Layer 1: 벡터 인덱스 최적화
+- Layer 2: 세션별 인덱스 활용
+- Layer 3: 배치 조회
+
+### 5.2 캐싱 전략
+
+```typescript
+// 레이어별 캐시 TTL
+const CACHE_CONFIG = {
+  layer1: {
+    ttl: 60 * 1000,      // 1분 (검색 결과는 자주 변함)
+    maxSize: 100
+  },
+  layer2: {
+    ttl: 5 * 60 * 1000,  // 5분 (타임라인은 안정적)
+    maxSize: 500
+  },
+  layer3: {
+    ttl: 30 * 60 * 1000, // 30분 (상세 내용은 거의 안 변함)
+    maxSize: 200
+  }
+};
+```
+
+### 5.3 메모리 사용
+
+- Layer 1 캐시: ~10KB per entry × 100 = ~1MB
+- Layer 2 캐시: ~2KB per entry × 500 = ~1MB
+- Layer 3 캐시: ~10KB per entry × 200 = ~2MB
+- **총 메모리**: ~4MB (허용 범위)
+
+## 6. UI/UX 고려사항
+
+### 6.1 CLI 출력 포맷
+
+```
+🔍 Search Results (5 matches)
+
+#1 [mem_abc] DuckDB 스키마 설계 논의 (0.94)
+#2 [mem_def] 타입 시스템 리팩토링 (0.87)
+#3 [mem_ghi] 벡터 저장소 설정 (0.82)
+
+💡 Tip: Use "show mem_abc" for details
+
+---
+
+📅 Timeline (auto-expanded for high confidence)
+
+14:00 → User asked about schema design
+14:05 → **[mem_abc]** Discussed DuckDB approach
+14:15 → Follow-up on indexing
+```
+
+### 6.2 확장 힌트
+
+```typescript
+function formatExpansionHint(result: ProgressiveSearchResult): string {
+  if (result.meta.expandedCount === 0) {
+    return `Use "show [id]" to see details`;
+  }
+  if (result.meta.expansionReason === 'ambiguous_multiple_high') {
+    return `Multiple matches found. Use "show [id]" for specific details`;
+  }
+  return '';
+}
+```
+
+## 7. 참고 자료
+
+- **claude-mem README**: Progressive disclosure pattern, MCP tools
+- **OpenAI Cookbook**: Token counting and optimization
+- **AXIOMMIND**: Principle 7 (Standard JSON) - 포맷 일관성
+- **기존 specs**: retriever.ts, matcher.ts 구현