claude-memory-layer 1.0.0

package/specs/post-tool-use-hook/spec.md

@@ -0,0 +1,364 @@
+# PostToolUse Hook Specification
+
+> **Version**: 1.0.0
+> **Status**: Draft
+> **Created**: 2026-02-01
+> **Reference**: claude-mem (thedotmack/claude-mem)
+
+## 1. 개요
+
+### 1.1 문제 정의
+
+현재 시스템에서 도구 사용 결과가 메모리에 저장되지 않음:
+
+1. **도구 실행 컨텍스트 손실**: 파일 읽기/쓰기 결과가 별도로 기록되지 않음
+2. **작업 패턴 학습 불가**: 어떤 도구를 어떤 상황에서 사용했는지 추적 불가
+3. **세션 재구성 어려움**: 과거 세션의 실제 작업 내용 파악 어려움
+
+### 1.2 해결 방향
+
+**PostToolUse 훅 추가**:
+- 도구 실행 직후 호출되는 훅
+- 도구 이름, 입력 파라미터, 출력 결과를 캡처
+- EventStore에 `tool_observation` 이벤트로 저장
+
+## 2. 핵심 개념
+
+### 2.1 훅 라이프사이클
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    Claude Code Session                       │
+├─────────────────────────────────────────────────────────────┤
+│                                                              │
+│  session-start ────────────────────────────────────────────▶│
+│       │                                                      │
+│       ▼                                                      │
+│  user-prompt-submit ◀──────────────────────────────────────┐│
+│       │                                                     ││
+│       ▼                                                     ││
+│  [Agent Processing]                                         ││
+│       │                                                     ││
+│       ├── Tool Execution ─────┐                            ││
+│       │                       ▼                            ││
+│       │              post-tool-use (NEW)                   ││
+│       │                       │                            ││
+│       │◀──────────────────────┘                            ││
+│       │                                                     ││
+│       ▼                                                     ││
+│    stop ───────────────────────────────────────────────────┘│
+│       │                                                      │
+│       ▼                                                      │
+│  session-end                                                 │
+│                                                              │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### 2.2 캡처할 데이터
+
+| 필드 | 타입 | 설명 |
+|------|------|------|
+| tool_name | string | 실행된 도구 이름 (Read, Write, Bash 등) |
+| tool_input | object | 도구에 전달된 파라미터 |
+| tool_output | string | 도구 실행 결과 (truncated) |
+| duration_ms | number | 실행 시간 |
+| success | boolean | 성공/실패 여부 |
+| error_message | string? | 실패 시 에러 메시지 |
+
+### 2.3 지원 도구 목록
+
+```typescript
+type SupportedTool =
+  | 'Read'           // 파일 읽기
+  | 'Write'          // 파일 쓰기
+  | 'Edit'           // 파일 편집
+  | 'Bash'           // 명령 실행
+  | 'Glob'           // 파일 검색
+  | 'Grep'           // 내용 검색
+  | 'WebFetch'       // 웹 요청
+  | 'WebSearch'      // 웹 검색
+  | 'Task'           // 서브에이전트
+  | 'NotebookEdit';  // 노트북 편집
+```
+
+## 3. 이벤트 스키마
+
+### 3.1 ToolObservation 이벤트
+
+```typescript
+const ToolObservationEventSchema = z.object({
+  eventId: z.string().uuid(),
+  eventType: z.literal('tool_observation'),
+  sessionId: z.string(),
+  timestamp: z.date(),
+  payload: z.object({
+    toolName: z.string(),
+    toolInput: z.record(z.unknown()),
+    toolOutput: z.string().max(10000),  // 10KB 제한
+    durationMs: z.number(),
+    success: z.boolean(),
+    errorMessage: z.string().optional(),
+
+    // 컨텍스트
+    promptIndex: z.number(),        // 몇 번째 프롬프트에서 실행됐는지
+    toolIndex: z.number(),          // 해당 프롬프트 내 몇 번째 도구인지
+
+    // 메타데이터 (도구별 특화)
+    metadata: z.object({
+      // Read/Write/Edit
+      filePath: z.string().optional(),
+      fileType: z.string().optional(),
+      lineCount: z.number().optional(),
+
+      // Bash
+      command: z.string().optional(),
+      exitCode: z.number().optional(),
+
+      // Grep/Glob
+      pattern: z.string().optional(),
+      matchCount: z.number().optional(),
+
+      // WebFetch
+      url: z.string().optional(),
+      statusCode: z.number().optional()
+    }).optional()
+  })
+});
+```
+
+### 3.2 도구별 메타데이터 예시
+
+```typescript
+// Read 도구
+{
+  toolName: 'Read',
+  toolInput: { file_path: '/src/core/types.ts' },
+  toolOutput: '// Type definitions...',  // truncated
+  metadata: {
+    filePath: '/src/core/types.ts',
+    fileType: 'typescript',
+    lineCount: 547
+  }
+}
+
+// Bash 도구
+{
+  toolName: 'Bash',
+  toolInput: { command: 'npm test' },
+  toolOutput: 'All 42 tests passed',
+  metadata: {
+    command: 'npm test',
+    exitCode: 0
+  }
+}
+
+// Grep 도구
+{
+  toolName: 'Grep',
+  toolInput: { pattern: 'async function', path: '/src' },
+  toolOutput: 'Found 15 matches in 8 files',
+  metadata: {
+    pattern: 'async function',
+    matchCount: 15
+  }
+}
+```
+
+## 4. 훅 인터페이스
+
+### 4.1 훅 입력
+
+```typescript
+interface PostToolUseHookInput {
+  // Claude Code에서 전달하는 데이터
+  tool_name: string;
+  tool_input: Record<string, unknown>;
+  tool_output: string;
+  tool_error?: string;
+
+  // 세션 컨텍스트
+  session_id: string;
+  conversation_id: string;
+
+  // 타이밍 정보
+  started_at: string;
+  ended_at: string;
+}
+```
+
+### 4.2 훅 출력
+
+```typescript
+interface PostToolUseHookOutput {
+  // 저장 결과
+  stored: boolean;
+  event_id?: string;
+
+  // 선택적 피드백 (Claude에게 전달)
+  feedback?: string;
+
+  // 에러
+  error?: string;
+}
+```
+
+## 5. 프라이버시 필터링
+
+### 5.1 민감 정보 마스킹
+
+```typescript
+const SENSITIVE_PATTERNS = [
+  /password\s*[:=]\s*['"]?[^\s'"]+/gi,
+  /api[_-]?key\s*[:=]\s*['"]?[^\s'"]+/gi,
+  /secret\s*[:=]\s*['"]?[^\s'"]+/gi,
+  /token\s*[:=]\s*['"]?[^\s'"]+/gi,
+  /bearer\s+[a-zA-Z0-9\-_.]+/gi,
+  /-----BEGIN\s+(?:RSA\s+)?PRIVATE\s+KEY-----/gi
+];
+
+function maskSensitiveData(content: string): string {
+  let masked = content;
+  for (const pattern of SENSITIVE_PATTERNS) {
+    masked = masked.replace(pattern, '[REDACTED]');
+  }
+  return masked;
+}
+```
+
+### 5.2 제외할 도구
+
+```typescript
+const EXCLUDED_TOOLS = [
+  'TodoWrite',      // 내부 상태 관리
+  'TodoRead',
+];
+
+function shouldStore(toolName: string): boolean {
+  return !EXCLUDED_TOOLS.includes(toolName);
+}
+```
+
+## 6. 출력 압축
+
+### 6.1 크기 제한
+
+```typescript
+const OUTPUT_LIMITS = {
+  maxLength: 10000,           // 10KB
+  maxLines: 100,              // 100줄
+  truncationMarker: '\n...[TRUNCATED]...\n'
+};
+
+function truncateOutput(output: string): string {
+  const lines = output.split('\n');
+
+  if (lines.length > OUTPUT_LIMITS.maxLines) {
+    const head = lines.slice(0, 50);
+    const tail = lines.slice(-50);
+    return head.join('\n') + OUTPUT_LIMITS.truncationMarker + tail.join('\n');
+  }
+
+  if (output.length > OUTPUT_LIMITS.maxLength) {
+    return output.slice(0, OUTPUT_LIMITS.maxLength / 2) +
+           OUTPUT_LIMITS.truncationMarker +
+           output.slice(-OUTPUT_LIMITS.maxLength / 2);
+  }
+
+  return output;
+}
+```
+
+### 6.2 도구별 압축 전략
+
+| 도구 | 압축 전략 |
+|------|----------|
+| Read | 첫 50줄 + 마지막 50줄, 파일 타입 보존 |
+| Bash | 전체 출력, exitCode 보존 |
+| Grep | 매칭된 파일 목록만, 전체 내용 제외 |
+| Glob | 파일 경로 목록만 |
+| WebFetch | 첫 500자 요약 |
+
+## 7. 벡터 임베딩 연동
+
+### 7.1 임베딩 대상
+
+```typescript
+function createEmbeddingContent(observation: ToolObservation): string {
+  const parts: string[] = [];
+
+  // 도구 이름
+  parts.push(`Tool: ${observation.toolName}`);
+
+  // 주요 입력
+  if (observation.metadata?.filePath) {
+    parts.push(`File: ${observation.metadata.filePath}`);
+  }
+  if (observation.metadata?.command) {
+    parts.push(`Command: ${observation.metadata.command}`);
+  }
+  if (observation.metadata?.pattern) {
+    parts.push(`Pattern: ${observation.metadata.pattern}`);
+  }
+
+  // 결과 요약
+  parts.push(`Result: ${observation.success ? 'Success' : 'Failed'}`);
+
+  return parts.join('\n');
+}
+```
+
+### 7.2 Outbox 연동
+
+```typescript
+// tool_observation도 Outbox에 추가하여 벡터화
+await eventStore.append({
+  eventType: 'tool_observation',
+  payload: observation
+});
+
+// VectorWorker가 배치 처리
+// embedding content: "Tool: Read\nFile: /src/types.ts\nResult: Success"
+```
+
+## 8. 검색 활용
+
+### 8.1 도구 사용 이력 검색
+
+```sql
+-- 특정 파일 관련 도구 사용 이력
+SELECT * FROM events
+WHERE event_type = 'tool_observation'
+  AND JSON_EXTRACT(payload_json, '$.metadata.filePath') LIKE '%types.ts%'
+ORDER BY timestamp DESC
+LIMIT 10;
+
+-- 실패한 도구 실행 조회
+SELECT * FROM events
+WHERE event_type = 'tool_observation'
+  AND JSON_EXTRACT(payload_json, '$.success') = false
+ORDER BY timestamp DESC;
+```
+
+### 8.2 컨텍스트 주입 활용
+
+```typescript
+// user-prompt-submit에서 활용
+async function getRelevantToolHistory(query: string): Promise<ToolObservation[]> {
+  // 벡터 검색으로 관련 도구 사용 이력 조회
+  const results = await vectorStore.search(query, {
+    filter: { eventType: 'tool_observation' },
+    topK: 5
+  });
+
+  return results.map(r => r.payload as ToolObservation);
+}
+```
+
+## 9. 성공 기준
+
+- [ ] PostToolUse 훅이 모든 도구 실행 후 호출됨
+- [ ] tool_observation 이벤트가 EventStore에 저장됨
+- [ ] 민감 정보가 마스킹됨
+- [ ] 출력이 크기 제한 내로 압축됨
+- [ ] 벡터 임베딩이 생성됨
+- [ ] 도구 사용 이력 검색이 가능함

package/specs/private-tags/context.md

@@ -0,0 +1,288 @@
+# 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 (잊혀질 권리)