claude-memory-layer 1.0.31 → 1.0.32

package/specs/selective-tool-observation/spec.md

@@ -1,127 +0,0 @@
-# Spec: Selective Storage Filtering
-
-## 개요
-
-모든 이벤트 타입에 걸쳐 메모리 가치가 낮은 데이터를 선별적으로 필터링하여
-저장량 55% 감소, 임베딩 backlog 해소, retrieval 품질 향상을 목표로 한다.
-
-## 목표
-
-- 전체 이벤트 저장량 **-55%** (10,536 → ~4,693)
-- 임베딩 pending 증가 속도 감소
-- retrieval signal-to-noise 향상
-- Ctrl+C, 메뉴번호 같은 쓰레기 데이터 제거
-
-## 비목표
-
-- 저장 스키마 변경 없음
-- 기존 저장된 이벤트 소급 삭제 없음
-- session_summary 로직 변경 없음
-
----
-
-## 필터 규칙 1: tool_observation (post-tool-use.ts)
-
-### Blocklist 확장
-
-**추가 제외 도구** (현재: TodoWrite, TodoRead만 제외):
-
-```
-Read, Grep, Glob, ToolSearch,
-WebFetch, WebSearch, NotebookRead,
-Skill, EnterPlanMode,
-mcp__*  (MCP 도구 전체, 조건부 예외 적용)
-```
-
-**항상 저장 (allowlist)**:
-- `Write`, `Edit`, `MultiEdit` — 파일 변경 기록
-- `Agent`, `Task` — 서브태스크 결과
-- `Bash` — 조건부 (output 필터 적용)
-- `ExitPlanMode` — 계획 완료 기록 (조건부)
-
-### Output-level 필터 (Bash 등 조건부 도구)
-
-| 조건 | 동작 |
-|------|------|
-| `stderr` 존재 | 저장 (에러 컨텍스트) |
-| `stdout` 길이 ≥ 100 chars | 저장 |
-| Write/Edit/Agent/Task | 길이 무관 저장 |
-| 그 외 | 스킵 |
-
-### 환경변수
-
-```bash
-CLAUDE_MEMORY_TOOL_BLOCKLIST="Read,Grep,Glob,..."   # 커스텀 blocklist
-CLAUDE_MEMORY_TOOL_MIN_OUTPUT_LEN=100               # Bash 최소 출력 길이
-```
-
----
-
-## 필터 규칙 2: agent_response (stop.ts)
-
-### Min-length 필터
-
-**150자 미만 agent_response는 저장 안 함**
-
-근거: 50자 미만 608개 (27%), 50~200자 587개 (26%) 가 도구 체인 전환 메시지.
-독립적 retrieval 가치 없음.
-
-```bash
-CLAUDE_MEMORY_AGENT_RESPONSE_MIN_LEN=150  # 기본값
-```
-
-**예외 (짧아도 저장):**
-- 세션의 마지막 agent_response (최종 답변일 가능성)
-
----
-
-## 필터 규칙 3: user_prompt (importer + hook)
-
-### 임포터에 shouldStorePrompt() 적용
-
-현재 import 시 transcript의 모든 user 메시지를 무조건 저장.
-Ctrl+C(`\x03`), 숫자 `'1'`, `'go'` 등이 저장되는 원인.
-
-**변경:** `session-history-importer.ts`에서 각 user_prompt 저장 전
-`shouldStorePrompt()` 동일 조건 적용:
-- 길이 < 15자 → 스킵
-- `/`로 시작 → 스킵
-- 제어문자 포함 → 스킵
-- 한글/영문 2글자 이상 포함 여부 확인
-
----
-
-## 적용 파일
-
-| 파일 | 변경 |
-|------|------|
-| `src/hooks/post-tool-use.ts` | blocklist 확장 + output-level 필터 |
-| `src/hooks/stop.ts` | agent_response min-length 필터 |
-| `src/services/session-history-importer.ts` | shouldStorePrompt() 임포트 적용 |
-
----
-
-## 판단 흐름
-
-```
-[PostToolUse]
-  tool_name이 blocklist? → 스킵
-  tool_name이 allowlist(Write/Edit/Agent/Task)? → 저장
-  Bash/기타: output length ≥ 100 OR stderr 있음? → 저장 else 스킵
-
-[Stop - agent_response]
-  마지막 메시지? → 저장
-  length ≥ 150? → 저장 else 스킵
-
-[Importer - user_prompt]
-  shouldStorePrompt() 통과? → 저장 else 스킵
-```
-
----
-
-## 성공 지표
-
-- 신규 세션 tool_observation 비율 < 40% (현재 68.5%)
-- agent_response 저장 비율 < 50% (현재 전량 저장)
-- user_prompt 쓰레기 입력 0건
-- 임베딩 pending 증가 속도 현재 대비 -50%

package/specs/task-entity-system/context.md

@@ -1,297 +0,0 @@
-# Task Entity System Context
-
-> **Version**: 1.0.0
-> **Created**: 2026-01-31
-
-## 1. 배경
-
-### 1.1 기존 설계의 한계
-
-현재 code-memory 시스템에서 Task는 `entries` 테이블에 저장되는 불변 기록으로 관리됩니다:
-
-```typescript
-// 기존: entries 테이블에 Task를 저장
-{
-  entry_id: "ent_abc123",
-  entry_type: "task",
-  title: "벡터 검색 구현",
-  content_json: { status: "in_progress", ... }
-}
-```
-
-**문제점**:
-
-1. **세션 A**에서 "벡터 검색 구현" Task 생성 → `ent_abc123`
-2. **세션 B**에서 같은 Task 언급 → `ent_def456` (새 entry 생성!)
-3. **세션 C**에서 "완료" 언급 → `ent_ghi789` (또 새 entry!)
-
-결과: 하나의 Task가 3개의 분리된 entry로 존재하며, 상태 추적 불가
-
-### 1.2 해결 방향
-
-**Entry와 Entity 분리**:
-
-| 구분 | Entry | Entity |
-|------|-------|--------|
-| 특성 | 불변 기록 | 상태 변화 개체 |
-| 예시 | Fact, Decision, Insight | Task, Condition, Artifact |
-| 생명주기 | 생성 후 변경 없음 | 이벤트로 상태 변화 |
-| 식별 | UUID | canonical_key |
-
-## 2. Memo.txt 참고 사항
-
-### 2.1 핵심 원칙 (섹션 2)
-
-> **5. Task는 entity**
-> - Task 상태(status/priority/blockers)는 이벤트 fold 결과로 계산
-> - 세션마다 Task entry를 새로 만들지 말고, 기존 task entity를 찾아 업데이트
-
-### 2.2 DB 스키마 (섹션 4.3)
-
-```sql
-CREATE TABLE entities (
-  entity_id      VARCHAR PRIMARY KEY,
-  entity_type    VARCHAR NOT NULL,       -- task|condition|artifact
-  canonical_key  VARCHAR NOT NULL,
-  title          VARCHAR NOT NULL,
-  stage          VARCHAR NOT NULL,
-  status         VARCHAR NOT NULL,
-  current_json   JSON NOT NULL,
-  ...
-);
-```
-
-### 2.3 Task 이벤트 타입 (섹션 7.2)
-
-- `task_created`
-- `task_status_changed`
-- `task_priority_changed`
-- `task_blockers_set` (mode=replace|suggest)
-- `task_transition_rejected`
-
-### 2.4 BlockerResolver 규칙 (섹션 7.3)
-
-1. 강한 ID/URL/키 패턴 → artifact로 get-or-create
-2. 명시 task_id → task로 연결
-3. Task 제목 매칭 실패 → **condition으로 fallback** (스텁 Task 생성 금지)
-
-## 3. Idris2 영감 적용
-
-### 3.1 의존적 타입 개념
-
-**Idris2의 Vector 타입**:
-```idris
--- 길이가 타입에 인코딩됨
-data Vect : Nat -> Type -> Type where
-  Nil  : Vect 0 a
-  (::) : a -> Vect n a -> Vect (S n) a
-```
-
-**TypeScript 적용**:
-```typescript
-// 상태에 따라 blockers 필드 타입이 달라짐
-type TaskState =
-  | { status: 'blocked'; blockers: BlockerRef[] }  // 필수, 1개 이상
-  | { status: 'done'; blockers?: never };          // 없어야 함
-```
-
-### 3.2 불변식 (Invariants)
-
-**Idris2에서**:
-```idris
--- 타입 시스템이 강제
-nonEmptyBlockers : (t : Task) -> t.status = Blocked -> NonEmpty t.blockers
-```
-
-**TypeScript + Zod에서**:
-```typescript
-// 런타임 검증
-const BlockedTaskSchema = z.object({
-  status: z.literal('blocked'),
-  blockers: z.array(BlockerRefSchema).min(1)  // 최소 1개 강제
-});
-```
-
-### 3.3 왜 실제 Idris2를 사용하지 않는가?
-
-**Memo.txt 섹션 11**:
-> "지금은 Python 쪽 구현이 핵심이므로, Idris는 Candidate/Verified 래퍼 기반으로만 최소 수정"
-
-**실용적 이유**:
-
-1. **학습 곡선**: 팀원 모두가 Idris2를 학습해야 함
-2. **도구 체인**: idris2 컴파일러 설치/관리 필요
-3. **통합 복잡도**: TypeScript ↔ Idris2 FFI 오버헤드
-4. **디버깅**: 두 언어 간 스택 트레이스 추적 어려움
-
-**TypeScript로 충분한 이유**:
-
-1. **Discriminated Union**: 상태별 타입 분리 가능
-2. **Zod**: 런타임 검증으로 불변식 강제
-3. **타입 가드**: 조건부 타입 narrowing
-4. **생태계**: 풍부한 라이브러리와 도구
-
-## 4. 기존 코드와의 관계
-
-### 4.1 types.ts
-
-현재 정의된 타입 활용:
-
-```typescript
-// 기존
-export type MatchConfidence = 'high' | 'suggested' | 'none';
-export const MATCH_THRESHOLDS = {
-  minCombinedScore: 0.92,
-  minGap: 0.03,
-  suggestionThreshold: 0.75
-};
-
-// 확장
-export type EntityType = 'task' | 'condition' | 'artifact';
-export type TaskStatus = 'pending' | 'in_progress' | 'blocked' | 'done' | 'cancelled';
-```
-
-### 4.2 canonical-key.ts
-
-현재 함수 확장:
-
-```typescript
-// 기존: 이벤트용 canonical key
-export function makeCanonicalKey(title: string, context?: {...}): string;
-
-// 확장: 엔티티 타입별 canonical key
-export function makeEntityCanonicalKey(
-  entityType: EntityType,
-  identifier: string,
-  context?: { project?: string }
-): string {
-  switch (entityType) {
-    case 'task':
-      return `task:${context?.project ?? 'default'}:${normalize(identifier)}`;
-    case 'condition':
-      return `cond:${context?.project ?? 'default'}:${normalize(identifier)}`;
-    case 'artifact':
-      return makeArtifactKey(identifier);
-  }
-}
-```
-
-### 4.3 event-store.ts
-
-현재 EventStore 활용:
-
-```typescript
-// 기존 append 메서드 재활용
-// Task 이벤트도 동일하게 append-only로 저장
-const event = {
-  eventType: 'task_created',
-  sessionId,
-  content: JSON.stringify(payload),
-  ...
-};
-await eventStore.append(event);
-```
-
-### 4.4 matcher.ts
-
-현재 Matcher 로직 확장:
-
-```typescript
-// 기존: 이벤트 매칭
-export class Matcher {
-  matchSearchResults(results: SearchResult[]): MatchResult;
-}
-
-// 확장: Task 매칭에도 동일 로직 적용
-export class TaskMatcher {
-  // MATCH_THRESHOLDS 재활용
-  findSimilar(title: string, project: string): MatchResult;
-}
-```
-
-## 5. 경계 조건
-
-### 5.1 Unknown Blocker 처리
-
-```typescript
-// Task가 blocked인데 blockedBy가 비어있으면
-if (task.status === 'blocked' && blockedByTexts.length === 0) {
-  // 자동으로 placeholder condition 생성
-  const placeholder = await createCondition({
-    text: `Unknown blocker for ${task.title}`,
-    meta: { auto_placeholder: true }
-  });
-  blockers.push({ kind: 'condition', entity_id: placeholder.id });
-}
-```
-
-### 5.2 상태 전이 거부
-
-```typescript
-// pending → done 직접 전이 시
-if (from === 'pending' && to === 'done') {
-  // task_transition_rejected 이벤트 발행
-  await eventStore.append({
-    eventType: 'task_transition_rejected',
-    content: JSON.stringify({
-      task_id: task.id,
-      from_status: 'pending',
-      to_status: 'done',
-      reason: 'Direct transition from pending to done is not allowed'
-    })
-  });
-
-  // in_progress로 보정
-  return 'in_progress';
-}
-```
-
-### 5.3 Condition → Task 해결
-
-```typescript
-// 나중에 "API 키 설정됨" condition이 실제 Task로 식별되면
-await eventStore.append({
-  eventType: 'condition_resolved_to',
-  content: JSON.stringify({
-    condition_id: 'cond_xyz',
-    resolved_to: { kind: 'task', entity_id: 'task_abc' }
-  })
-});
-```
-
-## 6. 성능 고려사항
-
-### 6.1 캐싱
-
-```typescript
-// Entity 조회 캐시 (LRU)
-const entityCache = new LRUCache<string, Entity>({
-  max: 1000,
-  ttl: 1000 * 60 * 5  // 5분
-});
-```
-
-### 6.2 배치 처리
-
-```typescript
-// Projector는 배치로 이벤트 처리
-const BATCH_SIZE = 100;
-const events = await eventStore.fetchSince(offset, { limit: BATCH_SIZE });
-```
-
-### 6.3 인덱스 활용
-
-```sql
--- FTS 검색용
-CREATE INDEX idx_entities_search ON entities USING GIN(to_tsvector('english', search_text));
-
--- canonical_key 조회용
-CREATE INDEX idx_entities_type_key ON entities(entity_type, canonical_key);
-```
-
-## 7. 참고 자료
-
-- **Memo.txt**: AxiomMind Memory Graduation Pipeline 지시서
-- **spec.md**: `src/core/types.ts` - 기존 타입 정의
-- **AXIOMMIND 원칙**: Principle 5 - Task는 Entity
-- **Idris2 개념**: Dependent types, Linear types

package/specs/task-entity-system/plan.md

@@ -1,301 +0,0 @@
-# Task Entity System Implementation Plan
-
-> **Version**: 1.0.0
-> **Status**: Draft
-> **Created**: 2026-01-31
-
-## Phase 1: 기반 구조 (P0)
-
-### 1.1 타입 정의
-
-**파일**: `src/core/types.ts` 수정
-
-```typescript
-// 추가할 타입들
-export const EntityTypeSchema = z.enum(['task', 'condition', 'artifact']);
-export type EntityType = z.infer<typeof EntityTypeSchema>;
-
-export const TaskStatusSchema = z.enum(['pending', 'in_progress', 'blocked', 'done', 'cancelled']);
-export type TaskStatus = z.infer<typeof TaskStatusSchema>;
-
-export const TaskEventTypeSchema = z.enum([
-  'task_created',
-  'task_status_changed',
-  'task_priority_changed',
-  'task_blockers_set',
-  'task_transition_rejected'
-]);
-```
-
-**작업 항목**:
-- [ ] EntityType, TaskStatus 스키마 추가
-- [ ] TaskEvent 타입 정의
-- [ ] BlockerRef 타입 정의
-- [ ] TaskState Discriminated Union 정의
-
-### 1.2 DB 스키마 추가
-
-**파일**: `src/core/schema.sql` 수정
-
-**작업 항목**:
-- [ ] entities 테이블 생성
-- [ ] entity_aliases 테이블 생성
-- [ ] edges 테이블 생성
-- [ ] 인덱스 추가
-
-### 1.3 Canonical Key 확장
-
-**파일**: `src/core/canonical-key.ts` 수정
-
-```typescript
-// 추가할 함수
-export function makeEntityCanonicalKey(
-  entityType: EntityType,
-  identifier: string,
-  context?: { project?: string }
-): string;
-```
-
-**작업 항목**:
-- [ ] Task canonical key 함수
-- [ ] Condition canonical key 함수
-- [ ] Artifact canonical key 함수 (URL, JIRA, GitHub 패턴)
-
-## Phase 2: 핵심 컴포넌트 (P0)
-
-### 2.1 EntityRepository
-
-**파일**: `src/core/entity-repo.ts` (신규)
-
-```typescript
-export class EntityRepository {
-  constructor(private db: Database);
-
-  // CRUD (Create, Read만 - append-only 철학)
-  async create(entity: EntityInput): Promise<Entity>;
-  async findById(entityId: string): Promise<Entity | null>;
-  async findByCanonicalKey(type: EntityType, key: string): Promise<Entity | null>;
-
-  // 검색
-  async findSimilar(type: EntityType, searchText: string): Promise<Entity[]>;
-
-  // Alias 관리
-  async addAlias(entityId: string, alias: string): Promise<void>;
-  async resolveAlias(type: EntityType, alias: string): Promise<string | null>;
-
-  // 상태 업데이트 (이벤트 발행 후 projector가 호출)
-  async updateCurrentState(entityId: string, state: EntityState): Promise<void>;
-}
-```
-
-**작업 항목**:
-- [ ] EntityRepository 클래스 구현
-- [ ] findByCanonicalKey 구현
-- [ ] findSimilar 구현 (FTS 활용)
-- [ ] alias 관리 메서드 구현
-
-### 2.2 TaskMatcher
-
-**파일**: `src/core/task-matcher.ts` (신규)
-
-```typescript
-export class TaskMatcher {
-  constructor(
-    private entityRepo: EntityRepository,
-    private vectorStore: VectorStore
-  );
-
-  async findExact(canonicalKey: string): Promise<Task | null>;
-  async findSimilar(title: string, project: string): Promise<MatchResult>;
-  async suggestCandidates(title: string, project: string, limit?: number): Promise<Task[]>;
-}
-```
-
-**작업 항목**:
-- [ ] 정확 매칭 (entity_aliases 활용)
-- [ ] FTS 기반 유사 매칭
-- [ ] Vector 기반 semantic 매칭
-- [ ] 점수 계산 (stage weight, status weight, recency)
-- [ ] strict 확정 로직 (score >= 0.92, gap >= 0.03)
-
-### 2.3 BlockerResolver
-
-**파일**: `src/core/blocker-resolver.ts` (신규)
-
-**작업 항목**:
-- [ ] URL/JIRA/GitHub 패턴 감지
-- [ ] Artifact get-or-create 로직
-- [ ] Task 제목 매칭 시도
-- [ ] Condition fallback 생성
-- [ ] candidates 저장 로직
-
-### 2.4 TaskResolver
-
-**파일**: `src/core/task-resolver.ts` (신규)
-
-**작업 항목**:
-- [ ] Task entry 처리 로직
-- [ ] 기존 Task 찾기 (TaskMatcher 활용)
-- [ ] 이벤트 발행 로직
-- [ ] 상태 전이 검증
-- [ ] blockers 정규화 (BlockerResolver 활용)
-
-## Phase 3: Projection (P0)
-
-### 3.1 TaskProjector
-
-**파일**: `src/core/task-projector.ts` (신규)
-
-```typescript
-export class TaskProjector {
-  constructor(
-    private eventStore: EventStore,
-    private entityRepo: EntityRepository,
-    private edgeRepo: EdgeRepository
-  );
-
-  async projectIncremental(): Promise<ProjectionResult>;
-  async rebuild(): Promise<void>;
-
-  private async handleTaskCreated(event: TaskEvent): Promise<void>;
-  private async handleStatusChanged(event: TaskEvent): Promise<void>;
-  private async handleBlockersSet(event: TaskEvent): Promise<void>;
-}
-```
-
-**작업 항목**:
-- [ ] projection_offsets 관리
-- [ ] 증분 이벤트 읽기
-- [ ] 이벤트 타입별 핸들러
-- [ ] mode=replace 처리 (기존 edge 삭제 + 새 edge 삽입)
-- [ ] mode=suggest 처리 (suggested edge만)
-- [ ] current_json 갱신
-
-### 3.2 EdgeRepository
-
-**파일**: `src/core/edge-repo.ts` (신규)
-
-```typescript
-export class EdgeRepository {
-  async createEdge(edge: EdgeInput): Promise<Edge>;
-  async findEdges(srcId: string, relType?: string): Promise<Edge[]>;
-  async deleteEdges(srcId: string, relType: string): Promise<number>;
-  async replaceEdges(srcId: string, relType: string, newEdges: EdgeInput[]): Promise<void>;
-}
-```
-
-**작업 항목**:
-- [ ] Edge CRUD 구현
-- [ ] 관계 타입별 조회
-- [ ] replace 로직 (트랜잭션)
-
-## Phase 4: 통합 (P0)
-
-### 4.1 Graduation Pipeline 연동
-
-**파일**: `src/core/graduation.ts` 수정
-
-**작업 항목**:
-- [ ] Task entry 처리 시 TaskResolver 호출
-- [ ] 이벤트 발행 후 TaskProjector 호출
-- [ ] evidence edge 생성 로직
-
-### 4.2 EventStore 확장
-
-**파일**: `src/core/event-store.ts` 수정
-
-**작업 항목**:
-- [ ] Task 이벤트 타입 지원
-- [ ] fetch_since 메서드 추가 (projector용)
-- [ ] replay 메서드 추가 (rebuild용)
-
-## Phase 5: CLI 및 조회 (P1)
-
-### 5.1 조회 API
-
-**작업 항목**:
-- [ ] list_blocked_tasks()
-- [ ] list_tasks_with_only_suggested_blockers()
-- [ ] get_task_detail(task_id)
-- [ ] v_task_blockers_effective 뷰
-
-### 5.2 CLI 커맨드
-
-**파일**: `src/cli/index.ts` 수정
-
-**작업 항목**:
-- [ ] `cli blocked` - blocked task 목록
-- [ ] `cli task show <task_id>` - task 상세
-- [ ] `cli tasks --status <status>` - 상태별 목록
-
-## 파일 목록
-
-### 신규 파일
-```
-src/core/entity-repo.ts
-src/core/edge-repo.ts
-src/core/task-matcher.ts
-src/core/blocker-resolver.ts
-src/core/task-resolver.ts
-src/core/task-projector.ts
-```
-
-### 수정 파일
-```
-src/core/types.ts
-src/core/canonical-key.ts
-src/core/event-store.ts
-src/core/graduation.ts
-src/cli/index.ts
-```
-
-## 테스트
-
-### 필수 테스트 케이스
-
-1. **Task 동일성**
-   - 같은 제목의 Task가 여러 세션에서 언급되어도 하나의 Entity로 관리
-
-2. **상태 전이**
-   - pending → done 직접 전이 시 에러
-   - blocked 상태에서 blockers가 비어있으면 에러
-
-3. **Idempotency**
-   - 동일 세션 재처리 시 중복 이벤트 없음
-   - 동일 edge 중복 생성 없음
-
-4. **Blocker 해결**
-   - URL → Artifact 정상 생성
-   - Task 제목 매칭 실패 → Condition 생성 + candidates 저장
-
-## 의존성 그래프
-
-```
-types.ts
-    │
-    ├── entity-repo.ts
-    │       │
-    │       ├── task-matcher.ts
-    │       │
-    │       └── edge-repo.ts
-    │               │
-    │               └── task-projector.ts
-    │
-    ├── blocker-resolver.ts ─────────┐
-    │                                │
-    └── task-resolver.ts ◀───────────┘
-            │
-            └── graduation.ts
-```
-
-## 마일스톤
-
-| 단계 | 완료 기준 |
-|------|----------|
-| M1 | 타입 정의 + DB 스키마 |
-| M2 | EntityRepo + EdgeRepo 동작 |
-| M3 | TaskMatcher 동작 (정확 매칭만) |
-| M4 | BlockerResolver + TaskResolver 동작 |
-| M5 | TaskProjector 동작 (증분 처리) |
-| M6 | Graduation 연동 완료 |
-| M7 | CLI 조회 커맨드 완료 |