Claude Code 세션은 stateless다. 세션이 끝나면 프로젝트에 대해 학습한 모든 것이 사라진다. 이 문제를 해결하기 위해 MCP 서버를 직접 만들어 npm에 배포했다.
이 글은 claude-session-continuity-mcp의 제작 배경, 동작 원리, 실제 효과를 다루는 글이다. MCP 개념은 이전 글을 참고한다.
1. 문제: 컨텍스트 손실의 실제 비용
매일 아침 Claude Code를 열면 이런 작업을 반복한다:
| 순서 | 작업 | 소요 시간 |
|---|---|---|
| 1 | 모노레포 구조 설명 (28개 앱) | 1분 |
| 2 | 공유 라이브러리 구조 설명 | 30초 |
| 3 | DB 스키마 재설명 | 1분 |
| 4 | 어제 해결한 버그 언급 | 1분 |
| 5 | 실제 작업 시작 | - |
하루 5～10번 세션 × 5분 = 매일 25～50분의 순수 낭비다. 한 달이면 약 13시간이다.
핵심: Claude Code 세션은 stateless다. 세션이 끝나면 프로젝트에 대해 학습한 모든 것이 사라진다. 컨텍스트를 이어가는 메커니즘이 없다.
2. 해결: claude-session-continuity-mcp
Claude Code에 세션 간 영구 메모리를 제공하는 MCP 서버다. Claude Hooks를 통해 완전 자동으로 동작한다.
npm install claude-session-continuity-mcp이것으로 끝이다. postinstall 스크립트가 MCP 서버 등록과 5개 Claude Hooks 설치를 자동 처리한다.
| 항목 | 값 |
|---|---|
| npm 패키지 | claude-session-continuity-mcp |
| 버전 | 1.13.0 |
| MCP 도구 수 | 25개 (7개 카테고리) |
| 테스트 | 111개 (6개 스위트) |
| 호환 | Claude Code, Gemini CLI, VS Code Copilot, Codex CLI |
3. 동작 원리: 5-Hook 아키텍처
Claude Code의 Hook 시스템으로 라이프사이클 이벤트를 인터셉트한다.
| 구분 | CLAUDE.md | Hooks |
|---|---|---|
| 실행 보장 | 약 80% (권고) | 100% (강제) |
| 형태 | 마크다운 | 셸 스크립트 |
5개 Hook 상세
SessionStart — Claude Code를 열면 프로젝트 컨텍스트를 자동 로드한다. 기술 스택, 최근 결정, 활성 태스크, 관련 메모리를 가져온다.
UserPromptSubmit — 프롬프트 처리 전에 관련 메모리를 검색해 자동 주입한다. "인증 어떻게 처리했었지?"라고 물으면 과거 결정과 솔루션이 자동으로 들어간다.
PostToolUse — 모든 도구 호출 후 작업 중인 파일을 추적한다. Bash 명령이 실패하면 이전에 해결한 에러인지 확인하고 솔루션을 자동 주입한다.
PreCompact — 컨텍스트 압축 전에 구조화된 핸드오버 요약을 저장한다.
Stop — Claude 응답 완료 시 git 커밋, 아키텍처 결정, 에러-해결 쌍을 추출한다.
4. 메모리 분류 시스템
모든 정보를 기억하면 잡음이 된다. 5가지 유형으로 분류해 품질을 유지한다.
| 유형 | 설명 | 보존 기간 |
|---|---|---|
| Observations | 자동 추적된 관찰 | 3일 (자동 삭제) |
| Decisions | 아키텍처와 설계 결정 | 영구 |
| Learnings | 개발 중 발견한 패턴 | 영구 |
| Errors | 에러 메시지와 해결 방법 | 영구 |
| Patterns | 반복되는 코드 패턴 | 14일 (자동 정리) |
위반 사례
// 모든 파일 변경을 메모리로 저장
// → "[File Change] src/app.ts" 같은 잡음이 쌓임개선안
// 결정, 학습, 에러만 분류해서 저장
// → "MVI를 MVVM 대신 선택. 이유: 채팅 화면 상태 관리 복잡성"
5. 지식 그래프
개별 메모리는 유용하다. 연결된 메모리는 강력하다.
타입된 관계로 메모리를 연결한다: causes, solves, depends_on, contradicts, extends, example_of.
에러를 검색하면 에러만 반환하는 게 아니다. 그것을 해결한 솔루션, 발생시킨 아키텍처 결정, 방지하는 패턴까지 함께 반환한다.
6. 에러→솔루션 파이프라인
실무에서 가장 시간을 절약하는 기능이다.
| 단계 | 동작 | 역할 |
|---|---|---|
| 1 | Bash 명령 실패 | PostToolUse Hook이 에러 캡처 |
| 2 | 에러 해결 | Stop Hook이 해결책 캡처 |
| 3 | 에러-솔루션 쌍 저장 | SQLite에 영구 보존 |
| 4 | 같은 에러 재발생 | 솔루션 자동 주입 |
다음에 같은 에러가 발생하면 — 이번 세션이든 미래 세션이든 — 솔루션이 자동 주입된다.
7. 기술 스택
| 구성 요소 | 기술 |
|---|---|
| 런타임 | TypeScript + Node.js 18+ |
| 프로토콜 | @modelcontextprotocol/sdk (stdio) |
| DB | SQLite (better-sqlite3) + WAL + FTS5 |
| 임베딩 | @xenova/transformers (multilingual-e5-small, 384d) |
| 검증 | Zod 스키마 |
| 테스트 | Vitest (111개, 6개 스위트) |
성능: 컨텍스트 로드 5ms 미만, FTS 검색 ~10ms, 시맨틱 검색 ~50ms.
8. 결과
| 항목 | Before | After |
|---|---|---|
| 컨텍스트 설정 | 5분/세션 | 0초 (자동) |
| 에러 재해결 | 매번 재디버깅 | 자동 주입 |
| 결정 보존 | 세션 종료 시 소멸 | 영구 보존 |
| 월간 절약 | - | 약 13시간 |
정리
- Claude Code 세션은 stateless다. 컨텍스트가 매번 사라진다
- 5개 Claude Hooks로 컨텍스트 캡처/복원을 완전 자동화했다
- 메모리를 5가지로 분류해 품질을 유지한다
- 지식 그래프로 메모리 간 관계를 연결한다
- 에러→솔루션 파이프라인으로 같은 에러를 두 번 디버깅하지 않는다
- 월간 약 13시간의 생산성을 회복했다
관련 링크
- MCP 개념과 설정 가이드: https://leesmemo.tistory.com/69
- TypeScript MCP 서버 npm 배포: https://leesmemo.tistory.com/71
- Claude Code Hooks 자동화: https://leesmemo.tistory.com/72
참고 자료
'AI관련' 카테고리의 다른 글
| Claude Code in Action 후기 (1) | 2026.04.04 |
|---|---|
| 자기학습하는 macOS 자동화 MCP 배포 (0) | 2026.03.25 |
| Claude Code Hooks로 AI 개발 자동화하기 (0) | 2026.03.22 |
| TypeScript MCP 서버를 npm에 배포하기 (0) | 2026.03.22 |
| MCP 서버 직접 만들기: Python FastMCP (0) | 2026.01.29 |