接入你的智能体
發布者自己的指令。不是 PlugMCP 端點。
用我們的金鑰與日誌託管一份副本。
npx -y [email protected]Claude Code 沒有本機指令的安裝連結。複製下方指令並在終端機中執行。
claude mcp add claude-memory-layer -- npx -y claude-memory-layer@2.5.8在終端機中執行。
{ "mcpServers": { "claude-memory-layer": { "command": "npx", "args": [ "-y", "[email protected]" ] } }}claude_desktop_config.json
遠端 URL 還是本機指令？ 兩種安裝方式的差異
來自發布者
Claude Code, Codex, Hermes, MCP 클라이언트가 함께 쓰는 프로젝트 스코프 메모리 레이어입니다. 대화/세션 기록을 SQLite 이벤트 저장소와 LanceDB 벡터 인덱스로 관리하고, 작업 시작 시 필요한 기억·타임라인·액션 프런티어를 privacy-safe 컨텍스트로 제공합니다.
Claude Memory Layer는 AI 에이전트의 대화와 작업 이벤트를 프로젝트별로 저장하고, 새로운 작업을 시작할 때 관련 기억을 자동 검색해 컨텍스트로 제공합니다. 최신 npm 패키지는 단순 Claude Code hook을 넘어 다음 용도로 사용할 수 있습니다:
Project-scoped memory layer for Claude Code, Codex, Hermes, MCP, and dashboards
projectPath 기반 MCP/CLI 조회mem-context-pack, mem-project-timeline, mem-source-ref, mem-import-latest로 Hermes/Codex/Claude Desktop이 같은 프로젝트 기억을 안전하게 조회합니다.session_search, CML context-pack, read-only Hermes provider, Headroom reference stance는 docs/HERMES_CML_HEADROOM_OPERATING_MODEL.md에 정리되어 있습니다.@huggingface/transformers는 보안 버전의 sharp를 고정한 격리 backend로 설치하며, CUDA 11 환경에서는 CPU-only ONNX Runtime으로 자동 복구합니다.source_file 엔티티 + touched_in 그래프 + session-file 검색 레인), Letta식 코어 메모리 블록(mem-core-block-get/update, SessionStart 상시 주입), Mem0식 사실 조정(mem-entity-supersede), Zep/Graphiti식 bitemporal 엣지 히스토리(mem-graph-query의 asOf/knownAt)를 제공합니다.~/.claude-code/memory/operations.json 파일 하나로 켤 수 있습니다. 아래 선택 기능 활성화 참고.아래 순서대로 하면 됩니다.
Runtime requirement: Claude Memory Layer 2.0.0부터 Node.js 20.19 이상이 필요합니다. Hono 정적 파일 서버와 로컬 embedding 이미지 backend의 보안 수정 버전을 사용하기 위한 최소 버전입니다.
권장 설치 방식은 npm에 배포된 패키지를 전역 설치하는 것입니다. install은 Claude Code hook 파일 경로를 ~/.claude/settings.json에 저장하므로, 일회성 npx claude-memory-layer install보다 전역 설치 또는 고정된 로컬 checkout을 쓰는 것이 안전합니다.
npm install -g claude-memory-layer@latest
# 기본: Claude Code 훅만 설치
claude-memory-layer install
# 또는: 훅과 주기 maintenance를 한 번에 설치
claude-memory-layer install --with-maintenance
claude-memory-layer status
# 설치 후 뭔가 이상하면 환경 진단 (Node 버전, embedding backend, PATH 중복 설치, 훅, 스토어 쓰기 권한)
claude-memory-layer doctor
# Codex에서도 자동 컨텍스트 적재/불러오기를 사용할 때
claude-memory-layer codex hooks install
claude-memory-layer codex hooks status
로컬 개발 checkout에서 설치할 때:
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
npx claude-memory-layer doctor
install은 한 번만 하면 됩니다(Claude Code hooks 등록).npm install만으로는 백그라운드 서비스를 등록하지 않습니다. maintenance install 또는 install --with-maintenance를 사용자가 명시적으로 실행해야 합니다.codex hooks install은 ~/.codex/hooks.json에 SessionStart/UserPromptSubmit/SessionEnd 훅을 병합합니다. Codex를 재시작한 뒤 /hooks에서 새 훅 정의를 검토하고 신뢰해야 실행됩니다.sharp 보안 버전을 강제하고, CUDA 11 환경에서는 onnxruntime-node를 CPU-only로 설치합니다.install / uninstall은 ~/.claude/settings.json을, codex hooks install / uninstall은 ~/.codex/hooks.json을 수정합니다. maintenance install / uninstall은 사용자 계정의 launchd/systemd 정의만 변경합니다. 기존의 다른 훅과 서비스는 보존합니다.프로젝트별 pending embedding/vector outbox와 5분 이상 멈춘 processing 작업을 주기적으로 처리하려면 최초 1회 활성화합니다.
# macOS: ~/Library/LaunchAgents에 사용자 LaunchAgent 등록
# Linux: ~/.config/systemd/user에 systemd user timer 등록(sudo 불필요)
claude-memory-layer maintenance install
# 기본 5분 대신 15분 주기
claude-memory-layer maintenance install --interval 900
claude-memory-layer maintenance status
claude-memory-layer maintenance run --json
claude-memory-layer maintenance run --no-compaction
# 기본 5 GiB보다 넉넉한 여유 공간을 요구할 때
claude-memory-layer maintenance run --min-free-gb 10
# 스케줄러 정의만 제거하며 메모리 데이터는 보존
claude-memory-layer maintenance uninstall
각 실행은 최근 저장소부터 순차적으로 확인하고 프로젝트별 worker lock을 사용합니다. 기본적으로 저장소당 최대 4 processing round(각 vector schema당 최대 한 batch)를 처리해 장시간 자원 독점을 피합니다. pending, retry 가능한 failed, 5분 이상 멈춘 processing 작업만 자동 복구하며 재시도 한도를 넘은 quarantined 작업은 무한 반복하지 않고 상태에 남깁니다.
maintenance는 메모리 루트가 있는 파일시스템의 여유 공간이 기본 5 GiB 미만이면 쓰기 작업을 blocked로 기록하고 큐 현황만 보고합니다. 기준은 maintenance run --min-free-gb <GiB>로 조정할 수 있으며, 0은 이 보호 장치를 명시적으로 끕니다. 예약 실행도 같은 기본값을 사용합니다.
systemd user session이 없는 최소 Linux, 컨테이너, 일부 WSL 환경에서는 스케줄러 설치 대신 claude-memory-layer maintenance run을 기존 cron/작업 스케줄러에서 호출할 수 있습니다.
onnxruntime-node 설치 에러Linux x64 서버에 CUDA 11이 설치되어 있으면 @huggingface/transformers의 하위 의존성인 onnxruntime-node가 nvcc --version을 감지한 뒤 CUDA 11용 GPU 바이너리를 자동 설치하려고 합니다. 현재 해당 install script는 CUDA 11 자동 설치를 지원하지 않아 다음 오류로 npm install이 실패할 수 있습니다.
Error: CUDA 11 binaries are not supported by this script yet.
Claude Memory Layer는 로컬 semantic/vector embedding에 필요한 @huggingface/transformers를 런타임 필수 backend로 취급합니다. 설치 중 postinstall repair가 이를 격리된 관리 디렉터리에 설치하면서 ONNXRUNTIME_NODE_INSTALL_CUDA=skip으로 CPU-only ONNX Runtime과 보안 수정된 sharp를 함께 고정합니다. npm 로그의 최종 exit code가 0이고 claude-memory-layer --version이 동작하면 정상입니다. 최신 버전에서는 일반적으로 아래 명령이 그대로 동작해야 합니다.
npm install -g claude-memory-layer@latest
claude-memory-layer --version
만약 npm 버전/환경 차이로 같은 오류가 계속 나면 아래처럼 CUDA 바이너리 다운로드를 명시적으로 건너뛰어 재설치하세요.
# 실패한 전역 설치가 일부 남아 있으면 먼저 제거
npm uninstall -g claude-memory-layer || true
# CPU-only ONNX Runtime으로 재설치
ONNXRUNTIME_NODE_INSTALL_CUDA=skip npm install -g claude-memory-layer@latest
claude-memory-layer --version
로컬 checkout 개발 환경에서 같은 오류가 나면 아래처럼 설치합니다.
ONNXRUNTIME_NODE_INSTALL_CUDA=skip npm install
이미 설치된 패키지 디렉터리에서 backend만 손상/누락된 경우에는 해당 패키지 디렉터리에서 아래 복구 스크립트를 실행할 수 있습니다.
ONNXRUNTIME_NODE_INSTALL_CUDA=skip node scripts/postinstall-embedding-backend.cjs
npm warn deprecated ... 경고는 하위 의존성 경고이며 설치 실패 원인이 아닙니다.
기본 로컬 embedding 모델은 Xenova/multilingual-e5-small입니다.
@huggingface/transformers/ONNX Runtime CPU에서 동작하므로 CUDA가 필요 없습니다.intfloat/multilingual-e5-small은 multilingual + Korean(ko) 지원 모델이고, Xenova variant는 Transformers.js용 ONNX 파일을 제공합니다.--embedding-model <hf-model> 또는 CLAUDE_MEMORY_EMBEDDING_MODEL로 onnx-community/Qwen3-Embedding-0.6B-ONNX, onnx-community/embeddinggemma-300m-ONNX 같은 Transformers.js/ONNX 모델을 실험할 수 있습니다. 다만 이들은 다운로드/CPU 비용이 더 크거나 모델/라이선스 성숙도를 별도 검토해야 합니다.claude-memory-layer import --project "$PWD" --embedding-model Xenova/multilingual-e5-small
CLAUDE_MEMORY_EMBEDDING_MODEL=onnx-community/Qwen3-Embedding-0.6B-ONNX claude-memory-layer process --project "$PWD"
cd /path/to/your-project
claude-memory-layer import
~/.claude/projects/...)을 읽어와 메모리로 적재합니다.# 프로젝트 메모리 검색
claude-memory-layer search "인증 구조"
# 통계 확인
claude-memory-layer stats
# 대시보드 실행
claude-memory-layer dashboard --no-open
네. 완전히 동일한 흐름을 각 프로젝트에서 반복하면 됩니다.
cd /path/to/another-project
claude-memory-layer import
claude-memory-layer search "배포 이슈"
프로젝트마다 내부적으로 별도 저장소(~/.claude-code/memory/projects/<hash>)를 사용하므로,
기억이 자동으로 분리됩니다. 같은 저장소(git) 안의 워크트리·하위 디렉터리는 메인 체크아웃으로
자동 수렴합니다.
git 경계를 넘어 수렴시키고 싶을 때 — 예: 워크스페이스 제품이 채팅/인스턴스마다 디렉터리(각자 git repo인 경우 포함)를 만들어 메모리가 파편화될 때 — 워크스페이스 루트에 빈 마커 파일을 두면 하위 모든 경로가 그 디렉터리 하나의 저장소를 공유합니다:
touch <workspace-root>/.claude-memory-root
.git을 가진 하위 repo보다 우선합니다 — 그것이 이 opt-in의 존재 이유입니다.--project <path> 사용 가능import --force 사용--session-limit <n> 또는 --limit <n> 사용maintenance install로 주기 처리하거나 process로 수동 처리GET /health (서버 헬스)GET /api/health (outbox pending/failed 포함 상세 헬스)GET /api/stats/retrieval-traces (검색→컨텍스트 채택 추적)CLAUDE_MEMORY_RETRIEVAL_MODE (기본 hybrid, keyword/hybrid/semantic)CLAUDE_MEMORY_SEMANTIC_DAEMON_IDLE_MS (기본 600000, semantic daemon 유휴 종료 시간)CLAUDE_MEMORY_MIN_SCORE (기본 0.4)CLAUDE_MEMORY_FALLBACK_MIN_SCORE (기본 0.3, 결과 0건일 때 재시도)새 서버에서 Claude Memory Layer를 설치하고 기존 Claude Code/Codex/Hermes 대화 기록을 처음 적재할 때는 아래 체크리스트를 따르세요.
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이 반영됩니다.
가장 안전한 방식은 원본 대화 기록을 새 서버로 복사한 뒤 새 서버에서 다시 import하는 것입니다. 필요한 것만 선택해서 복사하세요. 이 디렉토리/DB에는 민감한 대화와 경로가 포함될 수 있으므로 공개 저장소에 커밋하거나 공유하지 말고, SSH/사설망 등 신뢰할 수 있는 경로로만 복사하세요.
# 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으로 일관된 스냅샷을 만든 뒤 가져오세요.
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 방식을 우선 권장합니다.
mkdir -p ~/.claude-code
rsync -a OLD_HOST:~/.claude-code/memory/ ~/.claude-code/memory/
프로젝트 메모리는 프로젝트 경로 기준으로 분리됩니다. 새 서버의 실제 repo 경로를 PROJECT에 넣고, 필요한 importer만 실행하세요.
중요: Codex/Hermes/Claude Code 원본 세션의 project filter는 대화가 생성될 당시의 절대 경로를 기준으로 매칭합니다. 새 서버에서도 repo 절대 경로가 이전 서버와 같으면 아래 project import를 그대로 쓰면 됩니다.
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)로 가져오세요.
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도 의도적으로 전역 메모리를 만들 때만 사용하세요.--anonymize-projects를 함께 사용하세요.--force는 기존 import 이벤트를 지우고 재적재하므로 신중히 사용하세요.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
# 프로젝트 저장소 분리 상태를 aggregate-only 리포트로 점검
claude-memory-layer project scope-audit --days 7
Claude Desktop은 CLI로 자동 등록할 수 있습니다. GUI 앱에서 shell PATH가 다를 수 있으면 stdio binary의 절대 경로를 command로 넣는 방식이 더 견고합니다.
claude-memory-layer mcp install --command "$(command -v claude-memory-layer-mcp)"
# Claude Desktop 재시작
Codex/Hermes 등 MCP client에도 전역 설치된 stdio binary를 등록하면 됩니다.
# 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에 넣으세요.
MCP 서버는 client의 stdio가 닫히거나 부모 프로세스가 사라지면 자원을 정리하고 종료합니다. 연결은 유지됐지만 호출이 없을 때는 기본 10분 후 embedding 모델/native 자원을 해제하며, 다음 호출에서 자동으로 다시 준비합니다. 필요하면 CLAUDE_MEMORY_MCP_IDLE_RELEASE_MS를 60000~86400000ms 범위에서 지정할 수 있습니다.
[mem:abc123] 형태로 추적하고 source/mem-source-ref로 근거 확인mem-source-ref(includeNeighbors=true, neighborWindow=1..5)로 MemPalace식 hit 주변 세션 이벤트를 privacy-safe preview로 함께 확인<private> 태그, credential/path redaction, aggregate-only dashboard/API/CLI 출력memory/<namespace>/.../YYYY-MM-DD.md에 append검색 랭킹에 영향을 주는 기능은 기본적으로 꺼져 있고(옵트인), ~/.claude-code/memory/operations.json 파일로 켭니다 (v2.2.0+):
mkdir -p ~/.claude-code/memory
cat > ~/.claude-code/memory/operations.json <<'EOF'
{
"enabled": true,
"codifyLite": { "enabled": true }
}
EOF
동작 방식:
false로 바꾸거나 파일을 삭제하면 됩니다.CLAUDE_MEMORY_OPERATIONS_CONFIG_PATH 환경변수로 다른 파일을 지정할 수 있습니다 (주로 테스트·격리용).켤 수 있는 플래그 (전체 스키마는 MemoryOperationsConfigSchema 참고):
참고: 코어 메모리 블록·mem-entity-supersede·temporal graph 조회는 플래그와 무관하게 항상 사용 가능합니다. 이 플래그들은 자동 수집·검색 랭킹처럼 "가만히 있어도 동작이 바뀌는" 부분만 게이트합니다.
cd claude-memory-layer
npm install
npm run build
Claude Code hook 설정은 CLI가 등록합니다:
npx claude-memory-layer install
주의:
install/uninstall은~/.claude/settings.json을 수정합니다. 자동 테스트나 임의 실행 대신, 실제 사용자가 설치/해제를 원할 때만 실행하세요.
플러그인은 Claude Code 세션에 자동으로 연결되어 동작합니다:
Claude Code 내에서 사용할 수 있는 명령어:
# 메모리 검색 - 관련 기억 찾기
/memory-search "authentication 구현 방법"
# 대화 기록 보기
/memory-history
/memory-history --limit 50
/memory-history --session <session-id>
# 통계 확인
/memory-stats
# 기존 대화 기록 임포트
/memory-import # 현재 프로젝트
/memory-import --all # 모든 프로젝트
/memory-import --project /path/to/project # 특정 프로젝트
# 임포트 가능한 세션 목록
/memory-list
# 메모리 삭제
/memory-forget --session <id> --confirm
레거시 markdown 메모리를 읽어서 구조화 경로로 재저장(import)할 수 있습니다.
# 미리보기(실제 저장 없음)
claude-memory-layer organize-import /path/to/legacy-memory --dry-run
# 실제 import
claude-memory-layer organize-import /path/to/legacy-memory --project /path/to/project
# 일부만 import
claude-memory-layer organize-import /path/to/legacy-memory --limit 100
# source에 markdown이 없으면 자동 bootstrap(코드+git 분석)
claude-memory-layer organize-import /path/to/empty-dir --project /path/to/project
# bootstrap 강제 실행
claude-memory-layer organize-import /path/to/memory --force-bootstrap --repo /path/to/project
# 자동 bootstrap 비활성화
claude-memory-layer organize-import /path/to/empty-dir --no-bootstrap-if-empty
# markdown이 없는 초기 상태면 bootstrap 생성 + import
claude-memory-layer organize-import /path/to/empty-dir --bootstrap --repo /path/to/codebase
# bootstrap 강제 재생성 (기존 markdown 있어도)
claude-memory-layer organize-import /path/to/legacy-memory --force-bootstrap --repo /path/to/codebase --out /path/to/legacy-memory/bootstrap-kb
# 증분 bootstrap (기본값): 이전 manifest를 기준으로 변경분 중심 업데이트
claude-memory-layer organize-import /path/to/legacy-memory --bootstrap --repo /path/to/codebase --incremental
# 전체 재생성 bootstrap
claude-memory-layer organize-import /path/to/legacy-memory --bootstrap --repo /path/to/codebase --no-incremental
전역 설치 후에는 claude-memory-layer를 그대로 쓰고, 로컬 checkout에서는 npx claude-memory-layer 또는 node dist/cli/index.js를 사용할 수 있습니다.
# 메모리 검색 / progressive disclosure
claude-memory-layer search "React 컴포넌트 패턴" --top-k 10
claude-memory-layer search "API 에러 처리" --disclosure
claude-memory-layer expand mem:abc123
claude-memory-layer source mem:abc123
# 대화 기록 / 통계
claude-memory-layer history --limit 50 --type user_prompt
claude-memory-layer stats --project /path/to/project
# Claude Code 세션 import
claude-memory-layer list --project /path/to/project
claude-memory-layer import --project /path/to/project --verbose
# Codex/Hermes 세션은 read-only 검증 후 명시적으로 import
claude-memory-layer codex validate --project /path/to/project --format markdown --anonymize-projects
claude-memory-layer codex import --project /path/to/project --verbose
claude-memory-layer hermes validate --project /path/to/project --format markdown
claude-memory-layer hermes import --project /path/to/project --verbose
# 임베딩/벡터 outbox 처리와 상태 점검
claude-memory-layer process --project /path/to/project
claude-memory-layer process --project /path/to/project --dry-run-recovery
claude-memory-layer vector-status --project /path/to/project
# MCP/semantic daemon의 aggregate-only 런타임 리소스 상태
claude-memory-layer runtime-status
claude-memory-layer runtime-status --json
# 머신 전체 프로젝트 저장소의 bounded maintenance
claude-memory-layer maintenance run
claude-memory-layer maintenance run --min-free-gb 10
claude-memory-layer maintenance install --interval 300
claude-memory-layer maintenance status
claude-memory-layer maintenance uninstall
# registry/canonical store 분리 상태의 aggregate-only 감사
claude-memory-layer project scope-audit --days 7
claude-memory-layer project scope-audit --days 7 --json
# Perspective Memory actor/session membership backfill
claude-memory-layer actors repair --project /path/to/project --dry-run
claude-memory-layer actors repair --project /path/to/project --apply
# Memory Operations
claude-memory-layer facet query --project /path/to/project --dimension workflow
claude-memory-layer facet tag --project /path/to/project --target-type event --target-id <id> --dimension workflow --value release --actor <actor> --apply
claude-memory-layer action list --project /path/to/project
claude-memory-layer frontier --project /path/to/project --limit 20
claude-memory-layer checkpoint list --project /path/to/project
claude-memory-layer retention audit --project /path/to/project
# Dashboard
claude-memory-layer dashboard --no-open
claude-memory-layer dashboard --bind localhost --port 37777 --password "<local-password>" --no-open
# External read-only market/company context
claude-memory-layer market-context --company 삼성전자 --dart-corp-code 00126380 --symbol 005930.KS --json
MongoDB 동기화는 선택 기능입니다. 여러 서버에서 같은 프로젝트를 개발할 때, 각 서버의 로컬 SQLite 이벤트를 하나의 MongoDB로 모아 push/pull할 수 있습니다. Pull된 이벤트를 바로 semantic search/context-pack에서 쓰고 싶다면 --process-after-sync를 함께 켜서 새 이벤트가 내려온 뒤 pending embedding/vector outbox를 처리하세요.
export CLAUDE_MEMORY_MONGO_URI="mongodb://USER:***@HOST:PORT/"
export CLAUDE_MEMORY_MONGO_DB="claude_memory_layer"
export CLAUDE_MEMORY_MONGO_PROJECT="my-project"
claude-memory-layer mongo-sync
claude-memory-layer mongo-sync --watch --interval 30000
claude-memory-layer mongo-sync --watch --interval 30000 --process-after-sync --process-interval 120000
--process-after-sync는 pull된 이벤트가 있을 때만 실행되며, --process-interval 동안 debounce되어 매 sync tick마다 불필요하게 임베딩을 재처리하지 않습니다. 내부적으로 project-scoped vector-worker.lock을 사용하므로 별도 process worker가 이미 실행 중이면 skip합니다.
아래 예시는 SDK/서비스 레벨에서 retrieveMemories() 호출 시 적용되는 옵션입니다.
import { getMemoryServiceForProject } from './src/services/memory-service.js';
const memory = getMemoryServiceForProject('/path/to/project');
// 1) Fast: 키워드 기반 빠른 검색
const fast = await memory.retrieveMemories('브리핑 포맷', {
strategy: 'fast',
topK: 5,
minScore: 0.6
});
// 2) Deep: 벡터 검색 + 키워드 오버랩 재정렬
const deep = await memory.retrieveMemories('브리핑 포맷', {
strategy: 'deep',
topK: 10,
rerankWithKeyword: true
});
// 3) Scoped filter: 세션/타입/계층형 메타데이터로 범위 제한
const scoped = await memory.retrieveMemories('아침 브리핑', {
strategy: 'deep',
scope: {
sessionIdPrefix: 'agent:main:',
eventTypes: ['user_prompt', 'agent_response'],
canonicalKeyPrefix: 'pref/briefing',
contentIncludes: ['아침'],
metadata: {
'scope.project.id': 'alpha'
}
}
});
팁:
strategy: 'auto'는 기본적으로 fallback 체인을 사용해 결과를 찾습니다.fast, 정확도 우선이면 deep를 권장합니다.getMemoryServiceForProject) 기준 검색 스코프는 기본적으로 project-aware(엄격 모드)로 동작합니다.민감한 정보를 메모리에서 제외하려면 <private> 태그를 사용합니다:
이 부분은 저장됩니다.
<private>
API_KEY=sk-xxxx
SECRET_TOKEN=abc123
이 내용은 메모리에 저장되지 않습니다.
</private>
이 부분도 저장됩니다.
저장 결과:
이 부분은 저장됩니다.
[PRIVATE]
이 부분도 저장됩니다.
다음 패턴은 자동으로 마스킹됩니다:
password, api_key, secret, token검색 결과에는 인용 ID가 포함됩니다:
🔍 Search Results:
#1 [mem:a7Bc3x] (score: 0.94)
"SQLite/WAL을 사용하여 이벤트 소싱 패턴을..."
📅 2026-01-30 | 🔗 Session abc123
원본 확인:
claude-memory-layer show mem:a7Bc3x
세션 경계 없이 연속적인 메모리 스트림을 유지합니다:
# Endless Mode 활성화
claude-memory-layer endless enable
# 상태 확인
claude-memory-layer endless status
# 출력 예시:
# Mode: Endless
# Working Set: 47 events (last 18 hours)
# Continuity Score: 0.85 (seamless)
# Consolidated: 23 memories
현재 상태: MCP server implementation은
src/extensions/mcp/로 이동되어 있고,src/mcp/*는 compatibility shim입니다. package bin으로claude-memory-layer-mcp가 제공됩니다.
Claude Desktop 설정은 CLI로 자동 등록할 수 있습니다:
claude-memory-layer mcp install
# Config: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
이 명령은 Claude Desktop config의 기존 값을 보존하면서 다음 MCP server entry를 추가/갱신합니다:
{
"mcpServers": {
"claude-memory-layer": {
"command": "claude-memory-layer-mcp",
"args": []
}
}
}
옵션:
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를 직접 등록할 수 있습니다:
# 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 후 다음처럼 직접 실행할 수도 있습니다:
node dist/mcp/index.js
MCP 서버는 stdio 종료·부모 프로세스 소실 시 함께 종료됩니다. 유휴 상태에서는 기본 10분 후 embedding 모델/native 자원을 반납하고 다음 도구 호출에서 다시 적재합니다. 유휴 해제 시간은 CLAUDE_MEMORY_MCP_IDLE_RELEASE_MS(60000~86400000ms)로 조정할 수 있습니다.
MCP 도구 surface는 CLAUDE_MEMORY_MCP_PROFILE로 core, operations, governance, experimental, all 중 하나를 선택할 수 있습니다. 기본값 all은 기존 전체 도구 목록과 동작을 보존합니다. 작은 context/search 중심 surface가 필요하면 MCP server entry의 env에 CLAUDE_MEMORY_MCP_PROFILE=core를 설정하세요. 프로필별 범위, mutation 분류, 롤백 방법은 docs/MCP_TOOL_PROFILES.md를 참고하세요.
쓰기 제한 샌드박스에서 조회할 때는 MCP server entry의 env에 CLAUDE_MEMORY_MCP_READ_ONLY=1을 설정할 수 있습니다. Happy가 자동 recall을 담당해 CLAUDE_MEMORY_RECALL_OWNER=host를 전달하는 native MCP도 이 모드를 사용합니다. 선택한 프로필에서 mem-context-pack, mem-search, mem-timeline, mem-details, mem-project-timeline, mem-source-ref, mem-stats, mem-lesson-get, mem-lesson-list, external-market-context만 노출하며, 그 외 도구와 명시적 freshness refresh는 read_only_runtime 오류로 거절합니다.
이 모드의 메모리 조회는 임시 SQLite snapshot과 어휘 검색을 사용합니다. 의미 검색용 모델·vector 초기화, 자동 import, 조회 telemetry 기록을 수행하지 않으므로 의미 검색 품질과 usage 집계에 차이가 있습니다. mem-stats는 기존 vector index가 있으면 읽기 전용으로 개수를 조회합니다. mem-context-pack의 refreshLatest=false도 모델 초기화 없이 조회합니다. 원본 메모리 파일을 읽을 권한과 canonical memory 밖의 임시 디렉터리에 쓸 권한은 필요하며, 이 설정이 샌드박스 권한을 늘려주지는 않습니다. 동시 checkpoint 중 snapshot은 최신 데이터를 놓칠 수 있으므로 최신성이 필요하면 조회를 반복하거나 권한이 있는 writable runtime에서 import 후 조회하세요. 새 바이너리 설치 후에는 MCP 프로세스를 재시작해야 적용됩니다.
대부분의 project-scoped 도구는 projectPath를 지원하거나 요구합니다. mutating 도구는 audit용 actor와 evidence/source refs를 요구하고, raw transcript/path/secret 출력은 피합니다.
mem-lesson-candidates는 반복 성공 패턴 그룹을 결정적으로 채굴한 뒤, 로컬에 로그인된 claude(또는 codex) CLI 서브프로세스로 lesson 텍스트(name/trigger/steps/failureModes)를 추출합니다. 별도 API 키가 필요 없고, 추출 결과는 후보 그룹별로 캐시되어 재조회·승격 시 동일 텍스트를 반환합니다. 트랜스크립트는 서브프로세스에 넘기기 전에 경로/자격증명 redaction을 거칩니다.
호출당 신규(미캐시) 추출은 3그룹으로 제한됩니다. 남은 그룹은 응답의 extraction 통계와 note에 보고되며, 다시 호출하면 캐시된 그룹은 건너뛰고 이어서 추출합니다.
예시 workflow:
1. 새 작업 시작: mem-context-pack(projectPath, query)
2. 최근 흐름 확인: mem-project-timeline(projectPath)
3. 근거가 더 필요할 때: mem-source-ref(projectPath, ids=["mem:abc123"], includeNeighbors=true, neighborWindow=1)
이 workflow는 Hermes/Codex/Claude Code가 같은 project-scoped memory backend를 공유할 때 특히 유용합니다. mem-source-ref는 raw transcript를 그대로 덤프하지 않고 allowlisted metadata와 privacy-filtered preview만 반환합니다.
브라우저에서 메모리 대시보드를 확인할 수 있습니다:
# 웹 서버 시작
claude-memory-layer dashboard
# 브라우저에서 접속
# http://localhost:37777
localhost bind, 명시적 0.0.0.0, 선택적 password gate이미 Claude Code를 사용해왔다면, 기존 대화 기록을 임포트하여 바로 활용할 수 있습니다:
# 1. 먼저 임포트 가능한 세션 확인
npx claude-memory-layer list
# 2. 현재 프로젝트의 모든 세션 임포트
npx claude-memory-layer import
# 3. 또는 모든 프로젝트의 세션 임포트
npx claude-memory-layer import --all --verbose
📥 Importing all sessions from all projects
⏳ Processing embeddings...
✅ Import Complete
Sessions processed: 15
Total messages: 342
Imported prompts: 156
Imported responses: 186
Skipped duplicates: 0
Embeddings processed: 342
Codex CLI 기록(~/.codex/sessions)은 기본적으로 read-only validate/replay로 먼저 확인하고, 명시적 import 명령으로 메모리에 저장할 수 있습니다:
# 읽기 전용 검증/리포트
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.
Codex lifecycle hook을 opt-in으로 설치하면 프로젝트별 자동 메모리를 사용할 수 있습니다.
# 최초 1회
claude-memory-layer codex hooks install
# Codex를 재시작하고 /hooks에서 정의를 검토·신뢰한 뒤 상태 확인
claude-memory-layer codex hooks status --project /path/to/project
# 제거 시 다른 Codex 훅은 보존되고 CML 훅만 제거됨
claude-memory-layer codex hooks uninstall
SessionStart: 해당 프로젝트의 core memory와 최근 작업 메모리 인덱스를 Codex에 주입합니다. 일반 메모리는 제목·짧은 요약·mem: source ref·세션/턴 위치만 제공하며, 새 세션뿐 아니라 resume/clear/compact에도 적용됩니다.UserPromptSubmit: 질문마다 관련 메모리 인덱스를 검색합니다. Codex는 필요할 때만 mem-source-ref/mem-details로 원문을 확장하고, 실제로 사용한 경우에만 답변 끝에 📎 Recalled memories: <title> ([mem:ID])를 표시합니다.SessionEnd: 완료된 현재 transcript 하나만 별도 worker에 전달해 프로젝트 저장소로 적재합니다. Codex 종료, 대화 archive/delete, 또는 열려 있지 않은 대화의 30분 유휴 종료 시 실행됩니다.codex hooks status --project <path>는 해당 프로젝트의 마지막 자동 import 성공/실패 시각과 집계 결과를 보여줍니다. transcript 본문은 상태 파일에 기록하지 않습니다.codex validate와 importer 회귀 테스트를 함께 유지해야 합니다.Hermes Agent 기록(~/.hermes/state.db)도 원본 DB를 read-only validate/replay로 먼저 확인하고, 명시적 import 명령으로만 프로젝트별 메모리에 저장합니다. 기본 전략은 live sync가 아니라 SessionDB → CML explicit derived import입니다:
# 읽기 전용 검증/리포트
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 본문은 포함하지 않습니다.
임포트는 콘텐츠 해시 기반으로 중복을 자동 감지합니다. 여러 번 실행해도 같은 내용이 중복 저장되지 않습니다.
사용자 프롬프트 입력
↓
EventStore에 저장 (SQLite/WAL, append-only)
↓
Outbox에 임베딩 요청 등록
↓
Vector Worker가 임베딩 생성
↓
VectorStore에 저장 (LanceDB)
새 프롬프트 입력
↓
임베딩 생성
↓
VectorStore에서 유사 벡터 검색
↓
AXIOMMIND Matcher로 신뢰도 계산
↓
컨텍스트로 Claude에 제공
자주 참조되는 메모리는 더 높은 레벨로 승격됩니다:
검색 결과는 신뢰도에 따라 분류됩니다:
┌──────────────────────────────────────────────────────────────────────┐
│ Agent surfaces │
│ Claude Code Hooks │ CLI │ Dashboard │ MCP Clients │ Codex/Hermes import │
└───────────────────────────────┬──────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────────┐
│ Memory Service / Runtime │
│ Retrieval Orchestrator │ Disclosure │ Operations │ Perspective Memory │
│ Evidence/Privacy filters │ Governance audit │ Context-pack assembler │
└───────────────────────────────┬──────────────────────────────────────┘
│
┌─────────────────────┼─────────────────────┐
▼ ▼ ▼
┌──────────────────┐ ┌──────────────────┐ ┌───────────────────────┐
│ SQLite EventStore│ │ Operations tables│ │ External read-only ctx │
│ events/sessions │ │ facets/actions/ │ │ DART/FRED/Finnhub │
│ actor/perspective│ │ checkpoints/... │ │ │
└─────────┬────────┘ └──────────────────┘ └───────────────────────┘
│ same transaction
▼
┌──────────────────┐ worker lock/recovery ┌──────────────────┐
│ Vector Outbox V2 │ ─────────────────────────────▶ │ LanceDB vectors │
│ itemKind/id/ver │ versioned delete+add upsert │ per item/version │
└──────────────────┘ └──────────────────┘
핵심 원칙은 SQLite가 canonical source of truth이고, LanceDB는 재생성 가능한 derived accelerator라는 점입니다. 모든 vector write는 outbox를 통해 idempotent하게 처리하며, MCP/dashboard/CLI 출력은 가능한 aggregate 또는 redacted preview만 제공합니다.
┌─────────────────────────────────────────────────────────────┐
│ edges │
│ ┌──────────┐ evidence_of ┌──────────┐ │
│ │ Entry │ ─────────────────▶│ Entity │ │
│ │ (Fact, │ │ (Task, │ │
│ │ Decision)│ │ Artifact)│ │
│ └──────────┘ └──────────┘ │
│ │ │ │
│ │ derived_from │ blocked_by │
│ ▼ ▼ │
│ ┌──────────┐ ┌──────────┐ │
│ │ Entry │ │ Entity │ │
│ └──────────┘ └──────────┘ │
└─────────────────────────────────────────────────────────────┘
Layer 1: Search Index (~50-100 tokens/result)
│ { id, summary, score }
│
└──▶ Layer 2: Timeline Context (~200 tokens)
│ 시간순 전후 맥락
│
└──▶ Layer 3: Full Details (~500-1000 tokens)
선택된 항목만 전체 로드
┌─────────────────────┐ ┌─────────────────────┐
│ Claude Desktop │◀────────│ claude-memory-layer │
│ (MCP Client) │ stdio │ (MCP Server) │
└─────────────────────┘ └──────────┬──────────┘
│
▼
┌─────────────────────┐
│ Shared Storage │
│ ~/.claude-code/ │
└─────────────────────┘
메모리는 기본적으로 다음 위치에 저장됩니다:
~/.claude-code/memory/
├── projects/<hash>/events.sqlite # 프로젝트별 이벤트 저장소 (primary)
├── projects/<hash>/vectors/ # 프로젝트별 벡터 임베딩
└── shared/ # (옵션) 공유 지식 저장소
Claude Code 세션 기록 위치:
~/.claude/projects/<project-hash>/<session-id>.jsonl
# 의존성 설치
npm install
# 빌드
npm run build
# 테스트
npm test
# 타입 체크
npm run typecheck
# 개발 모드 실행
npm run dev
src/extensions/vector/)claude-memory-layer-mcp stdio server)상세 설계 문서는 specs/ 디렉토리에서 확인할 수 있습니다:
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:
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:
DART_API_KEY, FRED_API_KEY, and FINNHUB_API_KEY..env* files are ignored; .env.example is placeholder-only.crtfc_key, api_key, and token.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.v1subject: company, DART corpCode, ticker symbolcoverage: DART/FRED/Finnhub provider status and countsbullCases, bearCases, risks, catalysts: deterministic evidence-backed insightswatchlist and followUpQuestionsThe 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.
MIT
Project-scoped memory layer for Claude Code, Codex, Hermes, MCP, and dashboards
{ "mcpServers": { "claude-memory-layer": { "command": "npx", "args": [ "-y", "[email protected]" ] } }}工具
尚無工具清單。遠端伺服器會在首次健康檢查後取得工具清單。
常見問題
在本頁複製適用於 Cursor、Claude Desktop、Claude Code 或 VS Code 的 stdio 設定。它使用發布者的安裝方式，而不是 PlugMCP 代理伺服器。
這筆記錄未列出必要的環境變數。
Claude Memory Layer 透過 stdio 在本機執行。
上次檢查時間：2026-11-15。 Project-scoped memory layer for Claude Code, Codex, Hermes, MCP, and dashboards