claude-memory-layer 1.0.31 → 1.0.33

package/docs/REFACTORING_MILESTONES_AND_ISSUES.md

@@ -1,501 +0,0 @@
-# claude-memory-layer Refactoring Milestones & Issue Breakdown
-
-## 목적
-이 문서는 `claude-memory-layer`를 thin-core 구조로 리팩터링하기 위한 실행 가능한 milestone과 issue 단위 작업 목록이다.
-
-핵심 목표:
-- 구조를 설명 가능하게 만든다
-- 코어를 얇게 만든다
-- Claude 통합은 유지한다
-- 무거운 기능은 확장 계층으로 밀어낸다
-- 완전 재작성이 아니라 단계적 이전을 한다
-
----
-
-# Milestone 0. Architecture Alignment
-
-## 목표
-문서/용어/현실 구현을 맞춘다. 코드 수정 전에 반드시 필요하다.
-
-### Issue 0-1. Canonical storage 정의 문서화
-**내용**
-- SQLite / LanceDB / markdown mirror / shared / Mongo sync의 역할을 명시
-- canonical vs derived 레이어 정의
-
-**산출물**
-- 아키텍처 문서 업데이트
-- 저장 계층 표
-
-**완료 기준**
-- 신규 기여자가 어떤 데이터가 원본인지 1분 내 이해 가능
-
-### Issue 0-2. README drift 정리
-**내용**
-- DuckDB/Bun/MCP 관련 설명을 실제 구현과 맞춤
-- 현재 shipped feature vs experimental feature 분리
-
-**완료 기준**
-- README와 실제 엔트리포인트/의존성이 일치
-
-### Issue 0-3. 용어 정리
-**내용**
-- event / fact / summary / rule / shared memory / citation / retrieval trace 용어 정의
-
-**완료 기준**
-- 문서와 코드 naming이 서로 충돌하지 않음
-
----
-
-# Milestone 1. Domain Model Separation
-
-## 목표
-현재 혼합된 메모리 개념을 raw / fact / summary 계층으로 분리한다.
-
-### Issue 1-1. `RawEvent` 타입 도입
-**내용**
-- prompt / assistant / tool output / session marker / imported records를 단일 raw event 모델로 정리
-
-**완료 기준**
-- 모든 ingest path가 raw event로 normalize 가능
-
-### Issue 1-2. `MemoryFact` 타입 도입
-**내용**
-- 검색 단위로 쓸 작은 fact 모델 정의
-- source event reference 포함
-
-**완료 기준**
-- 최소 3개 ingest path(프롬프트/응답/툴 출력)에서 fact derivation 가능
-
-### Issue 1-3. `MemorySummary` 타입 도입
-**내용**
-- turn/session/project/continuity summary 타입 정리
-
-**완료 기준**
-- 요약 결과가 raw event/fact와 분리 저장됨
-
-### Issue 1-4. Retrieval result type 표준화
-**내용**
-- `fact`, `summary`, `tool_evidence`, `source`, `rule` 타입 도입
-
-**완료 기준**
-- search API 응답이 통일된 envelope를 사용
-
----
-
-# Milestone 2. Core Engine Extraction
-
-## 목표
-`MemoryService`를 작은 조립층으로 축소하고 핵심 기능을 분리한다.
-
-### Issue 2-1. `ProjectRegistryService` 추출
-**내용**
-- project path hash, storage path, session registry 관리 분리
-
-**완료 기준**
-- `memory-service.ts`에서 registry 관련 책임 제거
-
-### Issue 2-2. `MemoryIngestService` 추출
-**내용**
-- raw event append 경로 분리
-- privacy filter / capture normalization 연결
-
-**완료 기준**
-- append 관련 코드가 별도 서비스에 위치
-
-### Issue 2-3. `FactDeriver` 추출
-**내용**
-- raw event → fact 변환 책임 분리
-
-**완료 기준**
-- fact derivation이 독립 테스트 가능
-
-### Issue 2-4. `SummaryDeriver` 추출
-**내용**
-- turn/session/project 요약 생성 로직 분리
-
-**완료 기준**
-- summary 로직이 retrieval/index 로직과 분리됨
-
-### Issue 2-5. `RetrievalEngine` 추출
-**내용**
-- 검색/확장/소스해석 책임 분리
-
-**완료 기준**
-- `MemoryService`는 retrieval orchestration만 함
-
----
-
-# Milestone 3. Claude Adapter Isolation
-
-## 목표
-Claude-specific lifecycle을 adapter 레이어로 분리한다.
-
-### Issue 3-1. `src/adapters/claude/hooks` 생성
-**내용**
-- 기존 `src/hooks/*` 파일을 새 adapter 위치로 이동 또는 re-export
-
-**완료 기준**
-- hook entrypoint가 adapter layer 아래 존재
-
-### Issue 3-2. transcript parsing 분리
-**내용**
-- stop/session-end에서 사용하는 transcript reconstruction 로직 분리
-
-**완료 기준**
-- transcript 관련 유틸이 hook handler와 분리됨
-
-### Issue 3-3. capture policy 분리
-**내용**
-- 어떤 prompt/tool/response를 저장할지 정책 모듈화
-
-**완료 기준**
-- capture heuristics가 테스트 가능한 정책 모듈이 됨
-
-### Issue 3-4. context injection formatter 분리
-**내용**
-- additionalContext 생성 로직을 retrieval engine과 분리
-
-**완료 기준**
-- 검색 결과와 Claude용 문자열 포맷팅이 분리됨
-
----
-
-# Milestone 4. Storage & Index Simplification
-
-## 목표
-SQLite 중심 구조를 선명히 하고, vector 계층을 optional accelerator로 명확히 한다.
-
-### Issue 4-1. storage role matrix 작성 및 코드 반영
-**내용**
-- SQLite canonical / LanceDB derived / markdown journal projection 규칙 반영
-
-**완료 기준**
-- 코드 주석과 문서가 같은 storage 역할을 설명
-
-### Issue 4-2. SQLite-only fallback 공식화
-**내용**
-- vector index 없이도 최소 search / recent context 동작
-
-**완료 기준**
-- vector 미초기화 상태 테스트 통과
-
-### Issue 4-3. vector 계층 네임스페이스 이동
-**내용**
-- `vector-store`, `vector-worker`, `embedder` 등을 `extensions/vector`로 이동
-
-**완료 기준**
-- core 모듈이 vector 구현 세부사항에 직접 의존하지 않음
-
-### Issue 4-4. stable derived key 도입
-**내용**
-- fact / summary / imported transcript memory에 deterministic key 부여
-
-**완료 기준**
-- dedupe/rebuild가 key 기반으로 가능
-
----
-
-# Milestone 5. Retrieval UX Productization
-
-## 목표
-검색 품질보다 “검색 결과를 설명 가능하고 쓰기 쉽게” 만든다.
-
-### Issue 5-1. `search -> expand -> source` API 설계
-**내용**
-- search 결과
-- expanded context
-- source drill-down을 별도 surface로 노출
-
-**완료 기준**
-- CLI/API/dashboard 모두 같은 mental model 사용
-
-### Issue 5-2. retrieval reason 표준화
-**내용**
-- semantic / keyword / recent / continuity / entity / fallback reason taxonomy 도입
-
-**완료 기준**
-- 모든 search result에 최소 1개 reason 포함
-
-### Issue 5-3. result type badge 추가
-**내용**
-- fact / summary / tool evidence / source 구분
-
-**완료 기준**
-- 사용자가 결과 종류를 즉시 이해 가능
-
-### Issue 5-4. helpfulness minimal loop
-**내용**
-- shown / clicked / expanded / accepted / reused 등 최소 signal 수집
-
-**완료 기준**
-- retrieval trace와 연결된 lightweight feedback 저장 가능
-
----
-
-# Milestone 6. Extensions Isolation
-
-## 목표
-무거운 기능을 core 바깥으로 이동한다.
-
-### Issue 6-1. shared memory 모듈 분리
-**내용**
-- shared event store / shared vector / promoter를 `extensions/shared-memory`로 이동
-
-**완료 기준**
-- shared 기능 OFF 상태에서 core 영향 최소
-
-### Issue 6-2. Mongo sync 분리
-**내용**
-- sync 관련 설정/worker/ops 스크립트 경계 분리
-
-**완료 기준**
-- Mongo dependency가 core 실행 경로에서 제거됨
-
-### Issue 6-3. MCP extension 분리
-**내용**
-- MCP server/tools/handlers를 `extensions/mcp`로 이동
-
-**완료 기준**
-- MCP 비활성 상태가 정상 기본 경로가 됨
-
-### Issue 6-4. continuity/endless mode 분리
-**내용**
-- working set / consolidated / continuity 관련 기능을 `extensions/continuity`로 이동
-
-**완료 기준**
-- core search/ingest와 endless mode가 느슨하게 결합됨
-
----
-
-# Milestone 7. Apps Cleanup
-
-## 목표
-CLI / server / dashboard를 app layer로 정리한다.
-
-### Issue 7-1. CLI app 경계 정리
-**내용**
-- CLI는 parsing/composition만 담당
-- business logic 최소화
-
-### Issue 7-2. server app 경계 정리
-**내용**
-- API route와 core service composition 분리
-
-### Issue 7-3. dashboard asset modularization
-**내용**
-- `app.js` 단일 파일을 기능별 모듈로 분해
-
-**완료 기준**
-- Search / Sessions / Health / Projects 등 기능별 분리
-
----
-
-# Milestone 8. Code-Aware Memory Anchors (Optional, Recommended)
-
-## 목표
-full code graph 대신 가벼운 code-aware memory를 도입한다.
-
-### Issue 8-1. file path refs 도입
-**내용**
-- memory fact가 관련 파일 경로를 참조 가능하게 함
-
-### Issue 8-2. symbol refs 도입
-**내용**
-- 함수/클래스/모듈명 anchor를 metadata에 저장
-
-### Issue 8-3. commit/diff refs 도입
-**내용**
-- imported or observed coding actions에 git context 연결
-
-**완료 기준**
-- “이 기억이 어떤 코드와 관련 있는지”를 가볍게 설명 가능
-
----
-
-# Milestone 9. Hardening & Migration Finish
-
-## 목표
-새 구조를 기본 구조로 전환하고 legacy compatibility를 줄인다.
-
-### Issue 9-1. compat layer 축소
-**내용**
-- re-export/legacy wrapper 단계적으로 제거
-
-### Issue 9-2. test matrix 재정리
-**내용**
-- core
-- adapters/claude
-- extensions
-- apps
-별로 테스트 층 구분
-
-### Issue 9-3. docs refresh
-**내용**
-- architecture
-- operations
-- install
-- extension status 표기
-
-### Issue 9-4. release checklist 업데이트
-**내용**
-- 어떤 extension이 stable/experimental인지 릴리즈 노트에 명시
-
----
-
-# 추천 우선순위
-
-## 즉시 착수 권장
-1. Milestone 0
-2. Milestone 1
-3. Milestone 2
-4. Milestone 3
-
-## 다음 단계
-5. Milestone 4
-6. Milestone 5
-7. Milestone 6
-
-## 선택적 후속
-8. Milestone 7
-9. Milestone 8
-10. Milestone 9
-
----
-
-# 90일 추천 로드맵
-
-## 1~2주
-- Milestone 0 완료
-- 핵심 용어 및 문서 정리
-
-## 3~5주
-- Milestone 1~2 진행
-- 도메인 타입과 core service 분리
-
-## 6~8주
-- Milestone 3~4 진행
-- Claude adapter와 vector/storage 경계 정리
-
-## 9~10주
-- Milestone 5 진행
-- retrieval UX/API 정리
-
-## 11~12주
-- Milestone 6 시작
-- shared/MCP/Mongo/continuity extension 분리
-
----
-
-# 현재 구현/검증 상태 (2026-05-04 KST)
-
-## 이번 thin-core refactor에서 반영된 주요 항목
-- `src/core/registry/`와 `src/services/memory-service-registry.ts`로 project path/hash/session/default/lightweight service-locator 책임을 분리했다.
-- `src/services/memory-service-config.ts`가 disabled/enabled shared-store 기본값을 소유하고, `memory-service.ts`는 public compatibility export만 보존한다.
-- `src/core/model/`에 raw/fact/summary/rule/retrieval result 계층 타입을 추가했다.
-- `src/core/derive/fact-deriver.ts`와 summary derivation 흐름으로 deterministic derivation의 첫 slice를 분리했다.
-- `src/core/engine/` 아래로 `MemoryService`의 주요 책임을 분리했다.
-  - `memory-engine-services.ts`: SQLite/vector/embedder/retrieval/ingest/query bundle construction
-  - `retrieval-orchestrator.ts`, `retrieval-disclosure-service.ts`, `retrieval-analytics-service.ts`, `retrieval-services.ts`
-  - `memory-ingest-service.ts`, `memory-query-service.ts`, `memory-runtime-service.ts`
-  - `embedding-maintenance-service.ts`; `endless-memory-services.ts`와 `shared-memory-services.ts`는 현재 `src/extensions/*` 구현을 가리키는 compatibility shim
-  - `memory-service-composition.ts`: constructor-time service graph wiring
-- `MemoryService`는 현재 대부분 public compatibility facade + project state + composition assignment + service delegation 역할만 남겼다.
-- Claude hook 구현은 `src/adapters/claude/hooks/`로 이동했고, `src/hooks/*`는 compatibility wrapper로 축소했다.
-- Progressive retrieval disclosure는 service/API/CLI/dashboard까지 `search -> expand -> source` mental model로 연결했다.
-- Shared disclosure drill-down은 `shared:<entryId>`를 local raw event처럼 위장하지 않고 shared provenance를 명시한다.
-- `Retriever`에 deep retrieval 품질 개선용 intent rewrite merge, keyword rerank, graph-hop expansion, project scope filtering을 추가했다.
-- `@modelcontextprotocol/sdk@1.29.0` 기준으로 MCP `CallToolResult` 타입을 명시해 full typecheck를 복구했다.
-
-## 최근 완료 commit checkpoint
-```text
-2bd32b5 refactor(memory): centralize shared store defaults
-4f6ccc8 test(memory): document project registry shared config caching
-099dad1 [verified] Extract memory service registry
-ddea95e refactor(memory): extract service composition wiring
-54c360e refactor(memory): route embedding model facade through maintenance service
-e776d57 refactor(memory): delegate graduation access through runtime service
-36313a6 refactor(memory): move endless context formatting
-28e144d refactor(memory): move ingest pipeline to ingest service
-265899a refactor(memory): extract query service facades
-53354e3 refactor(memory): extract memory runtime service
-0b5bde4 refactor(memory): extract embedding maintenance service
-95d2075 Extract endless memory services
-6da4ddb refactor(memory): extract shared memory services
-c19757d refactor(memory): bundle engine service construction
-e186ee4 refactor(claude): move semantic daemon behind adapter boundary
-8071313 refactor(claude): move hook implementations behind adapter boundary
-50ff74e feat(dashboard): show shared retrieval provenance
-518bdda feat(cli): show shared retrieval results
-c58f50f fix(retrieval): keep disclosure drill-down lightweight
-81bbf70 refactor(retrieval): bundle retrieval services
-```
-
-## 현재 milestone status
-- **Milestone 0 — Architecture Alignment:** 부분 완료. 계획/비교 문서는 존재하지만 README drift와 extension stability 표시는 추가 정리가 필요하다.
-- **Milestone 1 — Domain Model Separation:** 부분 완료. raw/fact/summary/retrieval result 타입과 일부 derivation은 분리됐지만 fact/summary 저장 모델의 제품화는 남아 있다.
-- **Milestone 2 — Core Engine Extraction:** 큰 진전. `MemoryService`의 retrieval/ingest/query/runtime/shared/endless/embedding/composition/registry 책임이 대부분 별도 서비스로 이동했다.
-- **Milestone 3 — Claude Adapter Isolation:** 큰 진전. hooks/transcript/semantic-daemon adapter boundary가 생겼다. capture policy 추가 분리는 후속 후보다.
-- **Milestone 4 — Storage & Index Simplification:** 부분 완료. SQLite canonical / vector derived 관점은 구현에 반영됐고 Embedder implementation은 `src/extensions/vector/`로 이동했다. VectorStore/VectorWorker 물리 이동은 남아 있다.
-- **Milestone 5 — Retrieval UX Productization:** 큰 진전. service/API/CLI/dashboard disclosure surface가 있다. helpfulness feedback loop의 제품화는 후속이다.
-- **Milestone 6 — Extensions Isolation:** 진행 중. shared memory service implementation은 `src/extensions/shared-memory/`로, endless memory service implementation은 `src/extensions/endless-memory/`로, MCP implementation은 `src/extensions/mcp/`로, Embedder implementation은 `src/extensions/vector/`로 이동했고 각각 기존 core/engine 또는 app path compatibility shim을 남겼다. VectorStore/VectorWorker 물리 이동은 후속이다.
-- **Milestone 7~9:** 후속 hardening/release cleanup 단계.
-
-## 통과한 검증
-```bash
-npm test -- --run tests/memory-service-config.test.ts tests/memory-service-registry.test.ts tests/memory-service-composition.test.ts
-# 3 files / 12 tests passed
-
-npm run typecheck -- --pretty false
-# passed
-
-git diff --check
-# passed
-
-npm test -- --run
-# 39 files / 172 tests passed
-
-npm run build
-# Build complete
-
-graphify update .
-# graphify-out updated: 1263 nodes, 2613 edges, 48 communities
-```
-
-## 현재 known status
-- full typecheck, full vitest suite, build가 모두 통과한다.
-- full test에서 새 regressions는 발견되지 않았다.
-- `graphify-out/`는 현재 `git status --short`에 tracked 변경으로 나타나지 않는다.
-- `patch` 도구의 파일 단위 자동 lint는 tsconfig project mode가 아니라 단일 파일 컴파일 방식으로 동작해 `node_modules`/target 관련 false positive를 출력할 수 있다. authoritative check는 `npm run typecheck -- --pretty false`로 본다.
-
-## 다음 권장 slice
-
-1. **MemoryService facade audit 마무리**
-   - `MemoryService`에 남은 직접 상태는 `projectHash`, `projectPath`, mode flags, service field assignment 정도다.
-   - 더 뺄 후보는 `session-history-importer`, `codex-session-history-importer`, `mcp/handlers`처럼 아직 `MemoryService`에 직접 붙어 있는 adapter/app callsite다.
-
-2. **남은 extension 물리 이동 여부 결정**
-   - shared/endless/MCP/Embedder는 `src/extensions/*`로 이동했고 compatibility shim을 남겼다.
-   - 다음 후보는 VectorStore/VectorWorker 계층이며, retrieval/runtime/LanceDB와 얽혀 있어 별도 사전 조사 후 진행한다.
-
-3. **README / release docs refresh**
-   - 현재 shipped feature와 experimental extension을 구분했다.
-   - shared store, endless mode, MCP, disclosure API/CLI/dashboard, Embedder extension 상태를 README에 반영했다.
-   - 남은 후속: 정식 MCP package bin / `mcp install` command wiring 여부 결정.
-
-4. **Generated graph/code-map artifact 정책 결정**
-   - `graphify-out/`를 버전 관리할지, 생성물로 유지할지 명확히 한다.
-
----
-
-# 최종 판단
-
-이 계획에서 가장 중요한 것은 기능 삭제가 아니다.
-오히려 **기능의 위치를 올바르게 재배치하는 것**이다.
-
-즉:
-- 코어는 더 얇게
-- Claude 통합은 더 또렷하게
-- 확장은 더 안전하게
-- 문서는 더 정직하게
-
-이 네 가지가 맞춰지면 `claude-memory-layer`는 지금보다 훨씬 강한 장기 구조를 갖게 된다.