claude-memory-layer 1.0.31 → 1.0.33

package/specs/private-tags/spec.md

@@ -1,345 +0,0 @@
-# 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

@@ -1,346 +0,0 @@
-# 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 구현