Claude Historian MCP — 사용 사례, 설치 & 라이브 데모

왜 쓰나요

핵심 기능

두 가지 도구: '검색'(11개 범위) 및 '검사'(세션 요약)
~/.claude/conversations/에서 읽기 - 외부 서비스 없음
TF-IDF + 워크플로 패턴 감지를 통한 퍼지 매칭
병렬 프로젝트 스캔; 유지할 영구 인덱스가 없습니다.
짧은 접두사 세션 ID 지원

라이브 데모

실제 사용 모습

claude-historian-mcp.replay ▶ 준비됨

0/0

설치

클라이언트 선택

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "claude-historian-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "claude-historian-mcp"
      ]
    }
  }
}

Claude Desktop → Settings → Developer → Edit Config 열기. 저장 후 앱 재시작.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "claude-historian-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "claude-historian-mcp"
      ]
    }
  }
}

Cursor는 Claude Desktop과 동일한 mcpServers 스키마 사용. 프로젝트 설정이 전역보다 우선.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "claude-historian-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "claude-historian-mcp"
      ]
    }
  }
}

Cline 사이드바의 MCP Servers 아이콘 클릭 후 "Edit Configuration" 선택.

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "claude-historian-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "claude-historian-mcp"
      ]
    }
  }
}

Claude Desktop과 같은 형식. Windsurf 재시작 후 적용.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "claude-historian-mcp",
      "command": "npx",
      "args": [
        "-y",
        "claude-historian-mcp"
      ]
    }
  ]
}

Continue는 맵이 아닌 서버 오브젝트 배열 사용.

~/.config/zed/settings.json

{
  "context_servers": {
    "claude-historian-mcp": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "claude-historian-mcp"
        ]
      }
    }
  }
}

context_servers에 추가. 저장 시 Zed가 핫 리로드.

claude mcp add claude-historian-mcp -- npx -y claude-historian-mcp

한 줄 명령. claude mcp list로 확인, claude mcp remove로 제거.

사용 사례

실전 활용법: Claude Historian

이전에 비슷한 버그를 수정한 방법을 찾아보세요.

👤 여러 세션에서 Claude Code를 사용하는 개발자 ⏱ ~5 min beginner

언제 쓸까: 익숙한 오류가 발생했습니다. 지난번에 어떤 일이 이루어졌는지 보고 싶습니다.

사전 조건

기존 대화 기록이 있는 클로드 코드 — 기본값 — 기록은 ~/.claude/conversations/에 있습니다.

흐름

검색 오류

내 기록에서 'ECONNREFUSED redis' 검색 — 범위: 오류.✓ 복사됨

→ 해당 오류가 발생한 이전 세션의 순위 목록
최고의 히트를 검사

세션 abc12345 검사 — 수정 사항은 무엇이었나요?✓ 복사됨

→ 요약에는 근본 원인과 적용된 수정 사항이 나와 있습니다.

결과: 처음부터 다시 디버그하는 것이 아니라 몇 초 만에 구체적인 선례를 만들 수 있습니다.

함정

세션을 읽지 않고 요약을 신뢰함 — 요약을 위해 검사를 사용한 다음 실제 차이점을 위해 세션 파일을 엽니다.

함께 쓰기: filesystem

과거 구현 계획을 가져와 재사용

👤 클로드와 함께 자주 업무를 계획하시는 분 ⏱ ~10 min beginner

언제 쓸까: 새로운 기능은 몇 달 전에 계획한 것과 비슷해 보입니다. 뼈대를 다시 원합니다.

흐름

플랜 검색

검색 범위: '지수 백오프를 사용한 백그라운드 작업 재시도'에 대한 계획입니다.✓ 복사됨

→ 조회수에는 계획 제목과 세션 ID가 포함됩니다.
검사 및 조정

최고 히트를 검사합니다. 계획을 요약하고 Postgres 지원 대기열에 맞게 조정합니다.✓ 복사됨

→ 원본과 동일한 구조로 수정된 계획

결과: 발판을 다시 생성하지 않고 사고를 재사용합니다.

함께 쓰기: codebase-memory

과거 컨텍스트를 사용하여 새 세션을 웜 스타트합니다.

👤 헤비 클로드 코드 사용자 ⏱ ~10 min intermediate

언제 쓸까: 이전 프로젝트에서 새로운 채팅을 시작하고 컨텍스트를 다시 설명하고 싶지 않습니다.

흐름

프로젝트 언급 검색

검색 범위: 'acme-api billing' 세션, 프로젝트별 그룹.✓ 복사됨

→ 해당 프로젝트와 가장 관련성이 높은 3~5개 세션
수화 검사

세션 7f3e2a10을 검사합니다. 아키텍처 결정 및 알려진 버그를 요약합니다.✓ 복사됨

→ 새 세션의 기초가 되는 명확한 요약

결과: 마지막으로 유용한 세션이 중단된 지점부터 새 세션이 시작됩니다.

함정

한 번에 너무 많은 세션을 로드하고 상황에 빠져들다 — 점수 기준으로 상위 5위까지 올라갑니다. 가장 좋은 것에만 검사를 사용하세요

함께 쓰기: memory-bank-mcp

조합

다른 MCP와 조합해 10배 효율

claude-historian-mcp + filesystem

검사 후 실제 차이점에 대한 참조 파일을 엽니다.

세션 X를 검사합니다. 그런 다음 언급된 파일을 열고 관련 부분을 표시합니다.✓ 복사됨

claude-historian-mcp + memory-bank-mcp

일회성 수정을 내구성 있는 메모리로 승격

세션 X의 수정 사항은 부하를 견디는 것으로 보입니다. memory-bank/<project>/bugs.md에 추가하세요.✓ 복사됨

claude-historian-mcp + codebase-memory

코드 그래프에서 역사가의 텍스트 조회수를 접지합니다.

세션 X가 fn retryBilling에 닿습니다. 코드베이스 메모리를 통해 현재 발신자를 보여줍니다.✓ 복사됨

도구

이 MCP가 노출하는 것

도구	입력	언제 호출	비용
search	query: str, scope: one-of (conversations\|errors\|plans\|config\|tasks\|sessions\|tools\|similar\|memories\|…), limit?: int	현재 작업과 관련된 이전 대화 찾기	0
inspect	session_id: str (full UUID or short prefix)	사람이 읽을 수 있는 단일 세션 요약을 가져옵니다.	0

비용 및 제한

운영 비용

API 쿼터: 없음 — 로컬 파일 검사
호출당 토큰: 결과 크기에 따라 다릅니다. 제한이 있는 모자
금액: 무료
팁: '대화' 대신 좁은 범위(오류, 계획)를 사용하여 응답을 작게 유지하세요.

보안

권한, 시크릿, 파급범위

자격 증명 저장: 자격 증명이 없습니다. 로컬 파일에서만 작동합니다.

데이터 외부 송신: 당신의 기계에는 아무것도 남지 않습니다. MCP 서버는 ~/.claude/conversations/만 읽습니다.

대화 기록에는 이전에 붙여넣은 비밀이 포함될 수 있습니다. 검색 결과를 공유하기 전에 수정하는 것은 귀하의 책임입니다.
공유 머신: 홈 디렉토리에 액세스할 수 있는 테넌트는 모든 이전 세션을 읽을 수 있습니다. ~/.ssh를 보호하는 것처럼 ~/.claude를 보호하십시오.

문제 해결

자주 발생하는 오류와 해결

대화가 존재한다는 것을 알면서도 결과가 없습니다.

범위='대화'를 시도하고 쿼리를 완화하세요. ~/.claude/conversations/가 비어 있지 않은지 확인하세요.

확인: ls ~/.claude/conversations/ | head

검사 결과 짧은 접두사에 대한 세션을 찾을 수 없다고 표시됨

다른 세션은 동일한 접두사로 시작됩니다. 더 많은 문자를 사용하세요.

확인: Grep session IDs: grep -r -l '<prefix>' ~/.claude/conversations/

매우 큰 기록에서는 속도가 느림

더 좁은 범위와 한계를 통과하십시오. 이 도구는 요청 시 검색하므로 대규모 기록의 경우 쿼리당 비용이 더 많이 듭니다.

확인: du -sh ~/.claude/conversations/

대안

Claude Historian 다른 것과 비교

대안	언제 쓰나	단점/장점
memory-bank-mcp	원시 기록 검색보다는 선별된 프로젝트 범위의 메모리를 원합니다.	채워져야 합니다. 자유 형식 검색이 아님
codebase-memory	대화 검색이 아닌 코드의 기호 그래프를 원합니다.	다른 레이어
filesystem	차라리 직접 대화를 나누는 편이 낫습니다.	채점, 퍼지 매칭, 세션 요약 손실

Claude Historian