claude-memory-layer 1.0.27 → 1.0.29

package/docs/REFACTORING_PLAN_THIN_CORE.md

@@ -0,0 +1,414 @@
+# claude-memory-layer Thin-Core Refactoring Plan
+
+> 목표: `claude-memory-layer`를 **더 가볍고, 더 설명 가능하고, 더 확장 가능한 구조**로 재편한다. 핵심 방향은 **얇은 코어 메모리 엔진 + 강한 Claude 어댑터 + 선택형 확장 모듈**이다.
+
+---
+
+## 0. 현재 진행 상태 요약 (2026-05-04)
+
+현재 refactor branch에서는 초안 계획의 핵심인 “`MemoryService` 얇게 만들기”가 상당 부분 구현됐다.
+
+완료/진행된 축:
+
+- `MemoryService`는 대부분 compatibility facade가 되었고, 주요 책임은 `src/core/engine/*` 서비스로 이동했다.
+- Registry/service-locator 책임은 `src/services/memory-service-registry.ts`로 분리됐다.
+- Shared-store 기본 설정은 `src/services/memory-service-config.ts`가 소유한다.
+- Retrieval은 `RetrievalOrchestrator`, `RetrievalDisclosureService`, `RetrievalAnalyticsService`, `createRetrievalServices(...)`로 분리됐다.
+- Ingest/query/runtime/embedding/endless/shared/composition 책임은 각각 별도 서비스로 분리됐다.
+- Claude hooks는 `src/adapters/claude/hooks/*`로 이동했고, 기존 `src/hooks/*`는 wrapper로 남았다.
+- Progressive disclosure UX는 service/API/CLI/dashboard까지 `search -> expand -> source` 형태로 연결됐다.
+
+남은 큰 판단:
+
+- shared memory service는 `src/extensions/shared-memory/`로, endless memory service는 `src/extensions/endless-memory/`로, MCP implementation은 `src/extensions/mcp/`로, Embedder implementation은 `src/extensions/vector/`로 이동 완료. VectorStore/VectorWorker를 추가 물리 이동할지 여부
+- README에서 shipped/stable/experimental feature 상태는 1차 정리 완료. 남은 것은 MCP package bin / install command를 실제로 추가할지 결정하는 것
+- `session-history-importer`, `codex-session-history-importer`, `mcp/handlers` 같은 app/adapter callsite를 `MemoryService` facade에서 더 멀리 떼어낼지
+
+상세 commit checkpoint와 검증 결과는 `docs/REFACTORING_MILESTONES_AND_ISSUES.md`의 “현재 구현/검증 상태”를 기준으로 본다.
+
+---
+
+## 1. 왜 이 리팩터링이 필요한가
+
+현재 구조는 기능적으로 강하다. 하지만 다음 문제가 보인다.
+
+1. **코어와 확장 기능 경계가 흐리다**
+   - `MemoryService`가 너무 많은 책임을 가진다.
+   - 저장, 검색, shared store, endless mode, markdown mirror, workers, continuity, promotion이 한 서비스에 많이 몰려 있다.
+
+2. **저장 계층이 많다**
+   - SQLite
+   - LanceDB
+   - markdown mirror
+   - shared store
+   - optional Mongo sync
+   
+   각 계층의 역할은 유용하지만, source of truth가 명확하지 않으면 유지비가 커진다.
+
+3. **Claude 통합이 코어와 강결합되어 있다**
+   - 프로젝트 자체 강점이 Claude hooks인 것은 맞지만,
+   - 이 때문에 코어 메모리 엔진 자체가 재사용 가능한 구조로 잘 드러나지 않는다.
+
+4. **문서와 구현의 drift가 있다**
+   - README 설명과 실제 구현의 차이가 신규 기여자와 미래 유지보수 비용을 높인다.
+
+---
+
+## 2. 리팩터링의 설계 원칙
+
+### 원칙 1. Canonical과 Derived를 구분한다
+- **Canonical**: 반드시 보존되는 진실한 저장소
+- **Derived**: 언제든 재생성 가능한 저장소/인덱스/요약
+
+권장 정의:
+- **SQLite = machine canonical**
+- **Markdown journal = human-readable canonical projection**
+- **LanceDB = derived acceleration index**
+- **shared / Mongo sync = optional extension replication layer**
+
+### 원칙 2. Raw, Fact, Summary를 분리한다
+메모리 계층을 최소 3단으로 나눈다.
+
+1. **RawEvent**
+   - 원본 prompt / assistant / tool output / markers / imports
+2. **MemoryFact**
+   - retrieval에 최적화된 작은 사실 단위
+3. **MemorySummary**
+   - turn/session/project/continuity 수준 요약
+
+### 원칙 3. 코어는 SQLite-only로도 최소 기능 동작해야 한다
+- 검색 최소 모드는 SQLite keyword + recent timeline으로 동작 가능해야 한다.
+- Vector/LanceDB는 성능 향상 계층으로 취급한다.
+- semantic daemon도 optional accelerator여야 한다.
+
+### 원칙 4. Claude lifecycle integration은 adapter로 분리한다
+Claude Code hooks는 매우 중요하지만, 코어와 같은 층에 있으면 안 된다.
+
+### 원칙 5. 실험 기능은 확장 모듈로 이동한다
+- shared store
+- Mongo sync
+- MCP
+- endless/consolidation 실험
+- advanced graph/task systems
+
+이런 것들은 코어를 무겁게 하지 않도록 feature boundary를 가져야 한다.
+
+---
+
+## 3. 목표 아키텍처
+
+### Layer A. Core Memory Engine
+항상 필요한 최소 시스템.
+
+포함:
+- project/session registry
+- canonical SQLite store
+- raw event model
+- fact derivation pipeline
+- summary pipeline
+- retrieval engine
+- citation/source tracing
+- import/export
+
+비포함:
+- Claude-specific hook logic
+- dashboard UI
+- shared replication
+- Mongo sync
+- experimental graph layers
+
+### Layer B. Claude Adapter
+Claude Code lifecycle와의 결합층.
+
+포함:
+- `SessionStart`
+- `UserPromptSubmit`
+- `PostToolUse`
+- `Stop`
+- `SessionEnd`
+- transcript extraction
+- context injection formatting
+- tool capture policy
+
+### Layer C. Optional Accelerators
+성능과 품질 향상용 옵션.
+
+포함:
+- vector index (LanceDB)
+- embeddings / batch workers
+- semantic daemon
+- reranking
+- helpfulness analytics
+- retrieval traces visualization
+
+### Layer D. Optional Extensions
+실험 또는 고급 기능.
+
+포함:
+- shared store
+- Mongo sync
+- MCP server
+- advanced continuity systems
+- entity/task graph enhancements
+- future code-aware memory anchors
+
+### Layer E. Apps
+사용자-facing 프로그램.
+
+포함:
+- CLI
+- dashboard server
+- static UI
+
+---
+
+## 4. 새 도메인 모델 제안
+
+### 4.1 RawEvent
+원본 이벤트 저장 단위.
+
+필드 예시:
+- `event_id`
+- `project_hash`
+- `session_id`
+- `turn_id`
+- `event_type` (`user_prompt`, `assistant_response`, `tool_output`, `session_marker`, `imported_turn`)
+- `content`
+- `tool_name`
+- `metadata`
+- `created_at`
+- `privacy_level`
+- `source_ref`
+
+### 4.2 MemoryFact
+검색에 쓰는 최소 사실 단위.
+
+필드 예시:
+- `fact_id`
+- `project_hash`
+- `fact_type`
+- `text`
+- `derived_from_event_ids[]`
+- `source_kind`
+- `tags`
+- `confidence`
+- `importance`
+- `recency_bucket`
+- `entity_refs[]`
+- `file_refs[]`
+- `symbol_refs[]`
+- `created_at`
+- `updated_at`
+
+### 4.3 MemorySummary
+상위 요약 레이어.
+
+종류:
+- turn summary
+- session summary
+- project summary
+- continuity summary
+- timeline digest
+
+### 4.4 MemoryRule / Preference
+장기적 반복 패턴/선호/관례.
+
+예:
+- preferred coding style
+- recurring workflow preference
+- stable project constraints
+
+### 4.5 RetrievalTrace
+검색 explainability와 개선용 로그.
+
+필드 예시:
+- `query`
+- `selected_ids`
+- `candidate_ids`
+- `retrieval_reason`
+- `strategy`
+- `accepted`
+- `helpful_score`
+- `used_in_response`
+
+---
+
+## 5. 검색 제품 구조 재설계
+
+현재의 검색 능력은 이미 나쁘지 않다. 문제는 **사용자/개발자 관점에서 구조가 덜 선명하다**는 점이다.
+
+### 새 retrieval UX 제안
+
+#### Level 1: Search
+- 빠른 후보 목록
+- 짧은 snippet
+- why matched 표시
+
+#### Level 2: Expand
+- 더 넓은 맥락 복원
+- 같은 turn / session / tool run 내 주변 기억 표시
+
+#### Level 3: Source
+- 원문 transcript / tool output / imported source로 drill-down
+- citation trace 제공
+
+### 결과 타입 표준화
+모든 retrieval 결과는 아래 타입 중 하나를 가진다.
+- `fact`
+- `summary`
+- `tool_evidence`
+- `session_memory`
+- `rule`
+- `source`
+
+### Retrieval reason 표준화
+예:
+- `semantic_match`
+- `keyword_match`
+- `recent_relevance`
+- `continuity_link`
+- `entity_overlap`
+- `tool_followup`
+- `summary_fallback`
+
+---
+
+## 6. 저장 전략 재정의
+
+### 권장 기본 원칙
+- SQLite는 **항상 진실의 중심**
+- LanceDB는 **재생성 가능한 index**
+- markdown은 **사람이 읽는 projection/journal**
+- shared/Mongo는 **replication/extension**
+
+### 실전 운영 의미
+1. SQLite만 있어도 데이터는 살아 있어야 함
+2. LanceDB가 깨져도 rebuild 가능해야 함
+3. markdown journal만 봐도 사람은 전체 흐름을 이해할 수 있어야 함
+4. shared 기능이 꺼져도 코어는 정상 동작해야 함
+
+---
+
+## 7. `MemoryService` 분해 계획
+
+현재 `MemoryService`는 지나치게 큰 facade다. 완전 제거가 아니라 **얇은 orchestration facade**로 축소하는 게 좋다.
+
+### 목표 분해
+
+#### 1) `CoreMemoryEngine`
+- raw event append
+- fact derivation trigger
+- summary derivation trigger
+- retrieval dispatch
+
+#### 2) `ProjectRegistryService`
+- project path hashing
+- session registry 관리
+
+#### 3) `FactDeriver`
+- raw event → fact 변환
+- tool outputs / prompts / assistant responses에서 핵심 사실 추출
+
+#### 4) `SummaryDeriver`
+- turn/session/project digest 생성
+
+#### 5) `RetrievalEngine`
+- keyword / vector / fallback dispatch
+- result typing
+- explanation metadata 부착
+
+#### 6) `VectorIndexService`
+- embedding queue
+- batch embed
+- LanceDB sync
+
+#### 7) `JournalService`
+- markdown journal append
+- export/import friendly rendering
+
+#### 8) `SharedMemoryExtension`
+- shared promotion
+- shared search
+- Mongo sync integration
+
+이렇게 나누면 `MemoryService`는 호환성 wrapper 또는 app-level composition root로 남길 수 있다.
+
+---
+
+## 8. Claude adapter 재설계
+
+Claude 전용 로직은 `adapters/claude`로 모아야 한다.
+
+### 여기 들어갈 것
+- hooks entrypoints
+- hook payload parsing
+- transcript extraction
+- tool observation filtering
+- additionalContext formatting
+- Claude-specific heuristics
+
+### 이점
+- Claude integration이 더 읽기 쉬워짐
+- 다른 agent adapter 가능성 열림
+- core testing이 훨씬 쉬워짐
+
+---
+
+## 9. 이행 전략
+
+완전 재작성은 비추천. **strangler pattern**으로 단계적 이전을 권장한다.
+
+### Phase 0. 용어/문서 정리
+- SQLite / LanceDB / markdown / shared의 역할을 문서화
+- README drift 해소
+- canonical vs derived 정의 확정
+
+### Phase 1. 코드 경계 만들기
+- 새 폴더 구조 생성
+- 기존 구현은 유지하되 re-export로 연결
+- `MemoryService` 내부에서 새 서비스 호출 시작
+
+### Phase 2. 도메인 모델 분리
+- RawEvent / MemoryFact / MemorySummary 타입 도입
+- 기존 table/flow를 새 모델에 맞춰 점진 변환
+
+### Phase 3. Retrieval product 정리
+- result types, reasons, expand/source API 추가
+- CLI/API/dashboard에 동일한 개념 노출
+
+### Phase 4. 가속 계층 분리
+- vector, daemon, analytics를 optional 계층으로 명시
+- SQLite-only fallback을 공식 지원
+
+### Phase 5. extension 격리
+- shared/Mongo/MCP/experimental graph를 extension 폴더와 feature flag로 이동
+
+---
+
+## 10. 성공 기준
+
+이 리팩터링이 성공했다는 기준은 다음이다.
+
+1. **새 개발자가 30분 내 구조를 설명할 수 있다**
+2. **SQLite만으로 최소 검색/기억 기능이 동작한다**
+3. **LanceDB/daemon이 꺼져도 시스템이 깨지지 않는다**
+4. **Claude hooks 코드와 core memory 코드가 물리적으로 분리된다**
+5. **검색 결과가 왜 나왔는지 설명 가능하다**
+6. **shared/Mongo/MCP를 제거해도 core는 영향이 작다**
+7. **README와 실제 구현이 다시 일치한다**
+
+---
+
+## 11. 최종 판단
+
+이 계획의 핵심은 “더 많은 기능 추가”가 아니다.
+
+핵심은:
+- 구조를 정돈하고
+- 코어를 얇게 만들고
+- 이미 만든 강한 기능을 잃지 않으면서
+- 확장을 안전하게 계속할 수 있게 만드는 것
+
+즉, `claude-memory-layer`는 앞으로
+**feature-rich monolith**가 아니라,
+**composable local memory architecture**로 진화해야 한다.

package/docs/REFERENCE_PROJECT_ANALYSES.md

@@ -0,0 +1,25 @@
+# Reference Project Analyses for claude-memory-layer
+
+이 문서는 `claude-memory-layer` thin-core refactor를 위해 작성/수집한 비교 분석 문서의 인덱스다.
+
+## Target project
+
+- [`PROJECT_STRUCTURE_ANALYSIS.md`](./PROJECT_STRUCTURE_ANALYSIS.md) — `claude-memory-layer` 현재 구조 분석
+- [`TARGET_ARCHITECTURE_AND_FOLDER_STRUCTURE.md`](./TARGET_ARCHITECTURE_AND_FOLDER_STRUCTURE.md) — 목표 thin-core 폴더/계층 구조
+- [`REFACTORING_PLAN_THIN_CORE.md`](./REFACTORING_PLAN_THIN_CORE.md) — 단계적 리팩터링 계획
+- [`REFACTORING_MILESTONES_AND_ISSUES.md`](./REFACTORING_MILESTONES_AND_ISSUES.md) — milestone / issue 단위 작업 분해
+
+## Reference project snapshots
+
+- [`MEMSEARCH_PROJECT_STRUCTURE_ANALYSIS.md`](./MEMSEARCH_PROJECT_STRUCTURE_ANALYSIS.md) — Markdown-first + rebuildable Milvus index + skill/subagent recall 패턴
+- [`SUPERLOCALMEMORY_PROJECT_STRUCTURE_ANALYSIS.md`](./SUPERLOCALMEMORY_PROJECT_STRUCTURE_ANALYSIS.md) — SQLite/FTS/fact/graph/learning까지 확장된 local memory OS 패턴
+
+## Comparative synthesis
+
+- [`ARCHITECTURE_COMPARISON_AND_RECOMMENDATIONS.md`](./ARCHITECTURE_COMPARISON_AND_RECOMMENDATIONS.md) — 세 프로젝트 비교와 `claude-memory-layer` 적용 권고
+
+## 현재 refactor 방향 요약
+
+`claude-memory-layer`는 `memsearch`의 단순한 source-of-truth/derived-index discipline과 `superlocalmemory`의 raw/fact/summary 분리 아이디어를 참고하되, dashboard/MCP/analytics/semantic daemon 같은 무거운 기능은 extension layer로 밀어내고 `MemoryService`는 점진적으로 얇은 facade로 축소한다.
+
+다음 코드 작업의 핵심 slice는 retrieval coordination을 `MemoryService`에서 `RetrievalOrchestrator`로 분리하는 것이다.