claude-memory-layer

v1.0.42

Published

a day ago

Claude Code plugin that learns from conversations to provide personalized assistance

0High
0Medium
0Low

namsangboy

claude-code plugin memory learning personalization context

Claude Memory Layer

Claude Code 플러그인으로, 대화 내용을 기억하여 사용할수록 똑똑해지는 AI 어시스턴트를 만듭니다.

개요

Claude Memory Layer는 Claude Code에서 사용자와 AI 간의 모든 대화를 저장하고, 새로운 질문을 할 때 관련된 과거 대화를 자동으로 검색하여 컨텍스트로 제공합니다. 이를 통해:

연속성 있는 대화: 이전 세션에서 논의한 내용을 기억
프로젝트 맥락 이해: 프로젝트별로 축적된 지식 활용
개인화된 응답: 사용자의 선호도와 패턴 학습

빠른 시작 (신규 프로젝트 기준)

아래 순서대로 하면 됩니다.

0) 최초 1회(머신 전체) 설치

권장 설치 방식은 npm에 배포된 패키지를 전역 설치하는 것입니다. install은 Claude Code hook 파일 경로를 ~/.claude/settings.json에 저장하므로, 일회성 npx claude-memory-layer install보다 전역 설치 또는 고정된 로컬 checkout을 쓰는 것이 안전합니다.

npm install -g claude-memory-layer@latest
claude-memory-layer install
claude-memory-layer 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

install은 한 번만 하면 됩니다(Claude Code hooks 등록).
Embedding backend은 런타임 필수 기능이지만, npm 설치 단계에서는 optionalDependencies + postinstall repair로 처리합니다. CUDA 11 환경에서 onnxruntime-node의 GPU 바이너리 자동 설치가 실패해도 패키지 설치 자체를 살리고 CPU-only backend로 복구하기 위해서입니다.
이후 프로젝트별로 메모리 저장소가 자동 분리됩니다.
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이 실패할 수 있습니다.

Error: CUDA 11 binaries are not supported by this script yet.

Claude Memory Layer는 로컬 semantic/vector embedding에 필요한 @huggingface/transformers를 런타임 필수 backend로 취급합니다. 다만 CUDA 11 환경에서 하위 의존성 설치가 먼저 실패하는 문제를 피하려고 npm dependency level에서는 optional로 두고, 설치 중 postinstall repair가 ONNXRUNTIME_NODE_INSTALL_CUDA=skip으로 CPU-only ONNX Runtime을 자동 복구합니다. npm 로그에 onnxruntime-node의 CUDA 11 stack trace가 보이더라도 최종 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만 손상/누락된 경우에는 postinstall repair와 런타임 오류 메시지가 동일한 CPU-only 복구 명령을 안내합니다.

npm warn deprecated ... 경고는 하위 의존성 경고이며 설치 실패 원인이 아닙니다.

Embedding model

기본 로컬 embedding 모델은 Xenova/multilingual-e5-small입니다.

@huggingface/transformers/ONNX Runtime CPU에서 동작하므로 CUDA가 필요 없습니다.
원본 intfloat/multilingual-e5-small은 multilingual + Korean(ko) 지원 모델이고, Xenova variant는 Transformers.js용 ONNX 파일을 제공합니다.
384차원이라 대규모 세션 import에서도 CPU/메모리 부담이 작습니다.
더 높은 품질이 필요하면 --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"

1) 새 프로젝트에서 초기 메모리 생성

cd /path/to/your-project
claude-memory-layer import

현재 프로젝트의 기존 Claude Code 세션(~/.claude/projects/...)을 읽어와 메모리로 적재합니다.
벡터 임베딩까지 한 번에 처리됩니다.

2) 사용 중 확인

# 프로젝트 메모리 검색
claude-memory-layer search "인증 구조"

# 통계 확인
claude-memory-layer stats

# 대시보드 실행
claude-memory-layer dashboard --no-open

3) 다른 프로젝트에도 동일하게 적용?

네. 완전히 동일한 흐름을 각 프로젝트에서 반복하면 됩니다.

cd /path/to/another-project
claude-memory-layer import
claude-memory-layer search "배포 이슈"

프로젝트마다 내부적으로 별도 저장소(~/.claude-code/memory/projects/<hash>)를 사용하므로, 기억이 자동으로 분리됩니다.

4) 운영 팁

특정 프로젝트를 명시하고 싶으면 대부분 명령에 --project <path> 사용 가능
대규모 리임포트가 필요하면 import --force 사용
최근 일부만 가져오고 싶으면 --session-limit <n> 또는 --limit <n> 사용
백그라운드 worker가 못 처리한 임베딩은 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건일 때 재시도)

다른 서버 초기 세팅 & 이전 대화 ingest

새 서버에서 Claude Memory Layer를 설치하고 기존 Claude Code/Codex/Hermes 대화 기록을 처음 적재할 때는 아래 체크리스트를 따르세요.

1) 새 서버 준비

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/사설망 등 신뢰할 수 있는 경로로만 복사하세요.

# 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/

3) 프로젝트별로 read-only 검증 후 import

프로젝트 메모리는 프로젝트 경로 기준으로 분리됩니다. 새 서버의 실제 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도 의도적으로 전역 메모리를 만들 때만 사용하세요.
import/validate/list 결과에는 대화 내용 일부나 로컬 경로가 포함될 수 있습니다. 외부 공유 전에는 민감정보와 경로를 제거하고, Codex validate 리포트는 필요하면 --anonymize-projects를 함께 사용하세요.
import는 콘텐츠 해시 기반으로 중복을 건너뛰므로 여러 번 실행해도 같은 내용이 중복 저장되지 않습니다. 단, --force는 기존 import 이벤트를 지우고 재적재하므로 신중히 사용하세요.

4) 검증

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로 넣는 방식이 더 견고합니다.

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에 넣으세요.

Features

Core Features

Conversation Memory: 사용자 프롬프트와 AI 응답 저장
Semantic Search: 벡터 임베딩을 통한 의미 기반 검색
AXIOMMIND Architecture: 7가지 원칙 기반 안정적 메모리 관리
Memory Graduation: L0→L4 단계별 메모리 승격
Evidence Alignment: 응답이 실제 기억에 기반했는지 검증
History Import: 기존 Claude Code 세션 기록 임포트

Advanced Features

Citations System: 메모리 출처 추적 ([mem:abc123] 형식)으로 검색 결과의 원본 확인 가능
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와 동일한 메모리 공유 (stdio server bin: claude-memory-layer-mcp)
PostToolUse Hook: 도구 실행 결과 (Read, Write, Bash 등) 캡처 및 저장
Private Tags: <private> 태그로 민감 정보를 명시적으로 제외
Progressive Disclosure: 3-Layer 검색 (인덱스 → 타임라인 → 상세)으로 토큰 효율화
memU-inspired Retrieval: fast/deep 전략 + 스코프 필터(session prefix, canonical key prefix, metadata path)
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 패턴으로 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. 의존성 설치

cd claude-memory-layer
npm install

2. 빌드

npm run build

3. Claude Code에 플러그인 등록

Claude Code hook 설정은 CLI가 등록합니다:

npx claude-memory-layer install

주의: install / uninstall은 ~/.claude/settings.json을 수정합니다. 자동 테스트나 임의 실행 대신, 실제 사용자가 설치/해제를 원할 때만 실행하세요.

사용 방법

자동 동작 (Hooks)

플러그인은 Claude Code 세션에 자동으로 연결되어 동작합니다:

| Hook | 동작 | |------|------| | SessionStart | 세션 시작 시 프로젝트 관련 컨텍스트 로드 | | UserPromptSubmit | 프롬프트 입력 시 관련 기억 검색 및 저장 | | Stop | AI 응답 완료 시 응답 내용 저장 | | SessionEnd | 세션 종료 시 요약 생성 및 저장 |

Slash 명령어

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

기존 메모리 정리 Import (구조화)

레거시 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

CLI 명령어

터미널에서 직접 사용:

# 메모리 검색
npx claude-memory-layer search "React 컴포넌트 패턴"
npx claude-memory-layer search "API 에러 처리" --top-k 10

# 대화 기록 조회
npx claude-memory-layer history
npx claude-memory-layer history --limit 50 --type user_prompt

# 통계 확인
npx claude-memory-layer stats

# 기존 세션 임포트
npx claude-memory-layer import                    # 현재 프로젝트
npx claude-memory-layer import --all              # 모든 프로젝트
npx claude-memory-layer import --all --verbose    # 상세 로그

# 임포트 가능한 세션 목록
npx claude-memory-layer list
npx claude-memory-layer list --project /path/to/project

# 임베딩 수동 처리
npx claude-memory-layer process

# MongoDB 동기화 (옵션, 멀티 서버 협업)
# - 여러 서버에서 같은 프로젝트를 개발할 때, 각 서버의 로컬 SQLite(events.sqlite) 이벤트를
#   하나의 MongoDB로 모아 push/pull 동기화할 수 있습니다.
# - 동일 프로젝트는 반드시 같은 project key로 실행해야 합니다.
export CLAUDE_MEMORY_MONGO_URI="mongodb://USER:PASSWORD@HOST:PORT/"
export CLAUDE_MEMORY_MONGO_DB="claude_memory_layer"
export CLAUDE_MEMORY_MONGO_PROJECT="my-project"

# 1회 동기화 (push+pull)
npx claude-memory-layer mongo-sync

# 지속 동기화 (주기적으로 push+pull)
npx claude-memory-layer mongo-sync --watch --interval 30000

memU-inspired Retrieval 사용 예시

아래 예시는 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(엄격 모드)로 동작합니다.

Privacy 기능

Private Tags

민감한 정보를 메모리에서 제외하려면 <private> 태그를 사용합니다:

이 부분은 저장됩니다.

<private>
API_KEY=sk-xxxx
SECRET_TOKEN=abc123
이 내용은 메모리에 저장되지 않습니다.
</private>

이 부분도 저장됩니다.

저장 결과:

이 부분은 저장됩니다.
[PRIVATE]
이 부분도 저장됩니다.

자동 필터링

다음 패턴은 자동으로 마스킹됩니다:

password, api_key, secret, token
Bearer 토큰
Private Key 블록

Citations (인용 시스템)

검색 결과에는 인용 ID가 포함됩니다:

🔍 Search Results:

#1 [mem:a7Bc3x] (score: 0.94)
   "SQLite/WAL을 사용하여 이벤트 소싱 패턴을..."
   📅 2026-01-30 | 🔗 Session abc123

원본 확인:

claude-memory-layer show mem:a7Bc3x

Endless Mode

세션 경계 없이 연속적인 메모리 스트림을 유지합니다:

# 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

모드 비교

| 기존 세션 모드 | Endless Mode | |---------------|-------------| | 명확한 시작/끝 | 연속적 스트림 | | 세션별 요약 | 점진적 통합 | | 재시작 시 빈 상태 | 이전 컨텍스트 유지 |

MCP Desktop Integration

현재 상태: 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 도구

| 도구 | 설명 | |------|------| | 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:

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

브라우저에서 메모리 대시보드를 확인할 수 있습니다:

# 웹 서버 시작
claude-memory-layer dashboard

# 브라우저에서 접속
# http://localhost:37777

주요 기능

실시간 이벤트 스트림
세션/프로젝트별 탐색
벡터 검색 인터페이스
저장소 통계 대시보드
Outbox 상태 모니터링
Retrieval Trace (검색 질의 → 후보/채택 수 → 최종 context 채택 IDs) 1:1 확인
채택된 event ID 클릭으로 상세 모달 확인 + score breakdown(semantic/lexical/recency) 확인
후보(candidate) event ID 스냅샷도 함께 노출되어 검색→채택 전 과정을 추적 가능

기존 대화 기록 임포트

이미 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 세션 임포트

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.

Hermes 세션 임포트

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 본문은 포함하지 않습니다.

중복 처리

임포트는 콘텐츠 해시 기반으로 중복을 자동 감지합니다. 여러 번 실행해도 같은 내용이 중복 저장되지 않습니다.

동작 원리

1. 메모리 저장

사용자 프롬프트 입력
        ↓
    EventStore에 저장 (SQLite/WAL, append-only)
        ↓
    Outbox에 임베딩 요청 등록
        ↓
    Vector Worker가 임베딩 생성
        ↓
    VectorStore에 저장 (LanceDB)

2. 메모리 검색

새 프롬프트 입력
        ↓
    임베딩 생성
        ↓
    VectorStore에서 유사 벡터 검색
        ↓
    AXIOMMIND Matcher로 신뢰도 계산
        ↓
    컨텍스트로 Claude에 제공

3. 메모리 승격 (Graduation)

자주 참조되는 메모리는 더 높은 레벨로 승격됩니다:

| Level | 이름 | 설명 | 승격 조건 | |-------|------|------|-----------| | L0 | EventStore | 원본 이벤트 | 기본 저장 | | L1 | Structured | 구조화된 패턴 | 3회 이상 접근 | | L2 | Candidates | 검증된 스키마 | 5회 이상, 다중 세션 참조 | | L3 | Verified | 교차 검증됨 | 높은 신뢰도 | | L4 | Active | 활성 지식 | 10회 이상, 3개 이상 세션 |

매칭 신뢰도

검색 결과는 신뢰도에 따라 분류됩니다:

| 신뢰도 | 점수 | Gap | 동작 | |--------|------|-----|------| | High | ≥0.92 | ≥0.03 | 자동으로 컨텍스트에 포함 | | Suggested | ≥0.75 | <0.03 | 대안 제시 | | None | <0.75 | - | 매칭 없음 |

Architecture

System Overview

┌─────────────────────────────────────────────────────────────┐
│                     Claude Code Hooks                       │
│  SessionStart │ UserPromptSubmit │ Stop │ PostToolUse │ End │
└──────────────────────────┬──────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│                    Memory Service                           │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │  Retriever  │  │   Matcher   │  │  Graduation │         │
│  │  Progressive│  │   Evidence  │  │   L0 → L4   │         │
│  └─────────────┘  └─────────────┘  └─────────────┘         │
└──────────────────────────┬──────────────────────────────────┘
                           │
        ┌──────────────────┴──────────────────┐
        ▼                                      ▼
┌───────────────┐                    ┌───────────────┐
│  EventStore   │ ──── Outbox ────▶ │  VectorStore  │
│ (SQLite/WAL)  │    (V2 Pattern)   │   (LanceDB)   │
└───────────────┘                    └───────────────┘

Entity-Edge Model (3-Layer)

┌─────────────────────────────────────────────────────────────┐
│                        edges                                 │
│  ┌──────────┐    evidence_of    ┌──────────┐               │
│  │  Entry   │ ─────────────────▶│  Entity  │               │
│  │ (Fact,   │                   │ (Task,   │               │
│  │ Decision)│                   │ Artifact)│               │
│  └──────────┘                   └──────────┘               │
│       │                              │                       │
│       │ derived_from                 │ blocked_by           │
│       ▼                              ▼                       │
│  ┌──────────┐                   ┌──────────┐               │
│  │  Entry   │                   │  Entity  │               │
│  └──────────┘                   └──────────┘               │
└─────────────────────────────────────────────────────────────┘

Progressive Disclosure (토큰 효율화)

Layer 1: Search Index (~50-100 tokens/result)
    │     { id, summary, score }
    │
    └──▶ Layer 2: Timeline Context (~200 tokens)
              │     시간순 전후 맥락
              │
              └──▶ Layer 3: Full Details (~500-1000 tokens)
                        선택된 항목만 전체 로드

MCP Integration

┌─────────────────────┐         ┌─────────────────────┐
│   Claude Desktop    │◀────────│ claude-memory-layer │
│   (MCP Client)      │  stdio  │    (MCP Server)     │
└─────────────────────┘         └──────────┬──────────┘
                                           │
                                           ▼
                                ┌─────────────────────┐
                                │   Shared Storage    │
                                │  ~/.claude-code/    │
                                └─────────────────────┘

AXIOMMIND 7 원칙

Single Source of Truth: SQLite/WAL EventStore가 유일한 진실의 원천
Append-Only: 이벤트는 수정/삭제 없이 추가만
Idempotency: dedupe_key로 중복 이벤트 감지
Evidence Alignment: 주장이 실제 소스에 기반했는지 검증
Entity-Based Tasks: canonical_key로 일관된 엔티티 식별
Vector Store Consistency: SQLite outbox → LanceDB 단방향 흐름
Standard JSON: 모든 데이터는 이식 가능한 JSON 형식

저장 위치

메모리는 기본적으로 다음 위치에 저장됩니다:

~/.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

기술 스택

SQLite / WAL: 이벤트 저장소 (canonical append/read model)
LanceDB: 벡터 저장소 (derived acceleration index)
@huggingface/transformers: 로컬 임베딩 생성 (lazy import; Embedder는 src/extensions/vector/)
Zod: 런타임 타입 검증
Commander: CLI 인터페이스
TypeScript: 타입 안전한 코드
Node.js + Hono: HTTP 서버 / Web Viewer
Hono: 경량 라우터
MCP SDK: Claude Desktop 통합 (claude-memory-layer-mcp stdio server)

Specification Documents

상세 설계 문서는 specs/ 디렉토리에서 확인할 수 있습니다:

| 문서 | 설명 | |------|------| | citations-system | 메모리 인용 시스템 | | endless-mode | 연속 세션 모드 | | entity-edge-model | 3-Layer 데이터 모델 | | evidence-aligner-v2 | 증거 정렬 시스템 | | mcp-desktop-integration | MCP 서버 통합 | | post-tool-use-hook | 도구 사용 기록 | | private-tags | 프라이버시 태그 | | progressive-disclosure | 토큰 효율화 검색 | | task-entity-system | Task Entity 관리 | | vector-outbox-v2 | Transactional Outbox | | web-viewer-ui | 웹 대시보드 |

Roadmap

Phase 1: Core (완료)

[x] Event Store (SQLite/WAL)
[x] Vector Store (LanceDB)
[x] Memory Graduation (L0→L4)
[x] Evidence Alignment
[x] History Import

Phase 2: Advanced Features (진행 중)

[x] Citations System
[x] Endless Mode service boundary (experimental extension)
[ ] Entity-Edge Model productization
[x] Evidence Aligner V2
[x] Private Tags

Phase 3: Integration

[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:

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.