claude-memory-layer 1.0.31 → 1.0.33

package/docs/MEMORY_USEFULNESS_AUDIT_RAW.json

@@ -1,80 +0,0 @@
-{
-  "root": "/var/folders/vw/0ts5bq8n0k31vy_y7t0pd1nw0000gp/T/cml-usefulness-5q7j2p0p",
-  "home": "/var/folders/vw/0ts5bq8n0k31vy_y7t0pd1nw0000gp/T/cml-usefulness-5q7j2p0p/home",
-  "project_a": "/var/folders/vw/0ts5bq8n0k31vy_y7t0pd1nw0000gp/T/cml-usefulness-5q7j2p0p/projects/alpha-commerce-ai",
-  "project_b": "/var/folders/vw/0ts5bq8n0k31vy_y7t0pd1nw0000gp/T/cml-usefulness-5q7j2p0p/projects/beta-legacy-duckdb",
-  "results": [
-    {
-      "label": "import alpha crafted Claude session",
-      "exit": 0,
-      "cmd": "node /Users/namsangboy/workspace/claude-memory-layer/dist/cli/index.js import --session /var/folders/vw/0ts5bq8n0k31vy_y7t0pd1nw0000gp/T/cml-usefulness-5q7j2p0p/alpha-session.jsonl --project /var/folders/vw/0ts5bq8n0k31vy_y7t0pd1nw0000gp/T/cml-usefulness-5q7j2p0p/projects/alpha-commerce-ai --verbose",
-      "output": "\n⏳ Initializing memory service...\n  ✅ Ready (embedder: jinaai/jina-embeddings-v5-text-nano-text-matching)\n\n📥 Importing session: /var/folders/vw/0ts5bq8n0k31vy_y7t0pd1nw0000gp/T/cml-usefulness-5q7j2p0p/alpha-session.jsonl\n   Target: /var/folders/vw/0ts5bq8n0k31vy_y7t0pd1nw0000gp/T/cml-usefulness-5q7j2p0p/projects/alpha-commerce-ai\n\n\n  📄 [1/...] 1 msgs | +1 imported, ~0 skipped Imported 3 prompts, 3 responses from /var/folders/vw/0ts5bq8n0k31vy_y7t0pd1nw0000gp/T/cml-usefulness-5q7j2p0p/alpha-session.jsonl\n\n🧠 Processing embeddings...\n\n┌─────────────────────────────────┐\n│       ✅ Import Complete         │\n├─────────────────────────────────┤\n│  Sessions processed:         1 │\n│  Total messages:             7 │\n│  Imported prompts:           3 │\n│  Imported responses:         3 │\n│  Skipped duplicates:         1 │\n│  Embeddings queued:          6 │\n└─────────────────────────────────┘\n\n⏱️  Completed in 1.7s\n"
-    },
-    {
-      "label": "import beta conflicting project session",
-      "exit": 0,
-      "cmd": "node /Users/namsangboy/workspace/claude-memory-layer/dist/cli/index.js import --session /var/folders/vw/0ts5bq8n0k31vy_y7t0pd1nw0000gp/T/cml-usefulness-5q7j2p0p/beta-session.jsonl --project /var/folders/vw/0ts5bq8n0k31vy_y7t0pd1nw0000gp/T/cml-usefulness-5q7j2p0p/projects/beta-legacy-duckdb --verbose",
-      "output": "\n⏳ Initializing memory service...\n  ✅ Ready (embedder: jinaai/jina-embeddings-v5-text-nano-text-matching)\n\n📥 Importing session: /var/folders/vw/0ts5bq8n0k31vy_y7t0pd1nw0000gp/T/cml-usefulness-5q7j2p0p/beta-session.jsonl\n   Target: /var/folders/vw/0ts5bq8n0k31vy_y7t0pd1nw0000gp/T/cml-usefulness-5q7j2p0p/projects/beta-legacy-duckdb\n\n\n  📄 [1/...] 1 msgs | +1 imported, ~0 skipped Imported 1 prompts, 1 responses from /var/folders/vw/0ts5bq8n0k31vy_y7t0pd1nw0000gp/T/cml-usefulness-5q7j2p0p/beta-session.jsonl\n\n🧠 Processing embeddings...\n\n┌─────────────────────────────────┐\n│       ✅ Import Complete         │\n├─────────────────────────────────┤\n│  Sessions processed:         1 │\n│  Total messages:             2 │\n│  Imported prompts:           1 │\n│  Imported responses:         1 │\n│  Skipped duplicates:         0 │\n│  Embeddings queued:          2 │\n└─────────────────────────────────┘\n\n⏱️  Completed in 1.4s\n"
-    },
-    {
-      "label": "alpha stats",
-      "exit": 0,
-      "cmd": "node /Users/namsangboy/workspace/claude-memory-layer/dist/cli/index.js stats --project /var/folders/vw/0ts5bq8n0k31vy_y7t0pd1nw0000gp/T/cml-usefulness-5q7j2p0p/projects/alpha-commerce-ai",
-      "output": "\n📊 Memory Statistics\n\nTotal Events: 6\nVector Count: 6\n\nMemory Levels:\n  L0: █ 6\n"
-    },
-    {
-      "label": "Q1 lifecycle lightweight expand/source",
-      "exit": 0,
-      "cmd": "node /Users/namsangboy/workspace/claude-memory-layer/dist/cli/index.js search disclosure expand source initialize vector workers lightweight --project /var/folders/vw/0ts5bq8n0k31vy_y7t0pd1nw0000gp/T/cml-usefulness-5q7j2p0p/projects/alpha-commerce-ai --top-k 5 --min-score 0.1",
-      "output": "\n📚 Search Results\n\nConfidence: high\nTotal local memories found: 3\nShared memories found: 0\n\n---\n📌 agent_response (2026-05-05)\n   Score: 1.000\n   Session: alpha-se...\n   Content: Decision recorded: For progressive retrieval disclosure, expand/source drill-down routes must stay lightweight. Do not call full MemoryService.initialize for disclosure expand/source because it can...\n\n---\n📌 agent_response (2026-05-05)\n   Score: 0.829\n   Session: alpha-se...\n   Content: Dashboard provenance decision: shared disclosure results should be rendered as shared_troubleshooting provenance, showing sourceProjectHash, sourceEntryId, topics, rootCause, and solution. The UI m...\n\n---\n📌 user_prompt (2026-05-05)\n   Score: 0.773\n   Session: alpha-se...\n   Content: When adding retrieval disclosure API routes, what lifecycle rule should we remember?\n\n"
-    },
-    {
-      "label": "Q2 FTS T.event_id fix",
-      "exit": 0,
-      "cmd": "node /Users/namsangboy/workspace/claude-memory-layer/dist/cli/index.js search T.event_id FTS rebuild internal table trigger event_id --project /var/folders/vw/0ts5bq8n0k31vy_y7t0pd1nw0000gp/T/cml-usefulness-5q7j2p0p/projects/alpha-commerce-ai --top-k 5 --min-score 0.1",
-      "output": "\n📚 Search Results\n\nConfidence: high\nTotal local memories found: 2\nShared memories found: 0\n\n---\n📌 agent_response (2026-05-05)\n   Score: 0.978\n   Session: alpha-se...\n   Content: Bug fix recorded: SQLite FTS rebuild failure 'no such column: T.event_id' is fixed by making events_fts an internal FTS5 table with columns content and event_id UNINDEXED using porter unicode61 tok...\n\n---\n📌 user_prompt (2026-05-05)\n   Score: 0.905\n   Session: alpha-se...\n   Content: How did we fix the SQLite FTS rebuild T.event_id failure?\n\n"
-    },
-    {
-      "label": "Q3 shared provenance dashboard",
-      "exit": 0,
-      "cmd": "node /Users/namsangboy/workspace/claude-memory-layer/dist/cli/index.js search shared_troubleshooting rootCause solution sourceProjectHash --project /var/folders/vw/0ts5bq8n0k31vy_y7t0pd1nw0000gp/T/cml-usefulness-5q7j2p0p/projects/alpha-commerce-ai --top-k 5 --min-score 0.1",
-      "output": "\n📚 Search Results\n\nConfidence: high\nTotal local memories found: 1\nShared memories found: 0\n\n---\n📌 agent_response (2026-05-05)\n   Score: 1.000\n   Session: alpha-se...\n   Content: Dashboard provenance decision: shared disclosure results should be rendered as shared_troubleshooting provenance, showing sourceProjectHash, sourceEntryId, topics, rootCause, and solution. The UI m...\n\n"
-    },
-    {
-      "label": "Q4 noise command artifact should not retrieve",
-      "exit": 0,
-      "cmd": "node /Users/namsangboy/workspace/claude-memory-layer/dist/cli/index.js search local-command-stdout command-name opus --project /var/folders/vw/0ts5bq8n0k31vy_y7t0pd1nw0000gp/T/cml-usefulness-5q7j2p0p/projects/alpha-commerce-ai --top-k 5 --min-score 0.1",
-      "output": "\n📚 Search Results\n\nConfidence: none\nTotal local memories found: 0\nShared memories found: 0\n\n"
-    },
-    {
-      "label": "Q5 project scoping negative DuckDB from alpha",
-      "exit": 0,
-      "cmd": "node /Users/namsangboy/workspace/claude-memory-layer/dist/cli/index.js search DuckDB legacy storage migrate --project /var/folders/vw/0ts5bq8n0k31vy_y7t0pd1nw0000gp/T/cml-usefulness-5q7j2p0p/projects/alpha-commerce-ai --top-k 5 --min-score 0.1",
-      "output": "\n📚 Search Results\n\nConfidence: none\nTotal local memories found: 0\nShared memories found: 0\n\n"
-    },
-    {
-      "label": "Q6 beta project positive DuckDB",
-      "exit": 0,
-      "cmd": "node /Users/namsangboy/workspace/claude-memory-layer/dist/cli/index.js search DuckDB legacy storage migrate --project /var/folders/vw/0ts5bq8n0k31vy_y7t0pd1nw0000gp/T/cml-usefulness-5q7j2p0p/projects/beta-legacy-duckdb --top-k 5 --min-score 0.1",
-      "output": "\n📚 Search Results\n\nConfidence: high\nTotal local memories found: 2\nShared memories found: 0\n\n---\n📌 user_prompt (2026-05-05)\n   Score: 1.000\n   Session: beta-ses...\n   Content: For the beta legacy storage project, should we migrate away from DuckDB?\n\n---\n📌 agent_response (2026-05-05)\n   Score: 0.922\n   Session: beta-ses...\n   Content: Legacy beta project decision: this old unrelated project should keep DuckDB and should not migrate to SQLite. This memory intentionally conflicts with alpha-commerce-ai and is used to test strict p...\n\n"
-    },
-    {
-      "label": "Q7 disclosure FTS query",
-      "exit": 0,
-      "cmd": "node /Users/namsangboy/workspace/claude-memory-layer/dist/cli/index.js search T.event_id FTS rebuild internal table --project /var/folders/vw/0ts5bq8n0k31vy_y7t0pd1nw0000gp/T/cml-usefulness-5q7j2p0p/projects/alpha-commerce-ai --top-k 3 --min-score 0.1 --disclosure --strategy fast",
-      "output": "\n🔎 Progressive Search Results\n\nMeta: total=2 vector=no keyword=yes fallback=no\n\n1. [source] Agent response\n   id: event:a5a01a44-67cb-4cef-b0e5-44c72925db9c\n   score: 1.000\n   reasons: keyword_match, recent_relevance, continuity_link\n   source: event:a5a01a44-67cb-4cef-b0e5-44c72925db9c\n   session: alpha-sessio...\n   snippet: Bug fix recorded: SQLite FTS rebuild failure 'no such column: T.event_id' is fixed by making events_fts an internal FTS5 table with columns content and event_id UNINDEXED using porter unicode61 tokenization. Rebuild by dropping and recre...\n\n2. [source] User prompt\n   id: event:eb14f3db-0aeb-424d-ae96-b2d6baefb731\n   score: 0.905\n   reasons: keyword_match, recent_relevance, continuity_link\n   source: event:eb14f3db-0aeb-424d-ae96-b2d6baefb731\n   session: alpha-sessio...\n   snippet: How did we fix the SQLite FTS rebuild T.event_id failure?\n\n"
-    },
-    {
-      "label": "Q8 expand first disclosure result",
-      "exit": 0,
-      "cmd": "node /Users/namsangboy/workspace/claude-memory-layer/dist/cli/index.js expand event:a5a01a44-67cb-4cef-b0e5-44c72925db9c --project /var/folders/vw/0ts5bq8n0k31vy_y7t0pd1nw0000gp/T/cml-usefulness-5q7j2p0p/projects/alpha-commerce-ai --window-size 2",
-      "output": "\n🧩 Expanded Retrieval Result\n\nTarget\n- [source] Agent response\n   id: event:a5a01a44-67cb-4cef-b0e5-44c72925db9c\n   score: 1.000\n   reasons: continuity_link\n   source: event:a5a01a44-67cb-4cef-b0e5-44c72925db9c\n   session: alpha-sessio...\n   snippet: Bug fix recorded: SQLite FTS rebuild failure 'no such column: T.event_id' is fixed by making events_fts an internal FTS5 table with columns content and event_id UNINDEXED using porter unicode61 tokenization. Rebuild by dropping and recre...\n\n\nSurrounding\n1. [source] Agent response\n   id: event:c0c2e795-eb98-4354-9ce0-cf453d967a87\n   score: 1.000\n   reasons: continuity_link\n   source: event:c0c2e795-eb98-4354-9ce0-cf453d967a87\n   session: alpha-sessio...\n   snippet: Decision recorded: For progressive retrieval disclosure, expand/source drill-down routes must stay lightweight. Do not call full MemoryService.initialize for disclosure expand/source because it can start embedders, vector workers, and sh...\n\n2. [source] User prompt\n   id: event:eb14f3db-0aeb-424d-ae96-b2d6baefb731\n   score: 1.000\n   reasons: continuity_link\n   source: event:eb14f3db-0aeb-424d-ae96-b2d6baefb731\n   session: alpha-sessio...\n   snippet: How did we fix the SQLite FTS rebuild T.event_id failure?\n\n3. [source] User prompt\n   id: event:34f59596-f65f-4520-9a88-6ba835b8018a\n   score: 1.000\n   reasons: continuity_link\n   source: event:34f59596-f65f-4520-9a88-6ba835b8018a\n   session: alpha-sessio...\n   snippet: For dashboard shared retrieval provenance, what should the UI show?\n\n4. [source] Agent response\n   id: event:9b376621-c598-42fc-826a-306b3603ba18\n   score: 1.000\n   reasons: continuity_link\n   source: event:9b376621-c598-42fc-826a-306b3603ba18\n   session: alpha-sessio...\n   snippet: Dashboard provenance decision: shared disclosure results should be rendered as shared_troubleshooting provenance, showing sourceProjectHash, sourceEntryId, topics, rootCause, and solution. The UI must state that there are no local raw ev...\n\n\nSources\n- event:c0c2e795-eb98-4354-9ce0-cf453d967a87 (imported_history) events=c0c2e795-eb98-4354-9ce0-cf453d967a87\n- event:eb14f3db-0aeb-424d-ae96-b2d6baefb731 (imported_history) events=eb14f3db-0aeb-424d-ae96-b2d6baefb731\n- event:a5a01a44-67cb-4cef-b0e5-44c72925db9c (imported_history) events=a5a01a44-67cb-4cef-b0e5-44c72925db9c\n- event:34f59596-f65f-4520-9a88-6ba835b8018a (imported_history) events=34f59596-f65f-4520-9a88-6ba835b8018a\n- event:9b376621-c598-42fc-826a-306b3603ba18 (imported_history) events=9b376621-c598-42fc-826a-306b3603ba18\n\nExpanded Context\n[agent_response] Decision recorded: For progressive retrieval disclosure, expand/source drill-down routes must stay lightweight. Do not call full MemoryService.initialize for disclosure expand/source because it can start embedders, vector workers, and shared promotion machinery. Use narrow SQLiteEventStore getEvent/getSessionEvents or shared-store lookup ports instead. API tests should assert initialize is not called for GET expand/source routes, including 404 paths.\n\n[user_prompt] How did we fix the SQLite FTS rebuild T.event_id failure?\n\n[agent_response] Bug fix recorded: SQLite FTS rebuild failure 'no such column: T.event_id' is fixed by making events_fts an internal FTS5 table with columns content and event_id UNINDEXED using porter unicode61 tokenization. Rebuild by dropping and recreating events_fts and then recreate triggers that write rowid, content, and event_id. Also cover deleteSessionEvents followed by rebuildFtsIndex.\n\n[user_prompt] For dashboard shared retrieval provenance, what should the UI show?\n\n[agent_response] Dashboard provenance decision: shared disclosure results should be rendered as shared_troubleshooting provenance, showing sourceProjectHash, sourceEntryId, topics, rootCause, and solution. The UI must state that there are no local raw events for a shared source instead of pretending shared memories are local event IDs. Escape all metadata before innerHTML rendering.\n\n"
-    },
-    {
-      "label": "Q9 source first disclosure result",
-      "exit": 0,
-      "cmd": "node /Users/namsangboy/workspace/claude-memory-layer/dist/cli/index.js source event:a5a01a44-67cb-4cef-b0e5-44c72925db9c --project /var/folders/vw/0ts5bq8n0k31vy_y7t0pd1nw0000gp/T/cml-usefulness-5q7j2p0p/projects/alpha-commerce-ai",
-      "output": "\n📎 Retrieval Source\n\nsourceRef: event:a5a01a44-67cb-4cef-b0e5-44c72925db9c\nsourceType: imported_history\neventIds: a5a01a44-67cb-4cef-b0e5-44c72925db9c\n\nRaw Events\n- a5a01a44-67cb-4cef-b0e5-44c72925db9c 2026-05-05T01:38:20.318Z\n  [agent_response] Bug fix recorded: SQLite FTS rebuild failure 'no such column: T.event_id' is fixed by making events_fts an internal FTS5 table with columns content and event_id UNINDEXED using porter unicode61 tokenization. Rebuild by dropping and recreating events_fts and then recreate triggers that write rowid, content, and event_id. Also cover deleteSessionEvents followed by rebuildFtsIndex.\n  session: alpha-session\n  canonicalKey: bug fix recorded sqlite fts rebuild failure no such column teventid is fixed by making eventsfts an internal fts5 table with columns content and eventid unindexed using porter unicode61 token_2e1a5fce\n\n"
-    }
-  ]
-}

package/docs/MEMSEARCH_PROJECT_STRUCTURE_ANALYSIS.md

@@ -1,333 +0,0 @@
-<!-- Imported from `/Users/namsangboy/workspace/memsearch/docs/PROJECT_STRUCTURE_ANALYSIS.md` as a local comparison snapshot for claude-memory-layer refactoring. -->
-
-# memsearch 프로젝트 구조 분석
-
-## 한 줄 요약
-`memsearch`는 **markdown을 source of truth로 삼고, Milvus를 파생 인덱스로 사용하는 가볍고 실용적인 semantic memory/search 엔진**이다. 코어 라이브러리는 비교적 작고 명확하며, 복잡성의 대부분은 각 에이전트/플랫폼용 플러그인 통합 계층에 있다.
-
----
-
-## 1. 프로젝트 목적
-
-이 프로젝트의 핵심 목적은 다음이다.
-
-- markdown 기반 메모리/지식 문서를 semantic search 가능하게 인덱싱
-- 여러 AI coding agent/도구(Claude Code, Codex, OpenClaw, OpenCode)에서 공통 memory layer로 활용
-- 기억의 “원본”은 사람이 읽고 편집 가능한 markdown으로 유지
-- 벡터 DB는 언제든 다시 만들 수 있는 파생 인덱스로 취급
-
-즉, 이 프로젝트는 **vector DB 중심 시스템**이 아니라,
-**markdown 중심 메모리 시스템**에 더 가깝다.
-
----
-
-## 2. 기술 스택
-
-### 언어 / 런타임
-- Python 3.10+
-- 일부 플러그인은 shell / TypeScript / Node 조합
-
-### 핵심 라이브러리
-- CLI: `click`
-- 벡터 저장소: `pymilvus` / Milvus Lite
-- 파일 감시: `watchdog`
-- 임베딩 제공자: OpenAI / Google / Voyage / Jina / Mistral / Ollama / local / ONNX
-- 문서/툴링: mkdocs, pytest, ruff, uv
-
-### 주요 엔트리 포인트
-- Python API: `src/memsearch/core.py`
-- CLI: `src/memsearch/cli.py`
-- 모듈 실행: `src/memsearch/__main__.py`
-- 플랫폼 플러그인: `plugins/*`
-
----
-
-## 3. 디렉터리 구조 분석
-
-### `src/memsearch/`
-코어 라이브러리 영역이다.
-
-주요 파일:
-- `core.py`: 공개 API `MemSearch`
-- `store.py`: Milvus wrapper, hybrid retrieval
-- `chunker.py`: markdown chunking, chunk ID 생성
-- `scanner.py`: markdown 파일 스캔
-- `watcher.py`: 파일 변경 감지 및 debounce
-- `config.py`: layered TOML config
-- `compact.py`: LLM 기반 요약/압축
-- `reranker.py`: optional cross-encoder rerank
-- `embeddings/*`: provider abstraction
-
-이 구조는 매우 명확하다.
-핵심 기능이 파일 단위로 잘 나뉘어 있고, 각 모듈의 책임이 비교적 분명하다.
-
-### `plugins/`
-플랫폼별 통합 레이어다.
-
-구성:
-- `claude-code/`
-- `codex/`
-- `openclaw/`
-- `opencode/`
-- `_shared/`
-
-즉, 메모리 엔진은 공통이고,
-각 에이전트별 capture/retrieval/injection 방식을 다르게 붙이는 구조다.
-
-### `tests/`
-chunking, config, store, CLI, transcript 파싱 등 코어 품질을 검증한다.
-
-### `docs/`
-문서 품질이 높은 편이다.
-아키텍처 설명, 플랫폼별 설치, 설정, FAQ, CLI 등이 비교적 잘 정리되어 있다.
-
----
-
-## 4. 데이터 모델
-
-### 4.1 Source of truth = Markdown
-이 프로젝트에서 가장 중요한 원칙이다.
-
-메모리는 결국 markdown 파일이다.
-예:
-- `.memsearch/memory/YYYY-MM-DD.md`
-
-장점:
-- 사람이 직접 읽고 수정 가능
-- git 관리 가능
-- vendor lock-in이 약함
-- 인덱스가 깨져도 원본은 남음
-
-### 4.2 Vector index = Milvus
-Milvus는 파생 검색 인덱스다.
-
-대표 스키마 필드:
-- `chunk_hash` (PK)
-- `embedding`
-- `sparse_vector`
-- `content`
-- `source`
-- `heading`
-- `heading_level`
-- `start_line`
-- `end_line`
-
-즉,
-**문서 provenance를 꽤 잘 보존하는 chunk index** 구조다.
-
-### 4.3 Chunk ID 전략
-`chunker.py`의 composite ID 설계가 핵심이다.
-
-대략 구성:
-- source
-- line range
-- content hash
-- model
-
-이 방식의 장점:
-- 자연스러운 dedupe
-- 변경 감지 쉬움
-- 파일 일부만 바뀌어도 필요한 chunk만 재색인 가능
-
----
-
-## 5. 인덱싱 파이프라인
-
-코어 흐름은 매우 직관적이다.
-
-### 단계
-1. `scanner.py`가 markdown 파일 탐색
-2. `chunker.py`가 heading 기반 분할
-3. 필요 시 oversized section을 추가 분할
-4. content 정리 후 embedding 생성
-5. `store.py`가 Milvus에 upsert
-6. 기존 chunk와 비교해서 stale chunk 삭제
-
-특징:
-- heading 중심 chunking
-- preamble chunk 지원
-- line overlap 지원
-- HTML comment 제거 후 embedding
-- changed chunk만 재처리
-
-즉, 단순하지만 실전적인 indexing pipeline이다.
-
----
-
-## 6. 검색 구조
-
-### hybrid retrieval
-이 프로젝트의 핵심 강점이다.
-
-- dense vector search
-- BM25 sparse search
-- RRF(Reciprocal Rank Fusion)
-
-즉, vector-only가 아니라 lexical 검색을 기본 결합한다.
-이건 실제 회상 정확도에서 꽤 중요하다.
-
-### progressive disclosure
-- L1: search
-- L2: expand (원문 markdown section 복원)
-- L3: transcript drill-down (플랫폼별)
-
-특히 Claude Code plugin은 이 구조를 잘 활용한다.
-
-### optional reranker
-추가적으로 cross-encoder reranker도 붙일 수 있다.
-하지만 기본은 비교적 가볍게 유지되어 있다.
-
----
-
-## 7. 플랫폼 플러그인 구조
-
-`memsearch`의 진짜 복잡성은 여기 있다.
-코어보다 플러그인 계층이 훨씬 운영적으로 까다롭다.
-
-### Claude Code 플러그인
-구성 요소:
-- hooks
-- shared shell runtime (`common.sh`)
-- transcript parser
-- `memory-recall` skill
-
-역할:
-- SessionStart 시 최근 메모리 주입
-- Stop 시 마지막 턴 요약/기록
-- Skill을 통한 forked memory recall
-
-이건 단순 자동 검색보다 더 세련된 구조다.
-메인 컨텍스트를 더럽히지 않고 recall을 subagent skill로 위임한다.
-
-### Codex 플러그인
-Claude 구조와 유사하지만,
-Codex lifecycle 제약(SessionEnd 부재 등) 때문에 프로세스 정리 로직이 더 복잡하다.
-
-### OpenClaw 플러그인
-TypeScript 기반 plugin으로 붙어 있으며,
-메모리 검색/원문 조회/트랜스크립트 조회 도구를 제공한다.
-
-### OpenCode 플러그인
-가장 무거운 편이다.
-배경 Python daemon이 SQLite를 polling하며 새 턴을 요약/기록한다.
-
----
-
-## 8. Watch / Sync 구조
-
-`watcher.py`는 `watchdog` 기반의 debounce watcher다.
-
-하지만 플러그인 레벨에서는 백엔드 종류에 따라 전략이 달라진다.
-
-- Milvus server/remote: 장기 watch 가능
-- Milvus Lite: file lock 문제 때문에 일회성 index 위주 fallback
-
-즉, 저장소 기술 선택이 integration 전략에 직접 영향을 준다.
-
----
-
-## 9. 설정 구조
-
-`config.py`는 layered configuration 구조를 가진다.
-
-우선순위:
-1. defaults
-2. `~/.memsearch/config.toml`
-3. 프로젝트 로컬 `.memsearch.toml`
-4. CLI flags
-
-장점:
-- 사용성과 운영 flexibility가 좋음
-- 전역/로컬 설정 분리가 자연스러움
-
-또한 secret을 `env:VAR_NAME` 으로 간접 참조할 수 있어 실전성이 높다.
-
----
-
-## 10. 테스트 / 품질 평가
-
-이 저장소는 코어 라이브러리 품질 신호가 좋다.
-
-강점:
-- chunker / config / store / scanner / transcript 등 핵심 경로 테스트 존재
-- CI, lint, format 정리되어 있음
-- 코어가 작아서 테스트 범위를 잡기 쉬움
-
-한계:
-- 플랫폼 integration 전체를 완전히 일관되게 검증하기는 어렵다
-- 일부 경로는 외부 API/환경 의존이 있다
-
-즉,
-- **core는 비교적 단단함**
-- **plugin edge는 환경 의존성이 큼**
-
----
-
-## 11. 아키텍처 강점
-
-### 강점 1: source of truth가 명확하다
-markdown이 원본이다.
-이건 설명 가능성, 복구성, 이식성 면에서 매우 큰 장점이다.
-
-### 강점 2: 코어가 작고 선명하다
-scanner → chunker → embedder → store 라는 파이프라인이 아주 명료하다.
-
-### 강점 3: hybrid retrieval 기본 제공
-실전 회상 품질을 높이는 중요한 선택이다.
-
-### 강점 4: 플러그인 분리 구조가 좋다
-코어 메모리 엔진과 각 에이전트 통합 레이어가 비교적 깔끔하게 분리돼 있다.
-
-### 강점 5: progressive disclosure 철학
-search → expand → transcript drill-down은 메모리 시스템 UX 측면에서 매우 좋다.
-
----
-
-## 12. 약점 / 리스크
-
-### 약점 1: Milvus 의존성
-문서 원본은 markdown이지만, 실제 semantic search 운영은 Milvus 특성에 많이 의존한다.
-
-### 약점 2: 플랫폼별 유지보수 비용
-Claude/Codex/OpenClaw/OpenCode 각각 lifecycle과 transcript format이 다르므로 plugin maintenance cost가 커진다.
-
-### 약점 3: shell hook brittleness
-shell script 기반 훅은 OS/환경 차이, PATH, 프로세스 정리 등에서 취약할 수 있다.
-
-### 약점 4: Lite 모드 동시성 제약
-Milvus Lite file lock 문제로 이상적인 watch 구조를 항상 쓰기 어렵다.
-
-### 약점 5: 메타데이터 모델은 상대적으로 얇다
-현재는 markdown chunk 중심 구조라,
-고급 엔티티 그래프, task graph, helpfulness 학습 같은 계층은 상대적으로 약하다.
-
----
-
-## 13. 구조적 해석
-
-`memsearch`는 크게 두 부분으로 나뉜다.
-
-1. **아주 잘 정리된 코어 라이브러리**
-2. **상대적으로 복잡한 플랫폼별 통합 계층**
-
-즉,
-“엔진은 가볍고 선명한데, 실제 제품화 complexity는 integration에 있다.”
-
-이 점이 매우 중요하다.
-
----
-
-## 14. 결론
-
-`memsearch`는 무거운 메모리 플랫폼이 아니라,
-**좋은 철학을 가진 가벼운 semantic memory engine** 이다.
-
-핵심적으로 배울 점은 다음이다.
-- 원본을 markdown에 두는 것
-- 코어를 작게 유지하는 것
-- retrieval을 hybrid로 설계하는 것
-- 플랫폼 통합을 core 밖으로 밀어내는 것
-- progressive disclosure로 UX를 설계하는 것
-
-즉, 이 프로젝트는 “엄청 많은 기능”보다,
-**작지만 강한 코어와 좋은 메모리 UX 패턴**이 매력인 구조다.

package/docs/MEMU_ADOPTION.md

@@ -1,40 +0,0 @@
-# memU Adoption Notes (claude-memory-layer)
-
-이 프로젝트에 적용된 memU 장점 요약입니다.
-
-## 1) Dual Retrieval Strategy
-- `strategy: "fast" | "deep" | "auto"`
-- `fast`: 키워드 기반(FTS/keyword) 우선 탐색으로 저지연 검색
-- `deep`: 임베딩 + 벡터 검색 + 재정렬(키워드 오버랩 가중)로 정밀 검색
-
-## 2) Scoped Retrieval Filters
-`scope`로 검색 범위를 좁혀 정확도를 높입니다.
-
-- `sessionId` / `sessionIdPrefix`
-- `eventTypes`
-- `canonicalKeyPrefix`
-- `contentIncludes` (부분 문자열 OR)
-- `metadata` (dot-path, 예: `scope.project.id`)
-
-## 3) Hybrid Rerank Behavior
-`rerankWithKeyword=true`일 때 semantic score에 키워드 오버랩/최근성 점수를 가중해 재정렬합니다.
-
-## 4) Test Coverage
-- `tests/retriever.memu-adoption.test.ts`
-  - metadata dot-path 스코프 필터
-  - fast 전략 키워드 경로
-- `tests/retriever-strategy-scope.test.ts`
-  - fast/deep 전략 및 복합 스코프 필터
-
-## Quick Example
-```ts
-await retriever.retrieve('브리핑', {
-  strategy: 'deep',
-  topK: 10,
-  scope: {
-    sessionIdPrefix: 'agent:main:',
-    canonicalKeyPrefix: 'pref/briefing',
-    metadata: { 'scope.project.id': 'alpha' }
-  }
-});
-```

package/docs/OPERATIONS.md

@@ -1,18 +0,0 @@
-# Operations Runbook
-
-## Health scripts
-
-- `npm run ops:sync-gap:report`
-- `npm run ops:sync-gap:fix`
-- `npm run ops:sync-gap:heal`
-- `npm run ops:review:resolve`
-- `npm run ops:heartbeat`
-
-## Status policy
-
-- `ok`: no failed outbox items and no un-leveled events after heal
-- `needs-attention`: failed outbox remains or level sync still broken
-
-## Notes
-
-These scripts are best-effort operational automation for Claude memory DB (`~/.claude-code/memory/events.sqlite`).

package/docs/PRODUCT_VALIDATION_MATRIX.md

@@ -1,82 +0,0 @@
-# Product Validation Matrix
-
-This document mirrors the tested matrix in `src/core/product-validation-matrix.ts`. The matrix is data-first so product reports and future CLI/API surfaces can reuse the same surface → requirement → evidence representation.
-
-## Scope
-
-| Area | Surface | Status | Validation intent |
-| --- | --- | --- | --- |
-| Claude | Claude adapter import | covered | Import Claude Code JSONL while filtering tool/local-command noise and preserving turn/project continuity. |
-| Claude | Claude adapter search | covered | Search memory by project/session with plain and disclosure output paths. |
-| Claude | Claude adapter disclosure | covered | Exercise search → expand → source/citation disclosure flow. |
-| Codex | Codex adapter scan | ready | Recursively scan `~/.codex/sessions`, match by `session_meta.payload.cwd`, and count malformed/unsupported records. |
-| Codex | Codex adapter import | covered | Existing explicit import path remains mutation-only; `codex import` now exposes project/session/all imports while validation/replay stay read-only. |
-| Codex | Codex adapter replay | ready | Normalize real Codex `response_item` message records and aggregate replay counts without transcript content. |
-| Hermes | Hermes adapter scan | ready | Read Hermes `~/.hermes/state.db` in read-only mode, match project context, and aggregate unsupported/empty/truncated counts without transcript content. |
-| Hermes | Hermes adapter import | covered | `hermes import` exposes project/session/all imports while preserving SessionDB as raw source-of-truth and storing only redacted user/assistant turns. |
-| Hermes | Hermes adapter replay | ready | Normalize Hermes SessionDB rows into aggregate replay reports without transcript content or secrets. |
-| MCP | MCP context pack | covered | Combine relevant project memories and recent timeline into agent-ready startup context with citations/follow-up refs. |
-| MCP | MCP project timeline | covered | Summarize recent project memory by session, source agent, event counts, and safe preview. |
-| MCP | MCP source reference | covered | Resolve event/mem citation refs into redacted source previews with safe metadata only. |
-| CLI/API | CLI / API / reporting | ready | Provide `claude-memory-layer codex validate` / `codex replay` and `hermes validate` / `hermes replay` with JSON/Markdown reports. |
-| Safety | Safety / dry-run | ready | Default Codex/Hermes validation is read-only, avoids Claude settings/memory mutation, and can exclude transcript content from reports. |
-
-## Codex validation requirements
-
-`claude-memory-layer codex validate` and `claude-memory-layer codex replay` are intentionally read-only. They support:
-
-- `--project <path>`: match sessions whose `session_meta.payload.cwd` resolves to the project path.
-- `--sessions-dir <path>`: override the default `~/.codex/sessions` root.
-- `--limit <number>`: cap the number of session files scanned.
-- `--format json|markdown`: choose machine-readable or human-readable aggregate output.
-- `--output <path>`: save the aggregate report to disk.
-- `--dry-run`: explicit safety marker; mutation is not supported by validation/replay.
-- `--anonymize-projects`: replace raw cwd labels with stable project hashes for shareable reports.
-
-Reports include only aggregate counts: sessions scanned/matched, records read, messages/turns normalized, user/assistant counts, malformed lines, skipped/unsupported records, empty assistant messages, truncated messages, missing cwd, warnings, top projects, and source paths. Transcript text is never included in validation reports.
-
-## Hermes validation requirements
-
-`claude-memory-layer hermes validate` and `claude-memory-layer hermes replay` are intentionally read-only. They support:
-
-- `--project <path>`: match sessions whose Hermes session context/title includes the project path.
-- `--state-db <path>`: override the default `~/.hermes/state.db` source for tests, profiles, or replay fixtures.
-- `--limit <number>`: cap the number of matching sessions scanned.
-- `--format json|markdown`: choose machine-readable or human-readable aggregate output.
-- `--output <path>`: save the aggregate report to disk.
-- `--dry-run`: explicit safety marker; mutation is not supported by validation/replay.
-
-Reports include only aggregate counts: sessions scanned/matched, messages read/normalized, turns normalized, user/assistant counts, skipped/unsupported messages, empty assistant messages, truncated messages, missing project context, warnings, top sources, and source paths. Transcript text is never included in validation reports.
-
-## MCP context navigator requirements
-
-The MCP server exposes read-only project context navigation for Claude Desktop, Codex, Hermes, and other MCP clients. These tools support the same optional `projectPath` scoping as `mem-search`/`mem-stats`:
-
-- `mem-context-pack`: agent startup context pack. It combines relevant retrieval results (`query`, `topK`, optional `sessionId`) with a bounded recent project timeline (`recentLimit`, `sessionLimit`) and returns follow-up citation refs.
-- `mem-project-timeline`: recent project memory grouped by session, source agent/import source, event counts, and a privacy-filtered last preview.
-- `mem-source-ref`: resolves `event:<id>`, full event IDs, `mem:<citation>`, bare citation IDs, or `[mem:<citation>]` into source metadata and a redacted preview.
-
-The tools are intentionally context/navigation-oriented rather than mutation APIs. `mem-source-ref` uses a narrow safe metadata allowlist and shared privacy filtering before returning previews; raw transcript dumps should use lower-level detail APIs only when explicitly needed.
-
-## Codex import requirements
-
-`claude-memory-layer codex import` is the explicit mutation path. It supports:
-
-- `--project <path>`: import matching Codex sessions into the project-scoped memory store.
-- `--session <file>`: import one Codex JSONL session into the selected project scope.
-- `--all`: import all Codex sessions; without `--project`, this intentionally uses global memory and prints a warning.
-- `--sessions-dir <path>`: override the default `~/.codex/sessions` root for tests, replays, or alternate Codex profiles.
-- `--limit <number>`, `--force`, `--verbose`, and `--no-process-embeddings` for bounded/repeatable operational runs.
-
-## Evidence
-
-- `tests/core/product-validation-matrix.test.ts` checks coverage, summary, and Markdown rendering of the matrix.
-- `tests/core/codex-session-history-importer-validation.test.ts` covers Codex dry-run scan/replay, cwd project matching, malformed lines, unsupported/tool-ish records, empty assistant messages, large/truncated content, missing cwd, all-session summary, and transcript exclusion.
-- `tests/apps/codex-validation-output.test.ts` covers JSON and Markdown reporting helpers.
-- `tests/apps/codex-import-runner.test.ts` covers explicit Codex import routing for project, session, and global all-session modes.
-- `tests/extensions/mcp-context-tools.test.ts` covers MCP context-pack/timeline/source-ref routing, output shape, citation refs, safe previews, and secret redaction.
-- `src/extensions/mcp/tools.ts` defines MCP schemas for search/timeline/details/stats and the context navigator tools.
-- `src/extensions/mcp/handlers.ts` implements project-aware MCP tool dispatch and privacy-safe context navigation formatting.
-- `src/services/codex-session-history-importer.ts` implements read-only scan/normalize/validate helpers in addition to existing explicit Codex import APIs.
-- `src/apps/cli/codex-import-runner.ts` implements the safe import command runner.
-- `src/apps/cli/index.ts` exposes the user-facing commands.