claude-memory-layer 1.0.27 → 1.0.29

package/.env.example

@@ -0,0 +1,7 @@
+# External Market Context API keys are read from environment variables only.
+# Copy values into your shell environment or an ignored local .env file if desired.
+# Do not commit real credentials.
+
+DART_API_KEY=
+FRED_API_KEY=
+FINNHUB_API_KEY=

package/AGENTS.md

@@ -3,6 +3,17 @@
 이 저장소는 **Claude Code용 메모리 플러그인 + CLI + 로컬 대시보드 서버**입니다.
 Codex(또는 다른 코딩 에이전트)가 작업할 때 아래 규칙을 우선으로 따르세요.
 
+## Project Memory Bootstrap
+
+작업 시작/재개 전에 Claude Memory Layer MCP 도구가 사용 가능하면 먼저 프로젝트 맥락을 가져오세요.
+
+- 트리거: `continue`, `next`, `이어서`, `다음 단계`, 버그 수정, PR/merge/검증, 이전 결정/작업 맥락이 중요한 요청
+- 우선 호출: `mem-context-pack` / Hermes 도구명 `mcp_claude_memory_layer_mem_context_pack`
+- 권장 인자: `query=<현재 요청 요약>`, `projectPath=<현재 저장소 루트>`, `topK=5`, `recentLimit=30`, `sessionLimit=5`
+- MCP 도구가 없으면 막히지 말고 기존 AGENTS.md 규칙대로 진행하세요.
+- 결과는 배경 맥락으로만 사용하고, secret/token/credential 또는 transcript DB path 같은 민감한 metadata는 출력하지 마세요.
+- live agent session id를 CML `sessionId`로 넘기지 마세요. source-session 필터가 명시된 경우에만 사용하세요.
+
 ## Quick Commands
 
 ```bash

package/README.md

@@ -16,37 +16,80 @@ Claude Memory Layer는 Claude Code에서 사용자와 AI 간의 모든 대화를
 
 ### 0) 최초 1회(머신 전체) 설치
 
+권장 설치 방식은 npm에 배포된 패키지를 **전역 설치**하는 것입니다. `install`은 Claude Code hook 파일 경로를 `~/.claude/settings.json`에 저장하므로, 일회성 `npx claude-memory-layer install`보다 전역 설치 또는 고정된 로컬 checkout을 쓰는 것이 안전합니다.
+
 ```bash
-cd ~/workspace/claude-memory-layer
+npm install -g claude-memory-layer@latest
+claude-memory-layer install
+claude-memory-layer status
+```
+
+로컬 개발 checkout에서 설치할 때:
+
+```bash
+git clone https://github.com/buzzni/claude-memory-layer.git
+cd claude-memory-layer
 npm install
 npm run build
 npx claude-memory-layer install
+npx claude-memory-layer status
 ```
 
 - `install`은 **한 번만** 하면 됩니다(Claude Code hooks 등록).
+- Linux x64 + CUDA 11 환경에서는 설치 중 optional embedding backend를 CPU-only ONNX Runtime으로 자동 복구합니다.
 - 이후 프로젝트별로 메모리 저장소가 자동 분리됩니다.
+- `install` / `uninstall`은 `~/.claude/settings.json`을 수정합니다.
+
+#### CUDA 11 / `onnxruntime-node` 설치 에러
+
+Linux x64 서버에 CUDA 11이 설치되어 있으면 `@huggingface/transformers`의 하위 의존성인 `onnxruntime-node`가 `nvcc --version`을 감지한 뒤 CUDA 11용 GPU 바이너리를 자동 설치하려고 합니다. 현재 해당 install script는 CUDA 11 자동 설치를 지원하지 않아 다음 오류로 `npm install`이 실패할 수 있습니다.
+
+```text
+Error: CUDA 11 binaries are not supported by this script yet.
+```
+
+Claude Memory Layer는 설치 시 Linux x64 + CUDA 11 환경을 감지하면 `@huggingface/transformers`를 optional dependency로 처리한 뒤 CPU-only ONNX Runtime 설정으로 자동 복구합니다. 그래서 일반적으로 사용자가 환경변수를 직접 지정할 필요는 없습니다.
+
+만약 구버전 패키지를 설치 중이거나 postinstall 복구가 실패하면 아래처럼 수동으로 CUDA 바이너리 다운로드만 건너뛰어 재설치할 수 있습니다.
+
+```bash
+# 실패한 전역 설치가 일부 남아 있으면 먼저 제거
+npm uninstall -g claude-memory-layer || true
+
+# 수동 fallback: CPU-only ONNX Runtime으로 재설치
+ONNXRUNTIME_NODE_INSTALL_CUDA=skip npm install -g claude-memory-layer@latest
+claude-memory-layer --version
+```
+
+로컬 checkout 개발 환경에서 구버전 의존성 설치가 같은 오류를 내면 아래처럼 수동 fallback을 사용할 수 있습니다.
+
+```bash
+ONNXRUNTIME_NODE_INSTALL_CUDA=skip npm install
+```
+
+`npm warn deprecated ...` 경고는 하위 의존성 경고이며 설치 실패 원인이 아닙니다.
 
 ### 1) 새 프로젝트에서 초기 메모리 생성
 
 ```bash
 cd /path/to/your-project
-npx claude-memory-layer import
+claude-memory-layer import
 ```
 
-- 현재 프로젝트의 기존 Claude 세션(`~/.claude/projects/...`)을 읽어와 메모리로 적재합니다.
+- 현재 프로젝트의 기존 Claude Code 세션(`~/.claude/projects/...`)을 읽어와 메모리로 적재합니다.
 - 벡터 임베딩까지 한 번에 처리됩니다.
 
 ### 2) 사용 중 확인
 
 ```bash
 # 프로젝트 메모리 검색
-npx claude-memory-layer search "인증 구조"
+claude-memory-layer search "인증 구조"
 
 # 통계 확인
-npx claude-memory-layer stats
+claude-memory-layer stats
 
 # 대시보드 실행
-npx claude-memory-layer dashboard
+claude-memory-layer dashboard --no-open
 ```
 
 ### 3) 다른 프로젝트에도 동일하게 적용?
@@ -55,8 +98,8 @@ npx claude-memory-layer dashboard
 
 ```bash
 cd /path/to/another-project
-npx claude-memory-layer import
-npx claude-memory-layer search "배포 이슈"
+claude-memory-layer import
+claude-memory-layer search "배포 이슈"
 ```
 
 프로젝트마다 내부적으로 별도 저장소(`~/.claude-code/memory/projects/<hash>`)를 사용하므로,
@@ -66,6 +109,7 @@ npx claude-memory-layer search "배포 이슈"
 
 - 특정 프로젝트를 명시하고 싶으면 대부분 명령에 `--project <path>` 사용 가능
 - 대규모 리임포트가 필요하면 `import --force` 사용
+- 최근 일부만 가져오고 싶으면 `--session-limit <n>` 또는 `--limit <n>` 사용
 - 백그라운드 worker가 못 처리한 임베딩은 `process`로 수동 처리
 - 상태 점검:
   - `GET /health` (서버 헬스)
@@ -79,6 +123,144 @@ npx claude-memory-layer search "배포 이슈"
 
 ---
 
+## 다른 서버 초기 세팅 & 이전 대화 ingest
+
+새 서버에서 Claude Memory Layer를 설치하고 기존 Claude Code/Codex/Hermes 대화 기록을 처음 적재할 때는 아래 체크리스트를 따르세요.
+
+### 1) 새 서버 준비
+
+```bash
+node --version   # Node.js >= 18 필수
+npm --version
+npm install -g claude-memory-layer@latest
+claude-memory-layer install
+claude-memory-layer status
+```
+
+> `claude-memory-layer install`은 Claude Code hooks를 등록합니다. 이미 Claude Code가 실행 중이면 재시작해야 hook이 반영됩니다.
+
+### 2) 이전 서버의 원본 대화 기록 가져오기
+
+가장 안전한 방식은 **원본 대화 기록을 새 서버로 복사한 뒤 새 서버에서 다시 import**하는 것입니다. 필요한 것만 선택해서 복사하세요. 이 디렉토리/DB에는 민감한 대화와 경로가 포함될 수 있으므로 공개 저장소에 커밋하거나 공유하지 말고, SSH/사설망 등 신뢰할 수 있는 경로로만 복사하세요.
+
+```bash
+# Claude Code 원본 세션(JSONL)
+mkdir -p ~/.claude/projects
+rsync -a OLD_HOST:~/.claude/projects/ ~/.claude/projects/
+
+# Codex CLI 원본 세션(JSONL) - Codex 기록도 가져올 때만
+mkdir -p ~/.codex/sessions
+rsync -a OLD_HOST:~/.codex/sessions/ ~/.codex/sessions/
+
+# Hermes Agent SessionDB - Hermes 기록도 가져올 때만
+# 권장: OLD_HOST에서 Hermes/gateway/agent 프로세스를 먼저 멈춘 뒤 SQLite sidecar까지 함께 복사
+mkdir -p ~/.hermes
+rsync -a OLD_HOST:'~/.hermes/state.db*' ~/.hermes/
+```
+
+Hermes를 멈출 수 없는 운영 서버라면, `state.db` 파일을 직접 복사하는 대신 OLD_HOST에서 SQLite `.backup`으로 일관된 스냅샷을 만든 뒤 가져오세요.
+
+```bash
+ssh OLD_HOST 'sqlite3 ~/.hermes/state.db ".backup /tmp/hermes-state.db.backup"'
+mkdir -p ~/.hermes
+rsync -a OLD_HOST:/tmp/hermes-state.db.backup ~/.hermes/state.db
+```
+
+이미 처리된 CML 저장소를 그대로 옮기고 싶다면, 이전/새 서버의 관련 agent, dashboard, semantic daemon/worker 등 모든 CML writer를 멈춘 뒤 아래처럼 복사할 수도 있습니다. 단, 재현성과 모델/버전 migration을 위해서는 위의 원본 기록 re-ingest 방식을 우선 권장합니다.
+
+```bash
+mkdir -p ~/.claude-code
+rsync -a OLD_HOST:~/.claude-code/memory/ ~/.claude-code/memory/
+```
+
+### 3) 프로젝트별로 read-only 검증 후 import
+
+프로젝트 메모리는 프로젝트 경로 기준으로 분리됩니다. 새 서버의 실제 repo 경로를 `PROJECT`에 넣고, 필요한 importer만 실행하세요.
+
+중요: Codex/Hermes/Claude Code 원본 세션의 project filter는 **대화가 생성될 당시의 절대 경로**를 기준으로 매칭합니다. 새 서버에서도 repo 절대 경로가 이전 서버와 같으면 아래 project import를 그대로 쓰면 됩니다.
+
+```bash
+export PROJECT=/path/to/your-project
+cd "$PROJECT"
+
+# Claude Code 기록: import 가능한 세션 확인 후 프로젝트 메모리로 적재
+claude-memory-layer list --project "$PROJECT"
+claude-memory-layer import --project "$PROJECT" --verbose
+
+# Codex 기록: 먼저 읽기 전용 리포트로 확인한 뒤 명시적으로 import
+claude-memory-layer codex validate --project "$PROJECT" --format markdown
+claude-memory-layer codex import --project "$PROJECT" --verbose
+
+# Hermes 기록: 먼저 읽기 전용 리포트로 확인한 뒤 명시적으로 import
+claude-memory-layer hermes validate --project "$PROJECT" --format markdown
+claude-memory-layer hermes import --project "$PROJECT" --verbose
+
+# pending embedding이 남아 있으면 수동 처리
+claude-memory-layer process --project "$PROJECT"
+```
+
+이전 서버와 새 서버의 repo 절대 경로가 다르면, `OLD_PROJECT`로 원본 세션을 찾고 특정 session 파일/id를 새 프로젝트 저장소(`NEW_PROJECT`)로 가져오세요.
+
+```bash
+export OLD_PROJECT=/old/server/path/to/your-project
+export NEW_PROJECT=/path/to/your-project
+cd "$NEW_PROJECT"
+
+# Claude Code: list 출력의 JSONL session file path를 확인해서 사용
+claude-memory-layer list --project "$OLD_PROJECT"
+claude-memory-layer import --project "$NEW_PROJECT" --session /path/to/claude-session.jsonl --verbose
+
+# Codex: validate 결과에서 session JSONL 파일을 확인한 뒤 import
+claude-memory-layer codex validate --project "$OLD_PROJECT" --format markdown
+claude-memory-layer codex import --project "$NEW_PROJECT" --session /path/to/codex-session.jsonl --verbose
+
+# Hermes: validate 결과에서 Hermes session id를 확인한 뒤 import
+claude-memory-layer hermes validate --project "$OLD_PROJECT" --format markdown
+claude-memory-layer hermes import --project "$NEW_PROJECT" --session 20260505_010203_abcd1234 --verbose
+
+claude-memory-layer process --project "$NEW_PROJECT"
+```
+
+주의:
+
+- `claude-memory-layer import --all`은 모든 Claude Code 세션을 전역 저장소로 가져옵니다. 프로젝트별 컨텍스트 품질이 중요하면 각 repo에서 `--project <path>` 방식으로 반복하는 것을 권장합니다.
+- `codex import --all`, `hermes import --all`도 의도적으로 전역 메모리를 만들 때만 사용하세요.
+- import/validate/list 결과에는 대화 내용 일부나 로컬 경로가 포함될 수 있습니다. 외부 공유 전에는 민감정보와 경로를 제거하고, Codex validate 리포트는 필요하면 `--anonymize-projects`를 함께 사용하세요.
+- import는 콘텐츠 해시 기반으로 중복을 건너뛰므로 여러 번 실행해도 같은 내용이 중복 저장되지 않습니다. 단, `--force`는 기존 import 이벤트를 지우고 재적재하므로 신중히 사용하세요.
+
+### 4) 검증
+
+```bash
+export VERIFY_PROJECT=/path/to/your-project  # 위에서 쓴 PROJECT 또는 NEW_PROJECT
+claude-memory-layer stats --project "$VERIFY_PROJECT"
+claude-memory-layer search "최근에 하던 작업" --project "$VERIFY_PROJECT" --top-k 5
+claude-memory-layer dashboard --no-open --port 37777
+# 다른 터미널에서: curl http://localhost:37777/api/health
+```
+
+### 5) MCP/다른 agent에 연결
+
+Claude Desktop은 CLI로 자동 등록할 수 있습니다. GUI 앱에서 shell `PATH`가 다를 수 있으면 stdio binary의 절대 경로를 command로 넣는 방식이 더 견고합니다.
+
+```bash
+claude-memory-layer mcp install --command "$(command -v claude-memory-layer-mcp)"
+# Claude Desktop 재시작
+```
+
+Codex/Hermes 등 MCP client에도 전역 설치된 stdio binary를 등록하면 됩니다.
+
+```bash
+# Codex 예시
+codex mcp add claude-memory-layer -- claude-memory-layer-mcp
+
+# Hermes 예시
+hermes mcp add claude-memory-layer --command claude-memory-layer-mcp
+```
+
+MCP client가 환경에 따라 PATH를 못 찾으면 `command -v claude-memory-layer-mcp`로 절대 경로를 확인해서 command에 넣으세요.
+
+---
+
 ## Features
 
 ### Core Features
@@ -93,10 +275,10 @@ npx claude-memory-layer search "배포 이슈"
 ### Advanced Features
 
 - **Citations System**: 메모리 출처 추적 (`[mem:abc123]` 형식)으로 검색 결과의 원본 확인 가능
-- **Endless Mode**: 세션 경계 없는 연속적 메모리 스트림, Biomimetic Memory Architecture 기반
+- **Endless Mode**: 세션 경계 없는 연속적 메모리 스트림, Biomimetic Memory Architecture 기반 *(experimental extension)*
 - **Entity-Edge Model**: entries/entities/edges 3-layer 모델로 데이터 관계 명시적 모델링
 - **Evidence Aligner V2**: Quote 기반 3단계 정렬 (exact → normalized → fuzzy)
-- **MCP Desktop Integration**: Claude Desktop용 MCP 서버로 CLI와 동일한 메모리 공유
+- **MCP Desktop Integration**: Claude Desktop용 MCP 서버로 CLI와 동일한 메모리 공유 *(stdio server bin: `claude-memory-layer-mcp`)*
 - **PostToolUse Hook**: 도구 실행 결과 (Read, Write, Bash 등) 캡처 및 저장
 - **Private Tags**: `<private>` 태그로 민감 정보를 명시적으로 제외
 - **Progressive Disclosure**: 3-Layer 검색 (인덱스 → 타임라인 → 상세)으로 토큰 효율화
@@ -104,9 +286,21 @@ npx claude-memory-layer search "배포 이슈"
 - **Append-only Markdown Mirror**: 저장 이벤트를 `memory/<namespace>/<category...>/YYYY-MM-DD.md`에도 동기 append (기본값: `namespace=default`, `category=uncategorized`, 경로 세그먼트 sanitize)
   - `memory/_index.md` 인덱스를 자동 갱신
 - **Task Entity System**: Task를 Entity로 승격하여 세션 간 상태 추적
-- **Vector Outbox V2**: Transactional Outbox 패턴으로 DuckDB-LanceDB 정합성 보장
+- **Vector Outbox V2**: Transactional Outbox 패턴으로 SQLite-LanceDB 정합성 보장
 - **Web Viewer UI**: localhost:37777 대시보드로 실시간 메모리 모니터링
 
+### 현재 feature status
+
+| 영역 | 상태 | 비고 |
+|------|------|------|
+| Claude Code hooks / CLI / Dashboard | Stable | `install`, `search`, `import`, `stats`, `dashboard` 중심 |
+| SQLite event store / project registry | Stable | canonical source of truth |
+| LanceDB vector index / Embedder | Stable accelerator | `src/extensions/vector/embedder.ts`; VectorStore/VectorWorker는 아직 core compatibility path 유지 |
+| Progressive disclosure search/API/CLI/dashboard | Implemented | `search --disclosure`, `expand`, `source` mental model |
+| Shared memory / Endless mode | Experimental extension | 구현은 `src/extensions/shared-memory`, `src/extensions/endless-memory` 아래에 있고 기존 path는 shim 유지 |
+| MCP Desktop integration | Implemented | 구현은 `src/extensions/mcp`; package bin은 `claude-memory-layer-mcp`; `claude-memory-layer mcp install`로 Claude Desktop config 자동 등록 |
+| Mongo sync / Entity graph / Task entity | Experimental | 고급/운영 옵션으로 취급 |
+
 ## 설치 방법
 
 ### 1. 의존성 설치
@@ -124,13 +318,14 @@ npm run build
 
 ### 3. Claude Code에 플러그인 등록
 
-빌드된 플러그인을 Claude Code 설정에 추가합니다:
+Claude Code hook 설정은 CLI가 등록합니다:
 
 ```bash
-# Claude Code 설정 디렉토리에 플러그인 복사
-cp -r dist/.claude-plugin ~/.claude/plugins/claude-memory-layer/
+npx claude-memory-layer install
 ```
 
+> 주의: `install` / `uninstall`은 `~/.claude/settings.json`을 수정합니다. 자동 테스트나 임의 실행 대신, 실제 사용자가 설치/해제를 원할 때만 실행하세요.
+
 ## 사용 방법
 
 ### 자동 동작 (Hooks)
@@ -334,7 +529,7 @@ SECRET_TOKEN=abc123
 🔍 Search Results:
 
 #1 [mem:a7Bc3x] (score: 0.94)
-   "DuckDB를 사용하여 이벤트 소싱 패턴을..."
+   "SQLite/WAL을 사용하여 이벤트 소싱 패턴을..."
    📅 2026-01-30 | 🔗 Session abc123
 ```
 
@@ -349,10 +544,10 @@ claude-memory-layer show mem:a7Bc3x
 
 ```bash
 # Endless Mode 활성화
-claude-memory-layer config set mode endless
+claude-memory-layer endless enable
 
 # 상태 확인
-claude-memory-layer status
+claude-memory-layer endless status
 
 # 출력 예시:
 # Mode: Endless
@@ -371,31 +566,75 @@ claude-memory-layer status
 
 ## MCP Desktop Integration
 
-Claude Desktop에서 메모리 검색을 사용하려면:
+> 현재 상태: MCP server implementation은 `src/extensions/mcp/`로 이동되어 있고,
+> `src/mcp/*`는 compatibility shim입니다. package bin으로
+> `claude-memory-layer-mcp`가 제공됩니다.
+
+Claude Desktop 설정은 CLI로 자동 등록할 수 있습니다:
 
 ```bash
-# MCP 서버 설치
 claude-memory-layer mcp install
+# Config: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
+```
+
+이 명령은 Claude Desktop config의 기존 값을 보존하면서 다음 MCP server entry를 추가/갱신합니다:
 
-# 또는 수동 설정: ~/Library/Application Support/Claude/claude_desktop_config.json
+```json
 {
   "mcpServers": {
     "claude-memory-layer": {
-      "command": "npx",
-      "args": ["claude-memory-layer-mcp"]
+      "command": "claude-memory-layer-mcp",
+      "args": []
     }
   }
 }
 ```
 
+옵션:
+
+```bash
+claude-memory-layer mcp install --dry-run
+claude-memory-layer mcp install --config-path /path/to/claude_desktop_config.json
+claude-memory-layer mcp install --server-name claude-memory-layer --command claude-memory-layer-mcp
+```
+
+설정 후 Claude Desktop을 재시작하면 MCP 서버가 로드됩니다. Codex/Hermes처럼 MCP client가 있는 다른 agent에는 로컬 checkout의 built server를 직접 등록할 수 있습니다:
+
+```bash
+# Codex
+codex mcp add claude-memory-layer -- node /path/to/claude-memory-layer/dist/mcp/index.js
+
+# Hermes
+hermes mcp add claude-memory-layer --command node --args /path/to/claude-memory-layer/dist/mcp/index.js
+```
+
+로컬 checkout에서 서버만 바로 테스트하려면 `npm run build` 후 다음처럼 직접 실행할 수도 있습니다:
+
+```bash
+node dist/mcp/index.js
+```
+
 ### 제공되는 MCP 도구
 
 | 도구 | 설명 |
 |------|------|
-| `mem-search` | 메모리 검색 |
-| `mem-timeline` | 타임라인 조회 |
-| `mem-details` | 상세 정보 조회 |
-| `mem-stats` | 통계 조회 |
+| `mem-search` | 메모리 검색 (`projectPath`를 주면 프로젝트별 저장소 검색) |
+| `mem-timeline` | 특정 memory IDs 주변 chronological context 조회 (`projectPath` 지원) |
+| `mem-details` | 상세 정보 조회 (`projectPath` 지원) |
+| `mem-stats` | 통계 조회 (`projectPath` 지원) |
+| `mem-context-pack` | 작업 시작용 compact context pack. query 관련 memory + 최근 project timeline + follow-up refs를 한 번에 반환 |
+| `mem-project-timeline` | 최근 project memory를 session/source/event-count/safe-preview 기준으로 요약 |
+| `mem-source-ref` | `mem:<citation>` 또는 `event:<id>`를 privacy-safe source reference와 redacted preview로 해석 |
+
+예시 workflow:
+
+```text
+1. 새 작업 시작: mem-context-pack(projectPath, query)
+2. 최근 흐름 확인: mem-project-timeline(projectPath)
+3. 근거가 더 필요할 때: mem-source-ref(projectPath, ids=["mem:abc123"])
+```
+
+이 workflow는 Hermes/Codex/Claude Code가 같은 project-scoped memory backend를 공유할 때 특히 유용합니다. `mem-source-ref`는 raw transcript를 그대로 덤프하지 않고 allowlisted metadata와 privacy-filtered preview만 반환합니다.
 
 ## Web Viewer
 
@@ -451,6 +690,50 @@ Skipped duplicates: 0
 Embeddings processed: 342
 ```
 
+### Codex 세션 임포트
+
+Codex CLI 기록(`~/.codex/sessions`)은 기본적으로 read-only validate/replay로 먼저 확인하고, 명시적 import 명령으로만 메모리에 저장합니다:
+
+```bash
+# 읽기 전용 검증/리포트
+npx claude-memory-layer codex validate --project /path/to/project --format markdown
+
+# 현재 프로젝트 Codex 세션을 프로젝트별 메모리로 import
+cd /path/to/project
+npx claude-memory-layer codex import
+
+# 특정 세션만 import
+npx claude-memory-layer codex import --project /path/to/project --session /path/to/session.jsonl
+
+# 모든 Codex 세션 import (전역 저장소 사용; 필요할 때만)
+npx claude-memory-layer codex import --all --verbose
+```
+
+옵션: `--sessions-dir`, `--limit`, `--force`, `--no-process-embeddings`.
+
+### Hermes 세션 임포트
+
+Hermes Agent 기록(`~/.hermes/state.db`)도 원본 DB를 read-only validate/replay로 먼저 확인하고, 명시적 import 명령으로만 프로젝트별 메모리에 저장합니다. 기본 전략은 live sync가 아니라 **SessionDB → CML explicit derived import**입니다:
+
+```bash
+# 읽기 전용 검증/리포트
+npx claude-memory-layer hermes validate --project /path/to/project --format markdown
+
+# 현재 프로젝트 Hermes 세션을 프로젝트별 메모리로 import
+cd /path/to/project
+npx claude-memory-layer hermes import
+
+# 특정 Hermes session id만 import
+npx claude-memory-layer hermes import --project /path/to/project --session 20260505_010203_abcd1234
+
+# 모든 Hermes 세션 import (전역 저장소 사용; 필요할 때만)
+npx claude-memory-layer hermes import --all --verbose
+```
+
+옵션: `--state-db`, `--limit`, `--force`, `--no-process-embeddings`.
+
+Hermes import는 user/assistant turn만 저장하고 tool/system 메시지는 건너뜁니다. 검증 리포트에는 aggregate count만 포함되며 transcript 본문은 포함하지 않습니다.
+
 ### 중복 처리
 
 임포트는 콘텐츠 해시 기반으로 중복을 자동 감지합니다. 여러 번 실행해도 같은 내용이 중복 저장되지 않습니다.
@@ -462,7 +745,7 @@ Embeddings processed: 342
 ```
 사용자 프롬프트 입력
         ↓
-    EventStore에 저장 (DuckDB, append-only)
+    EventStore에 저장 (SQLite/WAL, append-only)
         ↓
     Outbox에 임베딩 요청 등록
         ↓
@@ -530,7 +813,7 @@ Embeddings processed: 342
         ▼                                      ▼
 ┌───────────────┐                    ┌───────────────┐
 │  EventStore   │ ──── Outbox ────▶ │  VectorStore  │
-│   (DuckDB)    │    (V2 Pattern)   │   (LanceDB)   │
+│ (SQLite/WAL)  │    (V2 Pattern)   │   (LanceDB)   │
 └───────────────┘                    └───────────────┘
 ```
 
@@ -583,12 +866,12 @@ Layer 1: Search Index (~50-100 tokens/result)
 
 ## AXIOMMIND 7 원칙
 
-1. **Single Source of Truth**: DuckDB EventStore가 유일한 진실의 원천
+1. **Single Source of Truth**: SQLite/WAL EventStore가 유일한 진실의 원천
 2. **Append-Only**: 이벤트는 수정/삭제 없이 추가만
 3. **Idempotency**: dedupe_key로 중복 이벤트 감지
 4. **Evidence Alignment**: 주장이 실제 소스에 기반했는지 검증
 5. **Entity-Based Tasks**: canonical_key로 일관된 엔티티 식별
-6. **Vector Store Consistency**: DuckDB → LanceDB 단방향 흐름
+6. **Vector Store Consistency**: SQLite outbox → LanceDB 단방향 흐름
 7. **Standard JSON**: 모든 데이터는 이식 가능한 JSON 형식
 
 ## 저장 위치
@@ -629,15 +912,15 @@ npm run dev
 
 ## 기술 스택
 
-- **DuckDB**: 이벤트 저장소 (append-only SQL)
-- **LanceDB**: 벡터 저장소 (고성능 벡터 검색)
-- **@xenova/transformers**: 로컬 임베딩 생성
+- **SQLite / WAL**: 이벤트 저장소 (canonical append/read model)
+- **LanceDB**: 벡터 저장소 (derived acceleration index)
+- **@huggingface/transformers**: 로컬 임베딩 생성 (lazy import; Embedder는 `src/extensions/vector/`)
 - **Zod**: 런타임 타입 검증
 - **Commander**: CLI 인터페이스
 - **TypeScript**: 타입 안전한 코드
-- **Bun**: HTTP 서버 (Web Viewer)
+- **Node.js + Hono**: HTTP 서버 / Web Viewer
 - **Hono**: 경량 라우터
-- **MCP SDK**: Claude Desktop 통합
+- **MCP SDK**: Claude Desktop 통합 (`claude-memory-layer-mcp` stdio server)
 
 ## Specification Documents
 
@@ -660,30 +943,72 @@ npm run dev
 ## Roadmap
 
 ### Phase 1: Core (완료)
-- [x] Event Store (DuckDB)
+- [x] Event Store (SQLite/WAL)
 - [x] Vector Store (LanceDB)
 - [x] Memory Graduation (L0→L4)
 - [x] Evidence Alignment
 - [x] History Import
 
 ### Phase 2: Advanced Features (진행 중)
-- [ ] Citations System
-- [ ] Endless Mode
-- [ ] Entity-Edge Model
-- [ ] Evidence Aligner V2
-- [ ] Private Tags
+- [x] Citations System
+- [x] Endless Mode service boundary *(experimental extension)*
+- [ ] Entity-Edge Model productization
+- [x] Evidence Aligner V2
+- [x] Private Tags
 
 ### Phase 3: Integration
-- [ ] MCP Desktop Integration
-- [ ] Web Viewer UI
-- [ ] PostToolUse Hook
-- [ ] Progressive Disclosure
-
-### Phase 4: Optimization
-- [ ] Vector Outbox V2
-- [ ] Task Entity System
+- [x] MCP Desktop Integration *(stdio server bin exists; auto install command pending)*
+- [x] Web Viewer UI
+- [x] PostToolUse Hook
+- [x] Progressive Disclosure
+
+### Phase 4: Optimization / Extension Isolation
+- [x] Vector Outbox V2
+- [x] Embedder extension boundary
+- [ ] VectorStore / VectorWorker extension boundary
+- [ ] Task Entity System productization
 - [ ] Performance Tuning
 
 ## License
 
 MIT
+
+## External Market Context (DART/FRED/Finnhub)
+
+`claude-memory-layer market-context` fetches read-only external company and market data from environment-configured providers and returns a structured `MarketContextSnapshot` plus a Markdown analysis report.
+
+Example:
+
+```bash
+export DART_API_KEY=...      # env-only; never commit real keys
+export FRED_API_KEY=...
+export FINNHUB_API_KEY=...
+claude-memory-layer market-context \
+  --company 삼성전자 \
+  --dart-corp-code 00126380 \
+  --symbol 005930.KS \
+  --providers dart,fred,finnhub \
+  --fred-series FEDFUNDS,CPIAUCSL \
+  --json
+```
+
+Security and behavior:
+
+- API keys are read only from `DART_API_KEY`, `FRED_API_KEY`, and `FINNHUB_API_KEY`.
+- `.env*` files are ignored; `.env.example` is placeholder-only.
+- Missing provider keys produce skipped-provider statuses rather than hard failures.
+- Provider requests use bounded timeouts; large FRED series lists are capped to the first 10 unique series.
+- Empty Finnhub profile responses are treated as skipped-provider/no-data results, not profile evidence.
+- Provider errors and rendered reports redact credential-bearing query params such as `crtfc_key`, `api_key`, and `token`.
+- The MCP `external-market-context` tool is read-only and does not initialize or mutate memory storage.
+- `--no-snapshot` / MCP `includeSnapshot: false` disables both `analysis.marketSnapshot` and the DART company snapshot.
+
+`MarketContextSnapshot` includes:
+
+- `schemaVersion: market-context-snapshot.v1`
+- `subject`: company, DART corpCode, ticker symbol
+- `coverage`: DART/FRED/Finnhub provider status and counts
+- `bullCases`, `bearCases`, `risks`, `catalysts`: deterministic evidence-backed insights
+- `watchlist` and `followUpQuestions`
+
+The Markdown report includes a `### MarketContextSnapshot` section with **Bull case**, **Bear case**, **Risks**, and **Catalysts**. DART analysis uses all fetched filings; only the rendered filing list is truncated. If `dartCorpCode` is omitted, company-name fallback is marked low-confidence, so exact DART corp codes are recommended for customer-facing analysis.

package/benchmarks/replay/anonymized-real-sessions.json

@@ -0,0 +1,48 @@
+{
+  "name": "anonymized-real-session-replay-v1",
+  "description": "Anonymized real-session-style retrieval replay fixture for Precision@k / Recall@k / nDCG@k / no-match checks.",
+  "ks": [1, 3, 5],
+  "queries": [
+    {
+      "queryId": "q-cli-fast",
+      "query": "fast search should avoid embedding startup",
+      "expectation": "match",
+      "expectedIds": ["m-cli-fast", "m-runtime-light"],
+      "expectedRelevance": { "m-cli-fast": 3, "m-runtime-light": 2 },
+      "knownAnswer": "CLI search --strategy fast uses keyword retrieval and should not start embedding model initialization."
+    },
+    {
+      "queryId": "q-hook-policy",
+      "query": "hook should not inject weak keyword rescue",
+      "expectation": "match",
+      "expectedIds": ["m-hook-policy", "m-hook-threshold"],
+      "expectedRelevance": { "m-hook-policy": 3, "m-hook-threshold": 2 },
+      "knownAnswer": "Claude hook prompt injection has a separate conservative policy for high-confidence memories."
+    },
+    {
+      "queryId": "q-replay-bench",
+      "query": "precision recall replay benchmark output",
+      "expectation": "match",
+      "expectedIds": ["m-benchmark", "m-metrics"],
+      "expectedRelevance": { "m-benchmark": 3, "m-metrics": 2 },
+      "knownAnswer": "Replay benchmark reports Precision@k and Recall@k over anonymized session queries."
+    },
+    {
+      "queryId": "q-no-match-command-artifact",
+      "query": "local-command-stdout command-name opus",
+      "expectation": "no_match",
+      "expectedIds": [],
+      "expectedRelevance": {},
+      "forbiddenIds": ["m-cli-fast", "m-hook-policy", "m-benchmark"]
+    }
+  ],
+  "memories": [
+    { "id": "m-cli-fast", "content": "CLI search --strategy fast uses keyword retrieval and should not start embedding model initialization." },
+    { "id": "m-runtime-light", "content": "Lightweight read paths initialize SQLite event-store only and avoid vector/embedder workers." },
+    { "id": "m-hook-policy", "content": "Claude hook prompt injection has a separate conservative policy for high-confidence memories." },
+    { "id": "m-hook-threshold", "content": "Low-confidence keyword fallback can remain searchable but should not be injected into prompts." },
+    { "id": "m-benchmark", "content": "Replay benchmark reports Precision@k and Recall@k over anonymized session queries." },
+    { "id": "m-metrics", "content": "Metric summaries average per-query precision and recall for k values one three and five." },
+    { "id": "m-noise", "content": "Unrelated dashboard styling note for visual spacing." }
+  ]
+}