mkreyman/mcp-memory-keeper

Claude AI 코딩 어시스턴트를 위해 지속적인 컨텍스트 관리 (Context Management)를 제공하는 Model Context Protocol (MCP) 서버입니다. 압축 (Compaction) 과정에서 더 이상 컨텍스트를 잃어버리지 마세요! 이 MCP 서버는 Claude Code가 세션 전반에 걸쳐 컨텍스트를 유지할 수 있도록 도와주며, 작업 이력, 결정 사항 및 진행 상황을 보존합니다.

30초 안에 시작하기:

# Claude에 memory-keeper 추가
claude mcp add memory-keeper npx mcp-memory-keeper
# 새로운 Claude 세션을 시작하고 사용하세요!
...

끝입니다! 이제 모든 Claude 세션에서 Memory Keeper를 사용할 수 있습니다. 귀하의 컨텍스트는 ~/mcp-data/memory-keeper/에 저장되며 세션 간에도 지속됩니다.

# 프로젝트 설정 (Project Configuration)
## 개발 규칙 (Development Rules)
- 진행 상황을 추적하기 위해 항상 memory-keeper를 사용하십시오
...

# 나의 개발 워크플로우 (My Development Workflow)
제공된 프로젝트에서 작업할 때:
- channel: <project_name>과 함께 memory-keeper를 사용하십시오
...

사용자: /my-dev-workflow authentication-service
AI: authentication-service를 위한 워크플로우를 설정 중입니다.
[channel "authentication-service"와 함께 memory-keeper 사용 중]
...

패턴 (The Pattern):

• 커스텀 명령(Custom command)에 memory-keeper를 사용하라는 지침을 포함합니다.
• AI는 해당 지침을 자동으로 따릅니다.
  대화가 길어지고 있다고 느껴질 때, 귀하가 Claude에게 체크포인트 (Checkpoint)를 저장하도록 요청하십시오 (마치 보스 전투 전에 게임을 저장하는 것처럼!)
  Claude가 공간이 부족하여 새로 시작하게 될 때, 귀하가 체크포인트 키를 사용하여 복구하도록 지시하십시오

🎯 핵심 기능 (Key Feature): Memory Keeper는 공유 게시판입니다! 다음과 같은 작업이 가능합니다:

• 리셋 후에도 동일한 세션에서 계속 진행
• 완전히 새로운 세션을 시작하고 복구
• 여러 Claude 세션을 병렬로 실행하며 모두 동일한 메모리 공유
• 한 세션이 저장한 컨텍스트를 다른 세션이 검색

이를 통해 한 Claude 세션은 리서치를 수행하고, 다른 세션은 코드를 구현하면서 Memory Keeper를 통해 발견한 내용을 모두 공유하는 강력한 워크플로우를 구현할 수 있습니다!

Claude Code 사용자들은 대화창이 가득 찼을 때 문맥 손실 (Context loss) 문제를 자주 겪습니다. 이 MCP 서버는 Claude AI를 위한 지속 가능한 메모리 계층 (Persistent memory layer)을 제공함으로써 이 문제를 해결합니다. 복잡한 리팩토링 (Refactoring), 다중 파일 변경, 또는 긴 디버깅 세션을 진행하든 상관없이, Memory Keeper는 Claude 어시스턴트가 중요한 문맥, 결정 사항 및 진행 상황을 기억하도록 보장합니다.

• Claude Code를 이용한 긴 코딩 세션

• 문맥 보존 (Context preservation)이 필요한 복잡한 프로젝트

• 협업 개발을 위해 Claude AI를 사용하는 팀

• Claude 세션 전반에 걸쳐 지속적인 문맥을 원하는 개발자

• 🔄 Claude Code 세션 간 문맥 저장 및 복구

• 📁 변경 감지 기능이 포함된 파일 내용 캐싱 (Caching)

• 🏷️ 카테고리 및 우선순위를 통한 문맥 정리

• 📺 채널 (Channels)

  • 주제 기반의 지속적인 조직화 (git 브랜치에서 자동 유도)
  • 완전한 문맥 스냅샷을 위한 체크포인트 (Checkpoint) 시스템

• 🤖 중요한 정보를 절대 놓치지 않는 스마트 압축 (Compaction) 도우미

• 🔍 저장된 모든 문맥에 대한 전체 텍스트 검색

• 🕐 향상된 필터링 (Enhanced filtering)

  • 시간 기반 쿼리, 정규 표현식 (Regex) 패턴, 페이지네이션 (Pagination)

• 📊 변경 사항 추적 (Change tracking)

  • 특정 시점 이후에 무엇이 추가, 수정 또는 삭제되었는지 확인

• 💾 백업 및 공유를 위한 내보내기/가져오기 (Export/import)

• 🌿 자동 문맥 상관관계를 지원하는 Git 통합

• 📊 우선순위를 인식하는 AI 친화적 요약

• 🚀 Claude에 최적화된 빠른 SQLite 기반 저장소

• 🔁 일괄 작업 (Batch operations)

  • 여러 항목을 원자적 (Atomically)으로 저장, 업데이트 또는 삭제

• 🔄 채널 재할당 (Channel reassignment)

  • 패턴에 따라 항목을 채널 간에 이동

• 🔗 문맥 관계 (Context relationships)

  • 유형화된 관계를 통해 관련 항목 연결

• 👁️ 실시간 모니터링 (Real-time monitoring)

  • 필터를 통해 문맥 변화 감시

claude mcp add memory-keeper npx mcp-memory-keeper

이 단일 명령은 다음을 수행합니다:

• ✅ 항상 최신 버전을 사용
• ✅ 모든 종속성 (Dependencies)을 자동으로 처리
• ✅ macOS, Linux, Windows에서 작동
• ✅ 수동 빌드 또는 네이티브 모듈 문제 없음

전역 설치 (Global Installation)

npm install -g mcp-memory-keeper
claude mcp add memory-keeper mcp-memory-keeper

소스에서 설치 (개발용)

# 1. 저장소 클론 (Clone)
git clone https://github.com/mkreyman/mcp-memory-keeper.git
cd mcp-memory-keeper
...

DATA_DIR

• 데이터베이스 저장용 디렉토리 (기본값: ~/mcp-data/memory-keeper/)

MEMORY_KEEPER_INSTALL_DIR

• 설치 디렉토리 (기본값: ~/.local/mcp-servers/memory-keeper/)

MEMORY_KEEPER_AUTO_UPDATE

• 자동 업데이트를 활성화하려면 1로 설정

MCP_MAX_TOKENS

• 응답에서 허용되는 최대 토큰 (Maximum tokens) (기본값: 25000, 범위: 1000-100000)
• 사용 중인 MCP 클라이언트의 제한 사항이 다른 경우 이를 조정하십시오.

MCP_TOKEN_SAFETY_BUFFER

• 안전 버퍼 비율 (Safety buffer percentage) (기본값: 0.8, 범위: 0.1-1.0)
• 오버플로 (Overflow)를 방지하기 위해 최대 토큰의 이 비율만큼만 사용합니다.

MCP_MIN_ITEMS

• 제한을 초과하더라도 반환할 최소 항목 수 (Minimum items) (기본값: 1, 범위: 1-100)
• 최소한 일부 결과는 반드시 반환되도록 보장합니다.

MCP_MAX_ITEMS

• 응답당 허용되는 최대 항목 수 (Maximum items) (기본값: 100, 범위: 10-1000)
• 토큰 제한과 관계없이 결과 집합의 상한선을 설정합니다.

MCP_CHARS_PER_TOKEN

• 토큰당 문자 수 비율 (Characters per token ratio) (기본값: 3.5, 범위: 2.5-5.0)
  [고급 설정]
• 다양한 콘텐츠 유형에 대한 토큰 추정 정확도를 조정합니다.
• 낮은 값 = 더 보수적임 (더 안전하지만 더 적은 항목을 반환)
• 높은 값 = 더 공격적임 (더 많은 항목을 반환하지만 오버플로 위험이 있음)

더 엄격한 토큰 제한을 위한 설정 예시:

export MCP_MAX_TOKENS=20000 # 최대 토큰 낮춤
export MCP_TOKEN_SAFETY_BUFFER=0.7 # 더 보수적인 버퍼
export MCP_MAX_ITEMS=50 # 응답당 항목 수 감소
...

기본적으로 38개의 모든 도구 (Tools)가 노출됩니다. AI 어시스턴트의 컨텍스트 오버헤드 (Context overhead)를 줄이려면, 사용 가능한 도구를 제한하는 도구 프로필 (Tool profile)을 활성화할 수 있습니다.

빠른 사용법:

# 필수 도구만 사용 (8개 도구)
TOOL_PROFILE=minimal npx mcp-memory-keeper
# 표준 워크플로우 세트 (22개 도구)
...

내장된 프로필 (Built-in profiles):

내장된 프로필 (Built-in profiles):

프로필 (Profile)	도구 (Tools)	설명 (Description)
minimal	8	핵심 지속성 (Core persistence): save, get, search, status, checkpoint
standard	22	일상적인 워크플로우 (Daily workflow): 핵심 도구 + git, 배치 작업 (batch ops), 채널 (channels), 내보내기/가져오기 (export/import)
full	38	모든 도구 (기본값, 하위 호환성 유지)

설정 파일을 통한 커스텀 프로필 (Custom profiles via config file):

~/.mcp-memory-keeper/config.json 파일을 생성하여 프로필을 정의하거나 덮어쓸 수 있습니다:

{
"profiles": {
"my_workflow": [
...

그 다음 다음과 같이 활성화합니다: TOOL_PROFILE=my_workflow npx mcp-memory-keeper

설정 파일의 프로필은 동일한 이름을 가진 내장 기본값보다 우선순위를 갖습니다.

프로필 결정 우선순위 (Profile resolution precedence):

TOOL_PROFILE 설정 여부	설정 파일에 프로필이 있는가?	내장 프로필이 존재하는가?	결과
설정됨	예	—	설정 파일의 정의를 사용
...

환경 변수 (Environment variables):

변수 (Variable)	설명 (Description)
TOOL_PROFILE	활성화할 프로필 이름 (예: minimal, standard, full 또는 커스텀 프로필)
TOOL_PROFILE_CONFIG	설정 파일 경로 재정의 (기본값: ~/.mcp-memory-keeper/config.json)

참고: 프로필 결정은 서버 시작 시 한 번만 수행됩니다. 환경 변수나 설정 파일의 변경 사항은 다음 서버 재시작 시 적용됩니다.

Claude Code / Claude Desktop 설정:

{
"mcpServers": {
"memory-keeper": {
...

전체 설정 파일 예시는 examples/config.json을 참조하세요.

설정을 저장할 위치를 선택하세요:

# 프로젝트별 설정 (기본값) - 이 프로젝트 내에서 본인에게만 적용
claude mcp add memory-keeper npx mcp-memory-keeper

# .mcp.json을 통해 팀과 공유
...

# 구성된 모든 서버 목록 표시
claude mcp list

# Memory Keeper의 상세 정보 가져오기
...

• Claude Desktop 설정을 엽니다.
• "Developer" → "Model Context Protocol"로 이동합니다.
• "Add MCP Server"를 클릭합니다.
• 다음 설정을 추가합니다:

{
"mcpServers": {
"memory-keeper": {
...

끝입니다! 경로를 지정할 필요가 없습니다. npx가 모든 것을 자동으로 처리합니다.

• Claude Code를 재시작하거나 새로운 세션(session)을 시작하세요

• Memory Keeper 도구들이 자동으로 사용 가능해질 것입니다

• 다음 명령어로 테스트하세요:
  mcp_memory_save({ key: "test", value: "Hello Memory Keeper!" })

• 작동하지 않는다면, 서버 상태를 확인하세요:
  claude mcp list # memory-keeper가 "running" 상태로 표시되어야 합니다

• 설정을 추가한 후 Claude Desktop을 재시작하세요

• 새로운 대화에서 Memory Keeper 도구들을 사용할 수 있어야 합니다

• 위와 동일한 명령어로 테스트하세요

Memory Keeper가 작동하지 않는 경우:

# 서버를 제거하고 다시 추가하세요
claude mcp remove memory-keeper
claude mcp add memory-keeper npx mcp-memory-keeper
...

npx 설치 방식을 사용하면 매번 자동으로 최신 버전을 가져옵니다! 수동 업데이트가 필요 없습니다.

글로벌(global) 설치 방식을 사용하는 경우:

# 최신 버전으로 업데이트
npm update -g mcp-memory-keeper
# 새로운 Claude 세션 시작
...

참고: 업데이트 후에는 Claude에서 MCP 서버를 다시 설정할 필요가 없습니다. 그냥 새로운 세션을 시작하세요!

// 새로운 세션 시작
mcp_context_session_start({
name: 'Feature Development',
...

채널(Channels)은 세션 충돌이나 재시작 후에도 유지되는 지속적인 주제 기반의 조직화 기능을 제공합니다:

// 채널은 (projectDir이 설정된 경우) git 브랜치로부터 자동 유도됩니다
// 브랜치 "feature/auth-system"은 채널 "feature-auth-system"이 됩니다 (최대 20자)
// 특정 채널에 저장
...

// 카테고리 및 우선순위와 함께 저장
mcp_context_save({
key: 'current_task',
...

// 변경 감지를 위해 파일 내용 캐싱
mcp_context_cache_file({
filePath: '/src/auth/user.model.ts',
...

// 1. 새로운 세션 시작
mcp_context_session_start({
name: 'Settings Refactor',
...

나중에 복구할 수 있는 전체 컨텍스트(context)의 이름이 지정된 스냅샷(snapshots)을 생성하세요:

// 주요 변경 사항 전 체크포인트 생성
mcp_context_checkpoint({
name: 'before-refactor',
...

저장된 컨텍스트에 대해 AI 친화적인 요약(summaries)을 가져오세요:

저장된 모든 컨텍스트에 대한 요약(summaries)을 가져오세요:

// 모든 컨텍스트의 요약 가져오기
mcp_context_summarize();
// 특정 카테고리의 요약 가져오기
...

요약 출력 예시:

# 컨텍스트 요약 (Context Summary)
## 우선순위 높은 항목 (High Priority Items)
- **main_task**: Settings.Context를 behaviors를 사용하도록 리팩터링 (Refactor Settings.Context to use behaviors)
...

여러 작업을 원자적(atomically)으로 수행하세요:

// 여러 항목을 한 번에 저장
mcp_context_batch_save({
items: [
...

채널 간에 컨텍스트 항목을 재구성하세요:

// 항목을 새로운 채널로 이동
mcp_context_reassign_channel({
keyPattern: 'auth_*',
...

관련 항목들의 그래프(graph)를 구축하세요:

// 관련 항목 연결
mcp_context_link({
sourceKey: 'epic_user_management',
...

컨텍스트 변경 사항을 감시(watch)하세요:

// 와처(watcher) 생성
const watcher = await mcp_context_watch({
action: 'create',
...

Claude의 컨텍스트 윈도우(window)가 가득 찰 때 중요한 컨텍스트를 절대 잃어버리지 마세요:

// 컨텍스트 윈도우가 가득 차기 전에
mcp_context_prepare_compaction();
// 이 작업은 자동으로 다음을 수행합니다:
...

프로젝트 디렉토리의 git 변경 사항을 추적하고 커밋(commits)과 함께 컨텍스트를 저장하세요:

// 먼저, 프로젝트 디렉토리를 설정하세요 (세션 시작 시 설정하지 않은 경우)
mcp_context_set_project_dir({
projectDir: '/path/to/your/project',
...

저장된 컨텍스트에서 무엇이든 찾아보세요:

// 키(keys)와 값(values)에서 검색
mcp_context_search({ query: 'authentication' });
// 키에서만 검색
...

컨텍스트를 공유하거나 작업 내용을 백업하세요:

// 현재 세션 내보내기
mcp_context_export(); // memory-keeper-export-xxx.json 파일을 생성합니다
// 특정 세션 내보내기
...

컨텍스트에서 엔티티(entities)와 관계(relationships)를 자동으로 추출하세요:

// 지식 그래프(knowledge graph) 구축을 위해 컨텍스트 분석
mcp_context_analyze();
// 또는 특정 카테고리 분석
...

자연어 쿼리(natural language queries)를 사용하여 컨텍스트를 찾으세요:

// 자연어로 검색
mcp_context_semantic_search({
query: 'how are we handling user authentication?',
...

복잡한 분석 작업을 전문 에이전트(specialized agents)에게 위임하세요:

// 컨텍스트의 패턴 분석
mcp_context_delegate({
taskType: 'analyze',
...

에이전트 유형 (Agent Types):

Analyzer Agent (분석 에이전트): 패턴을 감지하고, 관계를 분석하며, 트렌드를 추적합니다.
Synthesizer Agent (합성 에이전트): 요약을 생성하고, 통찰을 병합하며, 권장 사항을 생성합니다.

기존 작업물을 잃지 않고 대안을 탐색하세요:

// 새로운 시도를 위한 브랜치 생성
mcp_context_branch_session({
branchName: 'experimental-refactor',
...

타임스탬프가 찍힌 저널 항목으로 생각과 진행 상황을 기록하세요:

// 저널 항목 추가
mcp_context_journal_entry({
entry: '인증 모듈을 완료했습니다. 테스트를 통과했습니다!',
...

시간에 따른 작업 패턴을 시각화하세요:

// 활동 타임라인 가져오기
mcp_context_timeline({
startDate: '2024-01-01',
...

오래된 컨텍스트 (Context)를 지능적으로 압축하여 공간을 절약하세요:

// 30일보다 오래된 항목 압축
mcp_context_compress({
olderThan: '2024-01-01',
...

다른 MCP 도구로부터 발생하는 이벤트를 추적하세요:

// 다른 도구의 이벤트 기록
mcp_context_integrate_tool({
toolName: 'code-analyzer',
...