claude-memory-layer 1.0.26 → 1.0.28

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

@@ -93,10 +93,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 +104,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 +136,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 +347,7 @@ SECRET_TOKEN=abc123
 🔍 Search Results:
 
 #1 [mem:a7Bc3x] (score: 0.94)
-   "DuckDB를 사용하여 이벤트 소싱 패턴을..."
+   "SQLite/WAL을 사용하여 이벤트 소싱 패턴을..."
    📅 2026-01-30 | 🔗 Session abc123
 ```
 
@@ -349,10 +362,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 +384,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)
+```
 
-# 또는 수동 설정: ~/Library/Application Support/Claude/claude_desktop_config.json
+이 명령은 Claude Desktop config의 기존 값을 보존하면서 다음 MCP server entry를 추가/갱신합니다:
+
+```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 +508,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 +563,7 @@ Embeddings processed: 342
 ```
 사용자 프롬프트 입력
         ↓
-    EventStore에 저장 (DuckDB, append-only)
+    EventStore에 저장 (SQLite/WAL, append-only)
         ↓
     Outbox에 임베딩 요청 등록
         ↓
@@ -530,7 +631,7 @@ Embeddings processed: 342
         ▼                                      ▼
 ┌───────────────┐                    ┌───────────────┐
 │  EventStore   │ ──── Outbox ────▶ │  VectorStore  │
-│   (DuckDB)    │    (V2 Pattern)   │   (LanceDB)   │
+│ (SQLite/WAL)  │    (V2 Pattern)   │   (LanceDB)   │
 └───────────────┘                    └───────────────┘
 ```
 
@@ -583,12 +684,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 +730,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 +761,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." }
+  ]
+}