claude-memory-layer 1.0.31 → 1.0.33

package/docs/MCP_MEMORY_SERVICE_COMPARATIVE_REVIEW.md

@@ -1,271 +0,0 @@
-# mcp-memory-service 코드 리뷰 기반 개선 제안서
-
-작성일: 2026-02-26  
-대상:
-- 참고 레포: `~/workspace/mcp-memory-service` (commit `8d7e582`)
-- 개선 대상: `~/workspace/claude-memory-layer`
-
----
-
-## 0) 결론 요약
-
-`claude-memory-layer`는 이미 구조가 매우 좋고(프로젝트 해시 격리, scoped retrieval, outbox, endless mode, shared store 실험), **핵심 기능은 충분히 경쟁력 있음**.
-
-다만 `mcp-memory-service`를 기준으로 봤을 때 실제 운영 관점에서 보강하면 체감이 큰 포인트는 아래 5가지:
-
-1. **멀티-repo 스코프 강제 정책**(기본 격리 + 명시적 cross-repo)
-2. **태그 taxonomy 표준화**(`proj:`, `agent:`, `topic:`, `q:` 등) + 자동 주입
-3. **HTTP/SSE API 레이어**(운영/관측/통합성 증가)
-4. **하이브리드 검색(BM25+Vector) 공식화** 및 점수 퓨전 표준화
-5. **운영 안정성 레이어**(헬스체크, 백업/복구, 보존정책, 인증)
-
-즉, 지금은 “강한 코어 엔진” 단계고, 다음 단계는 “**운영형 메모리 플랫폼**”으로 가는 게 맞음.
-
----
-
-## 1) 조사 방식
-
-### 확인한 핵심 파일(참고 레포)
-- `README.md`
-- `docs/architecture.md`
-- `docs/agents/README.md`
-- `docs/mastery/configuration-guide.md`
-- `src/mcp_memory_service/models/tag_taxonomy.py`
-- `src/mcp_memory_service/web/api/memories.py`
-- `src/mcp_memory_service/web/api/search.py`
-
-### 확인한 핵심 파일(현재 레포)
-- `README.md`
-- `package.json`
-- `src/services/memory-service.ts`
-- `src/core/retriever.ts`
-- `src/core/event-store.ts`
-- `docs/OPERATIONS.md`
-- `docs/MEMU_ADOPTION.md`
-
----
-
-## 2) 현재 `claude-memory-layer` 강점 (유지해야 할 것)
-
-1. **프로젝트 격리 설계가 이미 있음**
-   - `hashProjectPath()` + `~/.claude-code/memory/projects/{hash}`
-   - 세션 레지스트리로 session→project 매핑
-
-2. **검색 전략 설계가 좋음**
-   - `fast/deep/auto`, fallback chain, scope filter, rerank, graph-hop
-   - 실전성 높은 토큰/정확도 트레이드오프
-
-3. **쓰기 파이프라인 안정성 의식이 강함**
-   - SQLite primary, outbox, background worker
-   - hook 경량 모드(lightweightMode)
-
-4. **고급 메모리 기능이 이미 구현/실험됨**
-   - graduation, endless mode, shared store, markdown mirror
-
-=> 요약: 엔진 레벨은 이미 상당히 앞서 있음.
-
----
-
-## 3) `mcp-memory-service` 대비 갭 분석
-
-### A. 멀티-repo 운영 규칙의 “정책 강제력”
-
-- 현 상태: 프로젝트 해시 분리는 있으나, 교차 검색/주입 정책이 코드/문서에서 강하게 표준화되어 있지는 않음
-- 참고 레포 포인트:
-  - `agent:` 태그 자동 주입(`X-Agent-ID`)
-  - 태그 namespace 체계 명시(`proj:`, `topic:`, `q:` ...)
-
-**리스크**
-- 여러 repo를 운용할수록 검색 누수(다른 repo 기억 주입) 가능성 증가
-
-**개선안**
-- 기본 policy: `same-project-only`
-- cross-project는 explicit flag + 이유(required reason) 필요
-- retrieval 요청 시 project_id 부재면 hard-fail(옵션)
-
----
-
-### B. 태그 체계 표준화 부족
-
-- 현 상태: metadata/scope가 강하지만 태그 네임스페이스 규약은 상대적으로 약함
-- 참고 레포 포인트:
-  - `TagTaxonomy`를 별도 모델로 정의하고 namespace 유효성 관리
-
-**개선안**
-- `src/core/tag-taxonomy.ts` 신설
-- 표준 namespace:
-  - `proj:` repository identifier
-  - `agent:` 실행 주체
-  - `topic:` 주제
-  - `q:` 품질/신뢰 등급
-  - `t:` 시간/스프린트
-  - `sys:` 시스템 자동 태그
-- ingest 시 최소 `proj:<hash>` 자동 부착
-
----
-
-### C. HTTP/SSE 운용 계층 부재(또는 약함)
-
-- 현 상태: CLI/hooks 중심 구조가 강점이지만, 외부 오케스트레이터/다중 클라이언트 연동은 제한적
-- 참고 레포 포인트:
-  - REST API + SSE + dashboard 연동
-
-**개선안**
-- 최소 API부터 시작:
-  - `POST /api/memories`
-  - `POST /api/memories/search`
-  - `GET /api/memories?project=...`
-  - `GET /api/health`
-- SSE 이벤트:
-  - memory_stored
-  - memory_deleted
-  - search_completed
-
----
-
-### D. Hybrid search 점수 체계 공식화 필요
-
-- 현 상태: fast/deep + rerank는 이미 훌륭함
-- 부족한 점: “BM25 + Vector + Recency + Quality”를 운영상 조정 가능한 공식으로 고정 문서화한 수준은 약함
-- 참고 레포 포인트:
-  - hybrid 검색을 제품 기능으로 명시
-
-**개선안**
-- `score = w_semantic*S + w_lexical*L + w_recency*R + w_quality*Q`
-- env/config에서 가중치 조정 가능하게
-- quality 점수 부재 시 graceful fallback
-
----
-
-### E. 운영/보안 레이어
-
-- 현 상태: runbook/ops 스크립트 존재(좋음)
-- 참고 레포 포인트:
-  - 인증, 헬스/환경 점검, 상세 config 가이드
-
-**개선안**
-- 최소 추가:
-  - `MEMORY_API_KEY` 인증(HTTP 도입 시)
-  - `/api/health` + 저장소 상태 + outbox backlog 노출
-  - 백업/복구 명령 표준화
-  - 보존정책(TTL, 중요도 기반 정리) 명문화
-
----
-
-## 4) 우선순위 로드맵 (실행 순서)
-
-## P0 (당장 효과 큼, 1~3일)
-1. 멀티-repo 스코프 기본 정책 강제
-2. `proj:` 자동 태깅
-3. 검색 기본값 same-project-only
-4. 교차 검색은 명시적 옵션 필요
-
-## P1 (1~2주)
-1. tag taxonomy 모듈화
-2. hybrid scoring 공식화 + 설정화
-3. health endpoint/metrics 정리
-
-## P2 (2~4주)
-1. HTTP API + SSE 추가
-2. 인증(OAuth까지는 아니어도 API key)
-3. 팀/멀티클라이언트 운영 문서화
-
----
-
-## 5) 구체 구현 제안 (코드 레벨)
-
-### 5.1 Retrieval 옵션 확장
-`src/core/retriever.ts`에 아래 정책 필드 추가 권장:
-
-- `projectScopeMode: 'strict' | 'prefer' | 'global'`
-- `allowedProjectHashes?: string[]`
-- `crossProjectReason?: string`
-
-`strict`일 때 현재 프로젝트 hash 불일치 결과는 필터링.
-
----
-
-### 5.2 자동 태깅 훅
-`MemoryService.storeUserPrompt/storeAgentResponse/storeToolObservation`에서 metadata 병합 시:
-
-- `scope.project.hash`
-- `scope.project.path`
-- `tags` 개념을 도입하면 `proj:${projectHash}` 자동 주입
-
----
-
-### 5.3 정책 파일 도입
-`claude-memory-layer/policies/memory-scope-policy.json` 예:
-
-```json
-{
-  "defaultMode": "strict",
-  "allowCrossProject": false,
-  "requireReasonForCrossProject": true,
-  "alwaysIncludeTags": ["sys:auto", "proj:auto"]
-}
-```
-
----
-
-### 5.4 운영 API 최소셋
-향후 `src/server`에 라우트 추가:
-
-- `GET /api/health`
-  - db 연결 상태
-  - vector worker backlog
-  - failed outbox 개수
-- `POST /api/memories/search`
-  - projectHash 필수(운영 모드에서)
-
----
-
-## 6) 여러 repository 관리 관점 평가
-
-질문의 핵심(“여러 repo 관리 용이?”)에 대해:
-
-- `claude-memory-layer` 현재 구조는 **잠재적으로 매우 유리**
-  - 프로젝트 해시 분리 구조가 이미 있기 때문
-- 하지만 운영 안정성은 “격리 정책 강제 + 표준 태깅 + API 관측”이 있어야 완성
-
-즉, **아키텍처 방향은 맞고, 운영 레이어 보강이 필요**.
-
----
-
-## 7) 추천 최종 전략
-
-`/Users/namsangboy/workspace/claude-memory-layer`를 계속 중심으로 가져가되:
-
-1. P0/P1 개선 먼저 적용해서 “멀티-repo 안 섞이는 안정성” 확보
-2. 그 다음 HTTP/SSE/API key 붙여서 외부 자동화/다중 클라이언트 지원
-3. 마지막에 공유 지식(shared store) 룰을 엄격히(검증된 것만 승격)
-
-이 순서가 리스크/효율 밸런스가 가장 좋음.
-
----
-
-## 8) 보너스: 바로 체크할 TODO
-
-- [x] `projectScopeMode` 옵션 추가
-- [x] 기본 검색 strict project filter 적용
-- [x] `proj:<hash>` 자동 태깅
-- [x] tag taxonomy 모듈 생성
-- [x] health API에 outbox failed/pending 수치 노출 (`GET /api/health`)
-- [ ] 문서에 cross-project 허용 조건 명시
-
-### P1 적용 메모 (이번 반영)
-
-- 태그 taxonomy 파일 추가: `src/core/tag-taxonomy.ts`
-  - namespace 유효성 검증(`sys:, q:, proj:, topic:, t:, user:, agent:`)
-  - tags 정규화(`normalizeTags`)로 ingest 시 품질 보정
-- rerank 가중치 설정화
-  - 환경변수 지원:
-    - `MEMORY_RERANK_WEIGHT_SEMANTIC`
-    - `MEMORY_RERANK_WEIGHT_LEXICAL`
-    - `MEMORY_RERANK_WEIGHT_RECENCY`
-  - 3개가 모두 유효하면 정규화해서 고정값 사용
-  - 없으면 기존 adaptive/기본 동작 fallback
-
----
-
-원하면 다음 단계로 health endpoint/운영 지표(outbox backlog, failed 카운트)까지 이어서 붙일 수 있음.

package/docs/MEMORY_USEFULNESS_AUDIT.md

@@ -1,371 +0,0 @@
-# Memory Usefulness Audit — Real Scenario Test
-
-Date: 2026-05-05
-Target: `claude-memory-layer` built CLI (`dist/cli/index.js`)
-Isolation: temporary `HOME` and temporary project directories; no real `~/.claude` or `~/.claude-code/memory` was touched.
-Raw evidence: [`MEMORY_USEFULNESS_AUDIT_RAW.json`](./MEMORY_USEFULNESS_AUDIT_RAW.json)
-
-## 0. Follow-up improvements applied and re-verified
-
-After the first audit exposed precision/UX issues, the following improvements were implemented and the same real scenario was rerun:
-
-1. Query-time command artifact guard
-   - Queries such as `local-command-stdout command-name opus` now return zero memories.
-2. Technical identifier lexical guard
-   - Out-of-domain project-scoped queries such as `DuckDB legacy storage migrate` in the alpha project now return zero memories instead of loosely related semantic matches.
-   - The same query in the beta project still returns the beta DuckDB memory, proving useful exact matches are preserved.
-3. Score cliff cutoff
-   - The FTS query now returns the two actually relevant memories instead of including an unrelated dashboard provenance third result.
-4. Transformer warning suppression
-   - Known benign HuggingFace warnings (`Unknown model class "eurobert"`, `dtype not specified`) no longer appear in CLI import/stats/search output.
-5. Disclosure reason taxonomy cleanup
-   - Keyword-only disclosure now reports `keyword_match` without `semantic_match` when `vector=no`.
-
-The raw evidence file was regenerated after these improvements.
-
-## 1. Test goal
-
-This audit tested whether the memory layer is useful in the way a coding assistant actually needs it:
-
-1. It can import real Claude-style JSONL conversation history.
-2. It retrieves durable engineering decisions when asked later with different wording.
-3. It keeps project memories scoped, so unrelated project decisions do not leak.
-4. It filters low-value command artifacts from imported sessions.
-5. The progressive `search -> expand -> source` workflow gives enough provenance to trust and inspect a memory.
-6. The shipped CLI works after build, not only through source-level tests.
-
-## 2. Scenario design
-
-Two temporary projects were created:
-
-- `alpha-commerce-ai`: current/refactor project memories.
-- `beta-legacy-duckdb`: unrelated project with a deliberately conflicting storage decision.
-
-The crafted Claude JSONL sessions contained the following durable memories.
-
-### Alpha memories
-
-1. **Retrieval disclosure lifecycle rule**
-   - `expand` / `source` drill-down routes must stay lightweight.
-   - They should not call full `MemoryService.initialize()` because that can start embedders, vector workers, or shared promotion machinery.
-
-2. **SQLite FTS rebuild fix**
-   - The `no such column: T.event_id` failure is fixed by making `events_fts` an internal FTS5 table with `content` and `event_id UNINDEXED`.
-   - Rebuild by dropping/recreating FTS and triggers.
-
-3. **Shared dashboard provenance decision**
-   - Shared results should render as `shared_troubleshooting` provenance.
-   - Show `sourceProjectHash`, `sourceEntryId`, `topics`, `rootCause`, `solution`, and state that no local raw event exists.
-
-4. **Noise artifact**
-   - `<command-name>/model</command-name>` + `<local-command-stdout>opus</local-command-stdout>` was included to verify command artifacts are not stored as useful user prompts.
-
-### Beta memory
-
-- A conflicting legacy decision: beta should keep DuckDB and not migrate to SQLite.
-- This tests project scoping against alpha queries.
-
-## 3. Commands executed
-
-All commands used a temporary `HOME`.
-
-```bash
-node dist/cli/index.js import --session <alpha-session.jsonl> --project <alpha-project> --verbose
-node dist/cli/index.js import --session <beta-session.jsonl> --project <beta-project> --verbose
-node dist/cli/index.js stats --project <alpha-project>
-node dist/cli/index.js search "disclosure expand source initialize vector workers lightweight" --project <alpha-project> --top-k 5 --min-score 0.1
-node dist/cli/index.js search "T.event_id FTS rebuild internal table trigger event_id" --project <alpha-project> --top-k 5 --min-score 0.1
-node dist/cli/index.js search "shared_troubleshooting rootCause solution sourceProjectHash" --project <alpha-project> --top-k 5 --min-score 0.1
-node dist/cli/index.js search "local-command-stdout command-name opus" --project <alpha-project> --top-k 5 --min-score 0.1
-node dist/cli/index.js search "DuckDB legacy storage migrate" --project <alpha-project> --top-k 5 --min-score 0.1
-node dist/cli/index.js search "DuckDB legacy storage migrate" --project <beta-project> --top-k 5 --min-score 0.1
-node dist/cli/index.js search "T.event_id FTS rebuild internal table" --project <alpha-project> --top-k 3 --min-score 0.1 --disclosure --strategy fast
-node dist/cli/index.js expand <first-disclosure-result-id> --project <alpha-project> --window-size 2
-node dist/cli/index.js source <first-disclosure-result-id> --project <alpha-project>
-```
-
-## 4. Verified working behavior
-
-### 4.1 Import works and filters command-artifact noise
-
-Alpha import result:
-
-- Total messages: 7
-- Imported prompts: 3
-- Imported responses: 3
-- Skipped duplicates/noise: 1
-- Embeddings queued: 6
-
-This is exactly expected: the three real user prompts and three assistant durable responses were imported, while the local-command artifact was skipped.
-
-Beta import result:
-
-- Total messages: 2
-- Imported prompts: 1
-- Imported responses: 1
-- Embeddings queued: 2
-
-### 4.2 Project-scoped markdown mirror writes to the target project
-
-The audit verified markdown mirrors were written under each temporary target project, not under the `claude-memory-layer` repository working directory.
-
-Examples:
-
-- `<alpha-project>/memory/_index.md`
-- `<alpha-project>/memory/agent_response/uncategorized/2026-05-05.md`
-- `<alpha-project>/memory/user_prompt/uncategorized/2026-05-05.md`
-
-`repo_memory_exists = false`, so the previous accidental `memory/` artifact in the repository did not recur.
-
-### 4.3 Stats reflect imported memory and vectors
-
-Alpha stats:
-
-- Total Events: 6
-- Vector Count: 6
-- Memory Levels: `L0: 6`
-
-This proves import, SQLite storage, embedding queue processing, and vector count all reached a coherent state.
-
-### 4.4 Retrieval finds the right durable decisions
-
-#### Query: lifecycle rule for disclosure expand/source
-
-Top result:
-
-- `agent_response`
-- Score: `1.000`
-- Correct memory: lightweight drill-down; do not call full `MemoryService.initialize()` for expand/source.
-
-This is highly useful: it recovers a nuanced architectural constraint from a later query.
-
-#### Query: SQLite FTS `T.event_id` fix
-
-Top result:
-
-- `agent_response`
-- Score: `0.978`
-- Correct memory: internal FTS5 table with `event_id UNINDEXED`, rebuild by dropping/recreating FTS and triggers.
-
-Second result:
-
-- Original user question, score `0.905`.
-
-This is also useful. It retrieves both the answer and the originating question.
-
-#### Query: dashboard shared provenance
-
-Top and only result:
-
-- `agent_response`
-- Score: `1.000`
-- Correct memory: `shared_troubleshooting`, `sourceProjectHash`, `sourceEntryId`, `topics`, `rootCause`, `solution`.
-
-This is excellent for product/UX decision recall.
-
-### 4.5 Project scoping works for cross-project conflict
-
-Alpha query for `DuckDB legacy storage migrate` did **not** return the beta DuckDB memory and, after the technical-identifier guard, returned **zero** alpha-project false positives.
-
-Beta query for the same phrase returned the beta DuckDB prompt/answer with high scores:
-
-- `user_prompt`, score `1.000`
-- `agent_response`, score `0.922`
-
-So strict project isolation is working at the storage/retrieval boundary.
-
-### 4.6 Progressive disclosure is useful and inspectable
-
-Disclosure query for FTS returned:
-
-```text
-Meta: total=2 vector=no keyword=yes fallback=no
-1. [source] Agent response
-   id: event:<uuid>
-   score: 1.000
-   reasons: keyword_match, recent_relevance, continuity_link
-```
-
-`expand` on the first result returned surrounding turn context:
-
-- previous lifecycle decision
-- target FTS answer
-- neighboring dashboard provenance question/answer
-
-`source` returned raw event details:
-
-- sourceRef
-- sourceType: `imported_history`
-- eventIds
-- full raw event content
-- session id
-- canonical key
-
-This is a strong product surface: the model/user can inspect not just the snippet but why the memory exists and what conversation context surrounded it.
-
-## 5. Problems discovered
-
-### P0 — Built CLI initially failed because of duplicate `fileURLToPath`
-
-The first audit run found that `node dist/cli/index.js ...` failed before any memory command ran:
-
-```text
-SyntaxError: Identifier 'fileURLToPath' has already been declared
-```
-
-Cause:
-
-- `scripts/build.ts` injects an esbuild banner that declares `fileURLToPath`.
-- `src/apps/server/index.ts` also imported `fileURLToPath` under the same identifier.
-- Because CLI bundles server/dashboard code, the duplicate identifier broke the built CLI.
-
-Fix applied:
-
-- Changed server import to alias the identifier:
-  - `import { fileURLToPath as fileUrlToPath } from 'url';`
-  - `fileUrlToPath(import.meta.url)`
-
-Verification:
-
-- `npm run build`
-- `node dist/cli/index.js --help`
-- full memory audit rerun successfully.
-
-### P1 — HuggingFace/transformer warnings were noisy in normal CLI flows — fixed
-
-The first run emitted known benign transformer warnings on import/stats/search. The improved run no longer shows these warnings in the raw CLI outputs.
-
-Implemented:
-
-- Known benign warnings are suppressed around lazy `@huggingface/transformers` pipeline loading/initialization.
-
-Remaining recommendation:
-
-- Consider further reducing embedder initialization on pure stats/read paths, but the user-facing warning noise is fixed.
-
-### P1 — Search returned plausible but irrelevant results on no-match artifact queries — fixed
-
-Noise query:
-
-```bash
-search "local-command-stdout command-name opus" --project alpha --top-k 5 --min-score 0.1
-```
-
-Improved result:
-
-- `Confidence: none`
-- `Total local memories found: 0`
-
-Implemented:
-
-- Query-time command artifact guard for `local-command-stdout`, `local-command-stderr`, `command-name`, and `command-message` patterns.
-- Regression coverage in `tests/core/retriever-strategy-scope.test.ts`.
-
-### P1 — Out-of-domain project-scoped queries returned irrelevant in-project memories — fixed
-
-Alpha query:
-
-```bash
-search "DuckDB legacy storage migrate" --project alpha
-```
-
-Improved result:
-
-- `Confidence: none`
-- `Total local memories found: 0`
-
-Beta query for the same phrase still returns the correct beta DuckDB memory, so the guard improves precision without breaking positive technical-identifier recall.
-
-Implemented:
-
-- Technical identifier lexical guard for terms such as `DuckDB`, `T.event_id`, and `sourceProjectHash`.
-- Regression coverage proving false positives are filtered while exact technical matches are preserved.
-
-### P2 — Top-k included adjacent but not always relevant memories — improved
-
-For the FTS query, top 1 and top 2 were excellent, but the first run included an unrelated dashboard provenance third result.
-
-Improved result:
-
-- The same FTS query now returns only the two directly relevant memories.
-
-Implemented:
-
-- A conservative score-cliff cutoff after reranking/scope filtering.
-
-Remaining recommendation:
-
-- For prompt injection, continue to prefer `confidence=high` results and keep suggested results separated from injected context.
-
-### P2 — Progressive disclosure reason labels were misleading in keyword-only mode — fixed
-
-Disclosure meta says:
-
-```text
-vector=no keyword=yes
-```
-
-Improved result reasons now say:
-
-```text
-keyword_match, recent_relevance, continuity_link
-```
-
-Implemented:
-
-- Disclosure reason mapping omits `semantic_match` when vector/deep retrieval was not used.
-- Regression coverage in `tests/core/retrieval-disclosure-service.test.ts`.
-
-## 6. Remaining next improvements, prioritized
-
-The originally identified precision/UX items have mostly been addressed in this slice. Remaining useful follow-ups:
-
-### Priority 1 — Further reduce unnecessary embedder initialization
-
-Known warning noise is now suppressed, but read paths may still initialize the embedder.
-
-Improve:
-
-- `stats` should use a lightweight/read-only service path when possible.
-- `search --strategy fast` should avoid embedder initialization until deep/vector search is actually needed.
-
-Expected impact:
-
-- Faster stats/search commands.
-- Lower CPU/model-load overhead.
-
-### Priority 2 — Make prompt-injection policy stricter than CLI search
-
-CLI search can show suggested results, but prompt injection should be more conservative.
-
-Improve:
-
-- Inject only high-confidence memories by default.
-- Keep suggested results visible in CLI/dashboard but separate from automatic context injection.
-
-Expected impact:
-
-- Lower memory hallucination risk in real Claude hooks.
-
-### Priority 3 — Add more real-world benchmark scenarios
-
-This audit used crafted sessions. Add broader replay suites:
-
-- 20-50 actual anonymized coding sessions.
-- Known-answer queries and negative/no-match queries.
-- Precision@k / recall@k tracking across refactors.
-
-## 7. Overall verdict
-
-The memory layer is already useful for durable engineering recall:
-
-- It successfully remembered architectural constraints, bug-fix details, and UI provenance decisions.
-- It recovered the right memories from later, differently phrased queries.
-- Project scoping prevented a deliberately conflicting beta project memory from leaking into alpha search.
-- Progressive disclosure gave enough context and raw source provenance to trust a retrieved memory.
-
-After the follow-up fixes, the biggest remaining quality issue is no longer basic precision; it is **operational efficiency and broader benchmarking**:
-
-- Avoid unnecessary embedder/model initialization on pure read paths where possible.
-- Keep automatic prompt injection stricter than exploratory CLI/dashboard search.
-- Expand the benchmark from crafted scenarios to larger anonymized real-session replay suites.