claude-memory-layer 1.0.11 → 1.0.12

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

@@ -0,0 +1,1164 @@
+
+## 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에 저장됨
+- [ ] 민감 정보가 마스킹됨
+- [ ] 출력이 크기 제한 내로 압축됨
+- [ ] 벡터 임베딩이 생성됨
+- [ ] 도구 사용 이력 검색이 가능함