claude-memory-layer 1.0.27 → 1.0.29

package/memory/specs/post-tool-use-hook/2026-02-25.md

@@ -1,1164 +0,0 @@
-
-## 2026-02-25T12:31:26.351Z | 1fc39ce6-94c1-4ee0-92cd-87b88d81f552
-- type: session_summary
-- session: import:organized
-# PostToolUse Hook Context
-
-> **Version**: 1.0.0
-> **Created**: 2026-02-01
-
-## 1. 배경
-
-### 1.1 claude-mem의 접근 방식
-
-claude-mem 프로젝트는 5개의 라이프사이클 훅을 사용:
-
-```
-SessionStart → UserPromptSubmit → PostToolUse → Stop → SessionEnd
-```
-
-**PostToolUse 훅의 역할** (claude-mem):
-- 모든 도구 실행 결과를 "observation"으로 캡처
-- SQLite + Chroma에 저장하여 검색 가능하게 함
-- 세션 간 도구 사용 패턴 학습
-
-**주요 특징**:
-- 웹 뷰어에서 실시간 observation 스트림 표시
-- 도구별로 다른 압축 전략 적용
-- `<private>` 태그로 민감 정보 제외
-
-### 1.2 현재 code-memory의 상황
-
-현재 4개 훅만 구현:
-
-```
-SessionStart → UserPromptSubmit → Stop → SessionEnd
-```
-
-**부족한 점**:
-1. 도구 실행 결과가 Stop 훅에서 응답 전체로만 저장됨
-2. 개별 도구 실행의 입력/출력 분리 불가
-3. "어떤 도구를 어떻게 사용했는지" 패턴 학습 불가
-
-### 1.3 도입 필요성
-
-| 현재 상황 | PostToolUse 도입 후 |
-|----------|-------------------|
-| 응답 전체만 저장 | 도구별 개별 저장 |
-| 파일 경로 추출 어려움 | 메타데이터로 즉시 조회 |
-| 성공/실패 구분 없음 | success 플래그로 분리 |
-| 검색 시 노이즈 많음 | 도구 타입별 필터링 가능 |
-
-## 2. Claude Code 훅 시스템
-
-### 2.1 지원되는 훅 이벤트
-
-Claude Code가 지원하는 훅 이벤트 목록:
-
-```typescript
-type HookEvent =
-  | 'session-start'       // 세션 시작
-  | 'user-prompt-submit'  // 사용자 프롬프트 제출
-  | 'post-tool-use'       // 도구 사용 후 (NEW)
-  | 'stop'                // 에이전트 응답 완료
-  | 'session-end';        // 세션 종료
-```
-
-### 2.2 post-tool-use 훅 입력 형식
-
-Claude Code가 전달하는 데이터:
-
-```typescript
-interface PostToolUseHookInput {
-  // 도구 정보
-  tool_name: string;           // "Read", "Write", "Bash" 등
-  tool_input: object;          // 도구에 전달된 파라미터
-  tool_output: string;         // 도구 실행 결과
-  tool_error?: string;         // 에러 발생 시 메시지
-
-  // 세션 정보
-  session_id: string;
-  conversation_id: string;
-
-  // 타이밍
-  started_at: string;          // ISO 8601 형식
-  ended_at: string;
-}
-```
-
-### 2.3 훅 등록 방법
-
-`.claude-plugin/hooks.json`:
-
-```json
-{
-  "hooks": [
-    {
-      "event": "post-tool-use",
-      "script": "node dist/hooks/post-tool-use.js",
-      "timeout": 5000
-    }
-  ]
-}
-```
-
-## 3. 참고 구현
-
-### 3.1 claude-mem의 observation 저장
-
-```typescript
-// claude-mem의 접근 방식 (추정)
-interface Observation {
-  id: string;
-  session_id: string;
-  tool_name: string;
-  input: object;
-  output: string;
-  timestamp: Date;
-
-  // 검색을 위한 필드
-  summary: string;        // LLM으로 생성한 요약
-  embedding: number[];    // 벡터 임베딩
-}
-```
-
-### 3.2 도구별 처리 차이
-
-| 도구 | 저장 내용 | 요약 생성 |
-|------|----------|----------|
-| Read | 파일 경로, 첫 N줄 | "Read {path}: {first_line}..." |
-| Write | 파일 경로, 변경 내용 요약 | "Wrote {lines} lines to {path}" |
-| Bash | 명령어, exit code | "Ran `{cmd}`: {status}" |
-| Grep | 패턴, 매칭 파일 수 | "Found {n} matches for {pattern}" |
-
-### 3.3 Progressive Disclosure 활용
-
-```typescript
-// 검색 시 observation을 3단계로 반환
-interface ObservationSearchResult {
-  // Layer 1: ID + 요약 (최소 토큰)
-  layer1: { id: string; summary: string }[];
-
-  // Layer 2: 타임라인 컨텍스트
-  layer2: (ids: string[]) => {
-    id: string;
-    tool_name: string;
-    timestamp: Date;
-  }[];
-
-  // Layer 3: 전체 내용
-  layer3: (ids: string[]) => Observation[];
-}
-```
-
-## 4. 기존 코드와의 관계
-
-### 4.1 event-store.ts
-
-현재 EventStore 스키마:
-
-```sql
-CREATE TABLE events (
-  event_id VARCHAR PRIMARY KEY,
-  event_type VARCHAR NOT NULL,
-  session_id VARCHAR NOT NULL,
-  timestamp TIMESTAMP NOT NULL,
-  payload_json JSON NOT NULL
-);
-```
-
-**확장 필요 없음** - `event_type = 'tool_observation'`으로 저장 가능
-
-### 4.2 types.ts
-
-추가해야 할 타입:
-
-```typescript
-// 기존 EventType
-export const EventTypeSchema = z.enum([
-  'user_prompt',
-  'assistant_response',
-  'session_start',
-  'session_end',
-  'tool_observation'  // 추가
-]);
-
-// ToolObservationPayload 추가
-export const ToolObservationPayloadSchema = z.object({
-  toolName: z.string(),
-  toolInput: z.record(z.unknown()),
-  toolOutput: z.string(),
-  // ...
-});
-```
-
-### 4.3 embedder.ts
-
-현재 임베딩 대상:
-
-```typescript
-function getEmbeddingContent(event: Event): string {
-  switch (event.eventType) {
-    case 'user_prompt':
-      return event.payload.content;
-    case 'assistant_response':
-      return event.payload.content;
-    // tool_observation 추가 필요
-  }
-}
-```
-
-### 4.4 retriever.ts
-
-검색 인터페이스 확장:
-
-```typescript
-// 기존
-async search(query: string): Promise<SearchResult[]>;
-
-// 추가
-async searchToolHistory(query: string): Promise<ToolObservation[]>;
-async getToolsForFile(filePath: string): Promise<ToolObservation[]>;
-```
-
-## 5. 설계 결정 사항
-
-### 5.1 왜 별도 이벤트 타입인가?
-
-**대안 1: assistant_response에 포함**
-```json
-{
-  "eventType": "assistant_response",
-  "payload": {
-    "content": "...",
-    "tools_used": [{ "name": "Read", "output": "..." }]
-  }
-}
-```
-- 단점: 도구별 검색 어려움, 출력이 커짐
-
-**대안 2: 별도 테이블**
-```sql
-CREATE TABLE tool_observations (...);
-```
-- 단점: 스키마 변경 필요, 일관성 관리 복잡
-
-**선택: 기존 events 테이블에 새 event_type**
-- 장점: 스키마 변경 없음
-- 장점: 기존 쿼리 패턴 재사용
-- 장점: 벡터 임베딩 파이프라인 공유
-
-### 5.2 출력 압축 전략
-
-**문제**: 도구 출력이 매우 클 수 있음 (대용량 파일 읽기)
-
-**해결**:
-1. 크기 제한 (10KB)
-2. 줄 수 제한 (100줄)
-3. Head + Tail 방식 (앞 50줄 + 뒤 50줄)
-4. 도구별 특화 압축 (Grep은 파일 목록만)
-
-### 5.3 민감 정보 처리
-
-**현재 privacy.excludePatterns 활용**:
-```typescript
-const patterns = config.privacy.excludePatterns;
-// ['password', 'secret', 'api_key']
-```
-
-**추가 필요**:
-- 정규식 기반 마스킹
-- 환경 변수 값 감지
-- Bearer 토큰 패턴
-
-### 5.4 임베딩 vs 저장만
-
-**질문**: 모든 tool_observation을 임베딩해야 하나?
-
-**결론**: 선택적 임베딩
-- Read/Write: 파일 경로 + 첫 줄만 임베딩
-- Bash: 명령어만 임베딩
-- 전체 출력은 검색되지 않음 (너무 노이즈가 많음)
-
-## 6. 성능 고려사항
-
-### 6.1 훅 실행 시간
-
-**제약**: 훅은 빨리 반환되어야 함 (Claude 응답 지연 방지)
-
-**해결**:
-```typescript
-// 비동기 저장 (fire-and-forget)
-async function handlePostToolUse(input: PostToolUseInput): Promise<void> {
-  // 바로 반환, 저장은 백그라운드
-  setImmediate(async () => {
-    await storeObservation(input);
-  });
-}
-```
-
-### 6.2 저장 빈도
-
-**문제**: 대화 중 수십 개의 도구가 실행될 수 있음
-
-**해결**:
-1. 배치 저장 (10개씩 모아서)
-2. 중복 제거 (같은 파일 연속 Read)
-3. 샘플링 (Glob 결과는 요약만)
-
-### 6.3 벡터 저장소 크기
-
-**문제**: tool_observation이 많아지면 벡터 DB 비대
-
-**해결**:
-1. TTL 적용 (30일 후 삭제)
-2. 자주 사용되는 것만 임베딩 유지
-3. graduation 적용 (L0에서 L4로 승급하는 것만 유지)
-
-## 7. 참고 자료
-
-- **claude-mem README**: 5 lifecycle hooks, observation storage
-- **Claude Code Hooks**: 공식 훅 이벤트 문서
-- **AXIOMMIND**: Principle 2 (Append-Only)
-- **기존 specs**: entity-edge-model, vector-outbox-v2
-
-## 2026-02-25T12:31:26.359Z | cc90cab1-b7d8-4780-9709-42f1f868ed94
-- type: session_summary
-- session: import:organized
-# PostToolUse Hook Implementation Plan
-
-> **Version**: 1.0.0
-> **Status**: Draft
-> **Created**: 2026-02-01
-
-## Phase 1: 타입 정의 (P0)
-
-### 1.1 이벤트 스키마 추가
-
-**파일**: `src/core/types.ts` 수정
-
-```typescript
-// 추가할 타입들
-export const ToolObservationPayloadSchema = z.object({
-  toolName: z.string(),
-  toolInput: z.record(z.unknown()),
-  toolOutput: z.string(),
-  durationMs: z.number(),
-  success: z.boolean(),
-  errorMessage: z.string().optional(),
-  promptIndex: z.number(),
-  toolIndex: z.number(),
-  metadata: z.object({
-    filePath: z.string().optional(),
-    fileType: z.string().optional(),
-    lineCount: z.number().optional(),
-    command: z.string().optional(),
-    exitCode: z.number().optional(),
-    pattern: z.string().optional(),
-    matchCount: z.number().optional(),
-    url: z.string().optional(),
-    statusCode: z.number().optional()
-  }).optional()
-});
-
-export type ToolObservationPayload = z.infer<typeof ToolObservationPayloadSchema>;
-```
-
-**작업 항목**:
-- [ ] ToolObservationPayloadSchema 추가
-- [ ] EventType에 'tool_observation' 추가
-- [ ] EventPayload union에 ToolObservationPayload 추가
-
-### 1.2 설정 스키마 확장
-
-**파일**: `src/core/types.ts` 수정
-
-```typescript
-// 설정에 tool observation 옵션 추가
-export const ConfigSchema = z.object({
-  // ... 기존 설정
-  toolObservation: z.object({
-    enabled: z.boolean().default(true),
-    excludedTools: z.array(z.string()).default(['TodoWrite', 'TodoRead']),
-    maxOutputLength: z.number().default(10000),
-    maxOutputLines: z.number().default(100),
-    storeOnlyOnSuccess: z.boolean().default(false)
-  }).optional()
-});
-```
-
-**작업 항목**:
-- [ ] toolObservation 설정 스키마 추가
-- [ ] 기본값 정의
-
-## Phase 2: 훅 구현 (P0)
-
-### 2.1 PostToolUse 훅 파일 생성
-
-**파일**: `src/hooks/post-tool-use.ts` (신규)
-
-```typescript
-import { MemoryService } from '../services/memory-service';
-import { maskSensitiveData, truncateOutput } from '../core/privacy';
-
-interface PostToolUseInput {
-  tool_name: string;
-  tool_input: Record<string, unknown>;
-  tool_output: string;
-  tool_error?: string;
-  session_id: string;
-  started_at: string;
-  ended_at: string;
-}
-
-export async function handlePostToolUse(input: PostToolUseInput): Promise<void> {
-  const memoryService = await MemoryService.getInstance();
-  const config = await memoryService.getConfig();
-
-  // 1. 제외 도구 체크
-  if (config.toolObservation?.excludedTools?.includes(input.tool_name)) {
-    return;
-  }
-
-  // 2. 실패 시 저장 스킵 옵션
-  const success = !input.tool_error;
-  if (!success && config.toolObservation?.storeOnlyOnSuccess) {
-    return;
-  }
-
-  // 3. 민감 정보 마스킹
-  const maskedOutput = maskSensitiveData(input.tool_output);
-  const maskedInput = maskSensitiveInput(input.tool_input);
-
-  // 4. 출력 압축
-  const truncatedOutput = truncateOutput(maskedOutput, {
-    maxLength: config.toolObservation?.maxOutputLength,
-    maxLines: config.toolObservation?.maxOutputLines
-  });
-
-  // 5. 메타데이터 추출
-  const metadata = extractMetadata(input.tool_name, maskedInput, success);
-
-  // 6. 이벤트 저장
-  await memoryService.storeToolObservation({
-    toolName: input.tool_name,
-    toolInput: maskedInput,
-    toolOutput: truncatedOutput,
-    durationMs: calculateDuration(input.started_at, input.ended_at),
-    success,
-    errorMessage: input.tool_error,
-    metadata
-  });
-}
-```
-
-**작업 항목**:
-- [ ] handlePostToolUse 함수 구현
-- [ ] 제외 도구 체크 로직
-- [ ] 성공/실패 필터링 로직
-- [ ] 메타데이터 추출 함수
-
-### 2.2 프라이버시 유틸리티
-
-**파일**: `src/core/privacy.ts` (신규 또는 확장)
-
-```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,
-];
-
-export function maskSensitiveData(content: string): string {
-  let masked = content;
-  for (const pattern of SENSITIVE_PATTERNS) {
-    masked = masked.replace(pattern, '[REDACTED]');
-  }
-  return masked;
-}
-
-export function truncateOutput(
-  output: string,
-  options: { maxLength?: number; maxLines?: number }
-): string {
-  const { maxLength = 10000, maxLines = 100 } = options;
-  // ... 구현
-}
-```
-
-**작업 항목**:
-- [ ] maskSensitiveData 함수
-- [ ] maskSensitiveInput 함수 (JSON 재귀 마스킹)
-- [ ] truncateOutput 함수
-- [ ] 도구별 압축 전략 구현
-
-### 2.3 메타데이터 추출기
-
-**파일**: `src/core/metadata-extractor.ts` (신규)
-
-```typescript
-export function extractMetadata(
-  toolName: string,
-  input: Record<string, unknown>,
-  success: boolean
-): ToolMetadata {
-  switch (toolName) {
-    case 'Read':
-    case 'Write':
-    case 'Edit':
-      return {
-        filePath: input.file_path as string,
-        fileType: getFileType(input.file_path as string)
-      };
-
-    case 'Bash':
-      return {
-        command: input.command as string
-      };
-
-    case 'Grep':
-      return {
-        pattern: input.pattern as string
-      };
-
-    // ... 기타 도구
-
-    default:
-      return {};
-  }
-}
-```
-
-**작업 항목**:
-- [ ] extractMetadata 함수
-- [ ] 도구별 메타데이터 추출 로직
-- [ ] getFileType 유틸리티
-
-## Phase 3: 서비스 연동 (P0)
-
-### 3.1 MemoryService 확장
-
-**파일**: `src/services/memory-service.ts` 수정
-
-```typescript
-export class MemoryService {
-  // 기존 메서드들...
-
-  async storeToolObservation(observation: ToolObservationPayload): Promise<string> {
-    const eventId = await this.eventStore.append({
-      eventType: 'tool_observation',
-      sessionId: this.currentSessionId,
-      payload: observation
-    });
-
-    // 임베딩을 위한 outbox 추가
-    await this.eventStore.addToOutbox(eventId);
-
-    return eventId;
-  }
-}
-```
-
-**작업 항목**:
-- [ ] storeToolObservation 메서드 추가
-- [ ] Outbox 연동
-
-### 3.2 임베딩 콘텐츠 생성
-
-**파일**: `src/core/embedder.ts` 수정
-
-```typescript
-export function createEmbeddingContent(event: Event): string {
-  if (event.eventType === 'tool_observation') {
-    return createToolObservationEmbedding(event.payload);
-  }
-  // 기존 로직...
-}
-
-function createToolObservationEmbedding(payload: ToolObservationPayload): string {
-  const parts: string[] = [];
-
-  parts.push(`Tool: ${payload.toolName}`);
-
-  if (payload.metadata?.filePath) {
-    parts.push(`File: ${payload.metadata.filePath}`);
-  }
-  if (payload.metadata?.command) {
-    parts.push(`Command: ${payload.metadata.command}`);
-  }
-  if (payload.metadata?.pattern) {
-    parts.push(`Pattern: ${payload.metadata.pattern}`);
-  }
-
-  parts.push(`Result: ${payload.success ? 'Success' : 'Failed'}`);
-
-  return parts.join('\n');
-}
-```
-
-**작업 항목**:
-- [ ] tool_observation 이벤트용 임베딩 콘텐츠 생성
-- [ ] VectorWorker에서 tool_observation 처리
-
-## Phase 4: 훅 등록 (P0)
-
-### 4.1 hooks.json 수정
-
-**파일**: `.claude-plugin/hooks.json` 수정
-
-```json
-{
-  "hooks": [
-    {
-      "event": "session-start",
-      "script": "node dist/hooks/session-start.js"
-    },
-    {
-      "event": "user-prompt-submit",
-      "script": "node dist/hooks/user-prompt-submit.js"
-    },
-    {
-      "event": "post-tool-use",
-      "script": "node dist/hooks/post-tool-use.js"
-    },
-    {
-      "event": "stop",
-      "script": "node dist/hooks/stop.js"
-    },
-    {
-      "event": "session-end",
-      "script": "node dist/hooks/session-end.js"
-    }
-  ]
-}
-```
-
-**작업 항목**:
-- [ ] post-tool-use 훅 등록
-- [ ] 스크립트 경로 확인
-
-### 4.2 빌드 스크립트 수정
-
-**파일**: `package.json` 또는 빌드 설정
-
-```json
-{
-  "scripts": {
-    "build:hooks": "esbuild src/hooks/*.ts --bundle --platform=node --outdir=dist/hooks"
-  }
-}
-```
-
-**작업 항목**:
-- [ ] post-tool-use.ts 빌드 포함
-- [ ] 번들 테스트
-
-## Phase 5: 검색 연동 (P1)
-
-### 5.1 Retriever 확장
-
-**파일**: `src/core/retriever.ts` 수정
-
-```typescript
-export class Retriever {
-  async searchToolHistory(query: string, options?: SearchOptions): Promise<ToolObservation[]> {
-    const vectorResults = await this.vectorStore.search(query, {
-      filter: { eventType: 'tool_observation' },
-      topK: options?.topK ?? 5
-    });
-
-    return vectorResults.map(r => r.payload as ToolObservation);
-  }
-
-  async getRecentToolsForFile(filePath: string): Promise<ToolObservation[]> {
-    // 특정 파일 관련 최근 도구 사용 조회
-    return this.eventStore.query({
-      eventType: 'tool_observation',
-      filter: { 'payload.metadata.filePath': filePath },
-      orderBy: 'timestamp DESC',
-      limit: 10
-    });
-  }
-}
-```
-
-**작업 항목**:
-- [ ] searchToolHistory 메서드
-- [ ] getRecentToolsForFile 메서드
-- [ ] 필터링 옵션
-
-### 5.2 user-prompt-submit 확장
-
-**파일**: `src/hooks/user-prompt-submit.ts` 수정
-
-```typescript
-async function handleUserPromptSubmit(input: UserPromptInput): Promise<HookOutput> {
-  // 기존 메모리 검색
-  const memories = await retriever.search(input.prompt);
-
-  // 관련 도구 사용 이력 추가
-  const toolHistory = await retriever.searchToolHistory(input.prompt, { topK: 3 });
-
-  // 컨텍스트 조합
-  return {
-    context: formatContext(memories, toolHistory)
-  };
-}
-```
-
-**작업 항목**:
-- [ ] 도구 이력을 컨텍스트에 포함
-- [ ] 포맷팅 함수 확장
-
-## 파일 목록
-
-### 신규 파일
-```
-src/hooks/post-tool-use.ts       # 메인 훅 구현
-src/core/privacy.ts              # 프라이버시 유틸리티
-src/core/metadata-extractor.ts   # 메타데이터 추출
-```
-
-### 수정 파일
-```
-src/core/types.ts                # ToolObservationPayload 추가
-src/services/memory-service.ts   # storeToolObservation 메서드
-src/core/embedder.ts             # 임베딩 콘텐츠 생성
-src/core/retriever.ts            # 도구 이력 검색
-src/hooks/user-prompt-submit.ts  # 컨텍스트 포함
-.claude-plugin/hooks.json        # 훅 등록
-```
-
-## 테스트
-
-### 필수 테스트 케이스
-
-1. **훅 호출 테스트**
-   ```typescript
-   test('should store tool observation after Read', async () => {
-     await handlePostToolUse({
-       tool_name: 'Read',
-       tool_input: { file_path: '/test.ts' },
-       tool_output: 'file content...',
-       session_id: 'session_1',
-       started_at: '2026-02-01T10:00:00Z',
-       ended_at: '2026-02-01T10:00:01Z'
-     });
-
-     const events = await eventStore.query({ eventType: 'tool_observation' });
-     expect(events.length).toBe(1);
-   });
-   ```
-
-2. **민감 정보 마스킹**
-   ```typescript
-   test('should mask sensitive data', () => {
-     const input = 'password=secret123';
-     const masked = maskSensitiveData(input);
-     expect(masked).toBe('[REDACTED]');
-   });
-   ```
-
-3. **제외 도구 스킵**
-   ```typescript
-   test('should skip excluded tools', async () => {
-     await handlePostToolUse({
-       tool_name: 'TodoWrite',
-       // ...
-     });
-
-     const events = await eventStore.query({ eventType: 'tool_observation' });
-     expect(events.length).toBe(0);
-   });
-   ```
-
-4. **출력 압축**
-   ```typescript
-   test('should truncate long output', () => {
-     const longOutput = 'x'.repeat(20000);
-     const truncated = truncateOutput(longOutput, { maxLength: 10000 });
-     expect(truncated.length).toBeLessThanOrEqual(10100);  // marker 포함
-   });
-   ```
-
-## 마일스톤
-
-| 단계 | 완료 기준 |
-|------|----------|
-| M1 | 타입 정의 완료 |
-| M2 | 훅 기본 구현 (저장만) |
-| M3 | 프라이버시 필터링 |
-| M4 | 출력 압축 |
-| M5 | 임베딩 연동 |
-| M6 | 검색 연동 |
-| M7 | 테스트 통과 |
-
-## 2026-02-25T12:31:26.368Z | 3d75016f-3046-478d-b3b2-24f067ad5f4d
-- type: session_summary
-- session: import:organized
-# 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에 저장됨
-- [ ] 민감 정보가 마스킹됨
-- [ ] 출력이 크기 제한 내로 압축됨
-- [ ] 벡터 임베딩이 생성됨
-- [ ] 도구 사용 이력 검색이 가능함