claude-memory-layer 1.0.10 → 1.0.12

package/memory/specs/private-tags/2026-02-25.md

@@ -0,0 +1,1057 @@
+
+## 2026-02-25T12:31:26.376Z | 0bd11cc2-d4f5-4b9b-ac8b-213ffdd8f6c4
+- type: session_summary
+- session: import:organized
+# Private Tags Context
+
+> **Version**: 1.0.0
+> **Created**: 2026-02-01
+
+## 1. 배경
+
+### 1.1 claude-mem의 접근 방식
+
+claude-mem은 `<private>` 태그를 통한 명시적 프라이버시 제어 지원:
+
+```markdown
+<private>
+API_KEY=sk-xxxx
+</private>
+```
+
+**특징**:
+- 사용자가 직접 비공개 영역 지정
+- 태그 내 내용은 저장되지 않음
+- 간단하고 직관적인 문법
+
+### 1.2 현재 code-memory의 상황
+
+현재 패턴 기반 필터링만 지원:
+
+```typescript
+const config = {
+  privacy: {
+    excludePatterns: ['password', 'secret', 'api_key']
+  }
+};
+```
+
+**한계**:
+1. 고정된 패턴만 감지
+2. 컨텍스트 무시 (실제 비밀번호 아닌 "password"도 필터링)
+3. 사용자 의도 반영 불가
+
+### 1.3 두 접근법 비교
+
+| 패턴 기반 | 태그 기반 |
+|----------|----------|
+| 자동 감지 | 명시적 지정 |
+| False positive 가능 | 정확한 제어 |
+| 설정 필요 | 즉시 사용 |
+| 패턴 외 누락 가능 | 사용자 책임 |
+
+**결론**: 두 방식 병행이 최선
+
+## 2. 태그 문법 선택
+
+### 2.1 고려한 옵션들
+
+| 옵션 | 예시 | 장점 | 단점 |
+|------|------|------|------|
+| XML 스타일 | `<private>...</private>` | 직관적, 중첩 가능 | Markdown과 충돌 가능 |
+| 대괄호 | `[private]...[/private]` | Markdown 친화적 | 덜 직관적 |
+| HTML 주석 | `<!-- private -->` | 렌더링 안 됨 | 복잡함 |
+| 펜스 스타일 | `:::private\n...\n:::` | Markdown 확장 스타일 | 비표준 |
+
+### 2.2 선택: XML 스타일 + 대안 지원
+
+```typescript
+// 기본: XML 스타일
+<private>...</private>
+
+// 대안 1: 대괄호 (Markdown 문서용)
+[private]...[/private]
+
+// 대안 2: HTML 주석 (렌더링 방지)
+<!-- private -->...<!-- /private -->
+```
+
+### 2.3 claude-mem과의 호환성
+
+claude-mem이 `<private>` 태그를 사용하므로 동일한 문법을 기본으로 채택하여 사용자 경험 일관성 유지.
+
+## 3. 기존 코드와의 관계
+
+### 3.1 types.ts
+
+현재 Privacy 관련 타입:
+
+```typescript
+// 현재
+export const PrivacyConfigSchema = z.object({
+  excludePatterns: z.array(z.string()),
+  anonymize: z.boolean()
+});
+
+// 확장
+export const PrivacyConfigSchema = z.object({
+  excludePatterns: z.array(z.string()),
+  anonymize: z.boolean(),
+  privateTags: PrivateTagsConfigSchema  // 추가
+});
+```
+
+### 3.2 훅 연동
+
+영향받는 훅:
+- `user-prompt-submit.ts`: 사용자 입력 필터링
+- `stop.ts`: AI 응답 필터링
+- `post-tool-use.ts`: 도구 출력 필터링
+
+```typescript
+// 모든 훅에서 동일한 필터 사용
+const filtered = applyPrivacyFilter(content, config.privacy);
+```
+
+### 3.3 검색 영향
+
+- **벡터 검색**: `[PRIVATE]` 마커가 임베딩에 포함되지만, 원본 내용은 검색 불가
+- **전문 검색**: 마커는 검색 가능, 원본 내용 불가
+
+## 4. 설계 결정 사항
+
+### 4.1 마커 선택
+
+**옵션들**:
+1. `[PRIVATE]` - 명확하고 검색 가능
+2. `[REDACTED]` - 일반적인 검열 용어
+3. `""` (빈 문자열) - 흔적 없이 제거
+4. `[...]` - 간결하지만 모호
+
+**선택**: `[PRIVATE]`
+- 명확한 의미 전달
+- 검색/필터링 가능
+- 설정으로 변경 가능
+
+### 4.2 코드 블록 처리
+
+**문제**: 코드 블록 내 `<private>` 태그를 리터럴로 취급해야 함
+
+```markdown
+```xml
+<private>이것은 예시 코드입니다</private>
+```
+```
+
+**해결**: 코드 블록을 먼저 추출하고 보호
+
+```typescript
+// 1. 코드 블록 임시 치환
+// 2. private 태그 파싱
+// 3. 코드 블록 복원
+```
+
+### 4.3 불완전한 태그 처리
+
+**시나리오**:
+```markdown
+<private>
+시작은 있지만 끝이 없음...
+(사용자가 실수로 닫지 않음)
+```
+
+**옵션**:
+1. 끝까지 private로 처리 → 데이터 손실 위험
+2. 무시 (원본 유지) → 보수적, 안전
+
+**선택**: 무시 (보수적 접근)
+- 데이터 손실 방지
+- 사용자에게 경고 표시 가능
+
+### 4.4 중첩 태그 처리
+
+```markdown
+<private>
+외부
+  <private>내부</private>
+외부 계속
+</private>
+```
+
+**선택**: 중첩 지원하지 않음
+- 외부 태그만 처리
+- 복잡도 감소
+- 실용적 케이스 드묾
+
+## 5. 성능 고려사항
+
+### 5.1 정규식 성능
+
+```typescript
+// 비효율적 (매번 새 정규식)
+for (const format of formats) {
+  const regex = new RegExp(...);  // 매번 생성
+}
+
+// 효율적 (캐싱)
+const TAG_PATTERNS = {
+  xml: /<private>[\s\S]*?<\/private>/gi,
+  // ...
+};
+```
+
+### 5.2 대용량 텍스트
+
+긴 텍스트의 경우:
+- 정규식 `[\s\S]*?` 사용 (non-greedy)
+- 스트리밍 파싱 고려 (향후)
+
+### 5.3 캐싱
+
+```typescript
+// 동일 입력에 대한 결과 캐싱
+const filterCache = new LRUCache<string, FilterResult>({
+  max: 100,
+  ttl: 60000
+});
+```
+
+## 6. 보안 고려사항
+
+### 6.1 태그 우회 시도
+
+```markdown
+<!-- 공격자가 태그를 깨뜨리려는 시도 -->
+<private
+>secret</private>
+
+<pri
+vate>secret</private>
+```
+
+**대응**: 엄격한 정규식 매칭 (정확한 `<private>` 패턴만)
+
+### 6.2 메모리 내 노출
+
+- 파싱 중 원본 내용이 메모리에 일시적으로 존재
+- 디스크에는 저장되지 않음
+- 로그에 원본 출력 금지
+
+```typescript
+// 안전하지 않음
+console.log(`Parsing: ${content}`);
+
+// 안전
+console.log(`Parsing content of length ${content.length}`);
+```
+
+## 7. 사용자 경험
+
+### 7.1 문서화
+
+```markdown
+## Privacy Tags
+
+Wrap sensitive content in `<private>` tags to prevent storage:
+
+\`\`\`
+<private>
+Your sensitive data here
+</private>
+\`\`\`
+
+Content inside these tags will NOT be stored in memory.
+```
+
+### 7.2 피드백
+
+```typescript
+// 훅에서 사용자에게 피드백
+if (filterResult.metadata.privateTagCount > 0) {
+  return {
+    message: `🔒 ${filterResult.metadata.privateTagCount} private section(s) excluded from memory`
+  };
+}
+```
+
+### 7.3 경고
+
+```typescript
+// 불완전한 태그 감지
+if (hasUnmatchedOpenTag(content)) {
+  return {
+    warning: '⚠️ Unclosed <private> tag detected. Content was NOT filtered.'
+  };
+}
+```
+
+## 8. 참고 자료
+
+- **claude-mem README**: Privacy controls using `<private>` tags
+- **OWASP**: Sensitive Data Exposure guidelines
+- **GDPR**: Right to erasure (잊혀질 권리)
+
+## 2026-02-25T12:31:26.383Z | a1b87a8c-0080-4962-a7a0-5074c74455a9
+- type: session_summary
+- session: import:organized
+# Private Tags Implementation Plan
+
+> **Version**: 1.0.0
+> **Status**: Draft
+> **Created**: 2026-02-01
+
+## Phase 1: 파서 구현 (P0)
+
+### 1.1 태그 파서
+
+**파일**: `src/core/privacy/tag-parser.ts` (신규)
+
+```typescript
+export interface PrivateSection {
+  start: number;
+  end: number;
+  content: string;
+  format: 'xml' | 'bracket' | 'comment';
+}
+
+export interface ParseResult {
+  filtered: string;
+  sections: PrivateSection[];
+  stats: {
+    count: number;
+    totalLength: number;
+  };
+}
+
+const TAG_PATTERNS: Record<string, RegExp> = {
+  xml: /<private>([\s\S]*?)<\/private>/gi,
+  bracket: /\[private\]([\s\S]*?)\[\/private\]/gi,
+  comment: /<!--\s*private\s*-->([\s\S]*?)<!--\s*\/private\s*-->/gi
+};
+
+export function parsePrivateTags(
+  text: string,
+  options: { formats: string[]; marker: string }
+): ParseResult {
+  const sections: PrivateSection[] = [];
+  let filtered = text;
+
+  for (const format of options.formats) {
+    const pattern = TAG_PATTERNS[format];
+    if (!pattern) continue;
+
+    let match;
+    // Reset lastIndex for global regex
+    pattern.lastIndex = 0;
+
+    while ((match = pattern.exec(text)) !== null) {
+      sections.push({
+        start: match.index,
+        end: match.index + match[0].length,
+        content: match[1],
+        format: format as PrivateSection['format']
+      });
+    }
+  }
+
+  // 모든 태그 제거 및 마커로 대체
+  for (const format of options.formats) {
+    const pattern = TAG_PATTERNS[format];
+    filtered = filtered.replace(pattern, (match, content) => {
+      // 빈 태그는 완전히 제거
+      if (!content.trim()) return '';
+      return options.marker;
+    });
+  }
+
+  return {
+    filtered,
+    sections,
+    stats: {
+      count: sections.length,
+      totalLength: sections.reduce((sum, s) => sum + s.content.length, 0)
+    }
+  };
+}
+```
+
+**작업 항목**:
+- [ ] parsePrivateTags 함수 구현
+- [ ] 각 포맷별 정규식 테스트
+- [ ] 중첩 태그 처리
+
+### 1.2 코드 블록 보호
+
+**파일**: `src/core/privacy/tag-parser.ts` 계속
+
+```typescript
+export function parsePrivateTagsSafe(
+  text: string,
+  options: { formats: string[]; marker: string }
+): ParseResult {
+  // 1. 코드 블록 임시 치환
+  const codeBlocks: string[] = [];
+  const textWithPlaceholders = text.replace(
+    /```[\s\S]*?```/g,
+    (match) => {
+      codeBlocks.push(match);
+      return `__CODE_BLOCK_${codeBlocks.length - 1}__`;
+    }
+  );
+
+  // 2. private 태그 파싱
+  const result = parsePrivateTags(textWithPlaceholders, options);
+
+  // 3. 코드 블록 복원
+  result.filtered = result.filtered.replace(
+    /__CODE_BLOCK_(\d+)__/g,
+    (_, idx) => codeBlocks[Number(idx)]
+  );
+
+  return result;
+}
+```
+
+**작업 항목**:
+- [ ] 코드 블록 감지 및 보호
+- [ ] 인라인 코드 처리
+- [ ] 복원 로직
+
+## Phase 2: 설정 통합 (P0)
+
+### 2.1 설정 스키마 확장
+
+**파일**: `src/core/types.ts` 수정
+
+```typescript
+export const PrivateTagsConfigSchema = 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', 'bracket', 'comment'])
+  ).default(['xml'])
+});
+
+// PrivacyConfigSchema 확장
+export const PrivacyConfigSchema = z.object({
+  excludePatterns: z.array(z.string()).default([...]),
+  privateTags: PrivateTagsConfigSchema.optional(),
+  // ...
+});
+```
+
+**작업 항목**:
+- [ ] PrivateTagsConfigSchema 추가
+- [ ] 기본값 설정
+- [ ] 설정 마이그레이션
+
+## Phase 3: 필터링 파이프라인 (P0)
+
+### 3.1 통합 필터
+
+**파일**: `src/core/privacy/filter.ts` (신규 또는 확장)
+
+```typescript
+export interface FilterResult {
+  content: string;
+  metadata: {
+    hasPrivateTags: boolean;
+    privateTagCount: number;
+    patternMatchCount: number;
+    originalLength: number;
+    filteredLength: number;
+  };
+}
+
+export function applyPrivacyFilter(
+  content: string,
+  config: PrivacyConfig
+): FilterResult {
+  let filtered = content;
+  let privateTagCount = 0;
+  let patternMatchCount = 0;
+
+  // 1. Private 태그 필터링
+  if (config.privateTags?.enabled) {
+    const tagResult = parsePrivateTagsSafe(filtered, {
+      formats: config.privateTags.supportedFormats,
+      marker: config.privateTags.marker
+    });
+    filtered = tagResult.filtered;
+    privateTagCount = tagResult.stats.count;
+  }
+
+  // 2. 패턴 기반 필터링
+  for (const pattern of config.excludePatterns) {
+    const regex = new RegExp(
+      `(${pattern})\\s*[:=]\\s*['"]?[^\\s'"]+`,
+      'gi'
+    );
+    const matches = filtered.match(regex);
+    if (matches) {
+      patternMatchCount += matches.length;
+      filtered = filtered.replace(regex, '[REDACTED]');
+    }
+  }
+
+  // 3. 연속 마커 정리
+  filtered = filtered.replace(/(\[PRIVATE\]\s*)+/g, '[PRIVATE]\n');
+  filtered = filtered.replace(/(\[REDACTED\]\s*)+/g, '[REDACTED] ');
+
+  return {
+    content: filtered,
+    metadata: {
+      hasPrivateTags: privateTagCount > 0,
+      privateTagCount,
+      patternMatchCount,
+      originalLength: content.length,
+      filteredLength: filtered.length
+    }
+  };
+}
+```
+
+**작업 항목**:
+- [ ] applyPrivacyFilter 함수 구현
+- [ ] 태그 + 패턴 조합 필터링
+- [ ] 마커 정리 로직
+
+### 3.2 훅 연동
+
+**파일**: `src/hooks/stop.ts` 수정
+
+```typescript
+import { applyPrivacyFilter } from '../core/privacy/filter';
+
+export async function handleStop(input: StopInput): Promise<void> {
+  const memoryService = await MemoryService.getInstance();
+  const config = await memoryService.getConfig();
+
+  // 응답 내용 필터링
+  const filterResult = applyPrivacyFilter(
+    input.response_content,
+    config.privacy
+  );
+
+  // 필터링된 내용 저장
+  await memoryService.storeResponse({
+    content: filterResult.content,
+    privacy: filterResult.metadata
+  });
+}
+```
+
+**작업 항목**:
+- [ ] stop 훅에 필터링 적용
+- [ ] user-prompt-submit 훅에 필터링 적용
+- [ ] 메타데이터 저장
+
+## Phase 4: UI 표시 (P1)
+
+### 4.1 CLI 출력
+
+**파일**: `src/cli/commands/history.ts` 수정
+
+```typescript
+function formatEventContent(event: Event): string {
+  const content = event.payload.content;
+
+  // [PRIVATE] 마커 강조
+  return content.replace(
+    /\[PRIVATE\]/g,
+    chalk.yellow('[🔒 PRIVATE]')
+  );
+}
+```
+
+**작업 항목**:
+- [ ] CLI에서 마커 강조
+- [ ] 통계 표시 옵션
+
+### 4.2 Web Viewer
+
+**파일**: `src/ui/components/EventContent.ts` 수정
+
+```typescript
+function EventContent({ content }) {
+  // [PRIVATE] 마커를 컴포넌트로 변환
+  const parts = content.split(/(\[PRIVATE\])/g);
+
+  return h('div', { class: 'event-content' },
+    parts.map(part =>
+      part === '[PRIVATE]'
+        ? h('span', { class: 'private-marker' }, '🔒 Private content')
+        : h('span', {}, part)
+    )
+  );
+}
+```
+
+**작업 항목**:
+- [ ] 마커를 시각적 컴포넌트로 변환
+- [ ] 툴팁 추가
+
+## Phase 5: 통계 및 모니터링 (P1)
+
+### 5.1 통계 수집
+
+**파일**: `src/services/memory-service.ts` 수정
+
+```typescript
+export class MemoryService {
+  async getPrivacyStats(): Promise<PrivacyStats> {
+    const events = await this.eventStore.query({
+      filter: { 'payload.privacy.hasPrivateTags': true }
+    });
+
+    return {
+      totalPrivateSections: events.reduce(
+        (sum, e) => sum + (e.payload.privacy?.privateTagCount || 0),
+        0
+      ),
+      totalCharactersFiltered: events.reduce(
+        (sum, e) => sum + (
+          (e.payload.privacy?.originalLength || 0) -
+          (e.payload.privacy?.filteredLength || 0)
+        ),
+        0
+      ),
+      sessionsWithPrivate: new Set(events.map(e => e.sessionId)).size
+    };
+  }
+}
+```
+
+**작업 항목**:
+- [ ] 프라이버시 통계 수집
+- [ ] Stats API에 추가
+- [ ] 대시보드 표시
+
+## 파일 목록
+
+### 신규 파일
+```
+src/core/privacy/tag-parser.ts   # 태그 파서
+src/core/privacy/filter.ts       # 통합 필터 (기존 확장 가능)
+```
+
+### 수정 파일
+```
+src/core/types.ts                # 설정 스키마
+src/hooks/stop.ts                # 응답 필터링
+src/hooks/user-prompt-submit.ts  # 프롬프트 필터링
+src/cli/commands/history.ts      # CLI 표시
+src/ui/components/EventContent.ts # Web 표시
+src/services/memory-service.ts   # 통계
+```
+
+## 테스트
+
+### 필수 테스트 케이스
+
+1. **기본 태그 파싱**
+   ```typescript
+   test('should remove private tag content', () => {
+     const result = parsePrivateTags(
+       'before <private>secret</private> after',
+       { formats: ['xml'], marker: '[PRIVATE]' }
+     );
+     expect(result.filtered).toBe('before [PRIVATE] after');
+   });
+   ```
+
+2. **코드 블록 보호**
+   ```typescript
+   test('should not parse tags inside code blocks', () => {
+     const result = parsePrivateTagsSafe(
+       '```\n<private>code</private>\n```',
+       { formats: ['xml'], marker: '[PRIVATE]' }
+     );
+     expect(result.filtered).toContain('<private>code</private>');
+   });
+   ```
+
+3. **불완전한 태그**
+   ```typescript
+   test('should ignore incomplete tags', () => {
+     const result = parsePrivateTags(
+       '<private>no closing tag',
+       { formats: ['xml'], marker: '[PRIVATE]' }
+     );
+     expect(result.filtered).toBe('<private>no closing tag');
+   });
+   ```
+
+4. **빈 태그**
+   ```typescript
+   test('should remove empty tags completely', () => {
+     const result = parsePrivateTags(
+       'text <private></private> more',
+       { formats: ['xml'], marker: '[PRIVATE]' }
+     );
+     expect(result.filtered).toBe('text  more');
+   });
+   ```
+
+## 마일스톤
+
+| 단계 | 완료 기준 |
+|------|----------|
+| M1 | 태그 파서 구현 |
+| M2 | 코드 블록 보호 |
+| M3 | 설정 통합 |
+| M4 | 훅 연동 |
+| M5 | CLI 표시 |
+| M6 | Web 표시 |
+| M7 | 통계 수집 |
+| M8 | 테스트 통과 |
+
+## 2026-02-25T12:31:26.391Z | 42126f8a-c371-4f17-81e0-e1a7a739f342
+- type: session_summary
+- session: import:organized
+# 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에서 적절히 표시