MCP를 사용하여 Claude Code에 세션 간 지속적인 메모리 부여하는 방법

모든 Claude Code 세션은 기억상실증과 함께 시작됩니다. 당신은 아키텍처를 설명합니다. 결정을 다시 설명합니다. 인증 계층(auth layer)이 왜 그런 모습인지 다시 설명합니다. 모델은 고개를 끄덕이며 작업을 수행하지만, 다음 세션에서는 그 모든 것을 잊어버립니다.

이것은 모델의 문제가 아닙니다. 저장(storage)의 문제입니다. 컨텍스트 윈도우(context window)가 초기화되며, 다음 세션이 읽을 수 있는 지속적인 정보가 아무것도 없습니다.

저는 이 문제를 해결하는 MCP 서버를 구축했습니다. Nucleus라고 불리는 이 서버는 모든 MCP 호환 AI 클라이언트(Claude Code, Cursor, Windsurf, Gemini)에 공유된 지속적 메모리 계층을 제공합니다.

스크린샷 한 장으로 보는 문제점

세션 1의 작업을 이어가기 위해 세션 2를 엽니다. 세션 2는 세션 1에 대해 들어본 적이 없습니다. 당신은 세션 1이 이미 알고 있었던 내용을 다시 설명하는 데 10분을 소비합니다.

이를 모든 세션, 매일, 모든 프로젝트에 곱해보십시오. 그것이 바로 컨텍스트 드리프트 세금(context-drift tax)입니다.

Nucleus가 하는 일

Nucleus는 지속적인 메모리를 쓰고 쿼리(query)하기 위한 소수의 도구 세트를 노출하는 MCP 서버입니다:

brain_write_engram — 키(key), 값(value), 컨텍스트 태그(context tag), 강도 점수(intensity score)와 함께 결정, 아키텍처 노트 또는 모든 지식을 저장합니다.
brain_query_engrams — 부분 문자열(substring), 컨텍스트 또는 최소 강도에 따라 저장된 지식을 검색합니다.
brain_audit_log — 신뢰 검증을 위해 암호화된 상호작용 로그를 확인합니다.
brain_governance_status — 브레인의 보안 및 컴플라이언스(compliance) 상태를 확인합니다.

모든 데이터는 로컬 .brain/ 디렉토리에 추가 전용(append-only) JSONL 파일로 저장됩니다. 클라우드도 없고, 벤더 종속(vendor lock-in)도 없습니다. 당신의 메모리는 당신의 기기에 머뭅니다.

60초 만에 설치하기

pip install nucleus-mcp
nucleus-init --scan

끝입니다. nucleus-init은 .brain/ 디렉토리를 생성하고, 초기 컨텍스트를 심기 위해 프로젝트의 README.md를 스캔하며, 당신의 MCP 클라이언트(Claude Desktop, Cursor, Windsurf)를 자동 구성합니다.

Claude Code를 재시작하면 도구들을 사용할 수 있습니다.

Claude Code에서 사용하기

설치 후, 모든 Claude Code 세션은 공유된 브레인(brain)에 쓰고 읽을 수 있습니다:

# 세션 1 — 인증 아키텍처를 결정하는 중
"Use brain_write_engram to store: key='auth_architecture', value='Using OAuth 2.1 with PKCE. Refresh tokens in httpOnly cookies. No server-side sessions.' context='Architecture' intensity=8"

...

세션 2에서는 사용자가 다시 설명할 필요 없이 세션 1에서의 결정 사항을 다시 가져옵니다. 이 엔그램 (engram)은 세션 간, 도구 간, 그리고 ( .brain/ 디렉토리를 동기화한다면) 기기 간에도 지속됩니다.

이것이 중요한 이유

컨텍스트 윈도우 (context window)는 메모리가 아닙니다. 그것은 단기 기억 (short-term recall)입니다. 진정한 메모리는 윈도우가 초기화될 때도 지속되어야 합니다.

모든 AI 코딩 도구는 이 문제를 가지고 있습니다. Claude Code, Cursor, Windsurf, Gemini CLI — 이들은 모두 컨텍스트가 전혀 없는 상태로 각 세션을 시작합니다. 모델은 동일하고, 기능도 동일합니다. 하지만 어제 당신이 결정한 것에 대한 _지식 (knowledge)_은 사라집니다.

Nucleus는 그 지식을 내구성 있게 만듭니다. 모든 AI 도구에서 공유되며 세션 간에도 유지되는 하나의 .brain/ 디렉토리를 제공합니다.

멀티 에이전트 조정 (Multi-agent coordination)

만약 당신이 여러 AI 에이전트를 실행한다면 (예: Claude Code + Cursor, 또는 코드베이스의 서로 다른 부분에서 실행되는 두 개의 Claude Code 세션), Nucleus는 이들에게 공유된 메모리를 제공합니다. 에이전트 A가 결정을 기록하면, 에이전트 B가 이를 읽습니다. 메시지 큐도, 오케스트레이션 프레임워크 (orchestration framework)도 필요 없습니다. 그저 공유된 파일 하나면 충분합니다.

동기화 도구들이 멀티 머신 조정을 처리합니다:

brain_sync_now — 수동으로 동기화 트리거
brain_sync_status — 동기화 상태 및 충돌 확인
brain_identify_agent — 귀속(attribution)을 위해 에이전트의 신원 등록

보안 모델

Nucleus는 OS 수준의 파일 보호를 제공하는 하이퍼바이저 (hypervisor) 서브시스템을 갖추고 있습니다:

lock_resource — 수정을 방지하기 위해 파일/폴더를 잠금 (macOS에서 BSD chflags uchg 사용)
watch_resource — 승인되지 않은 변경 사항에 대해 파일/폴더 모니터링
set_hypervisor_mode — 시각적 컨텍스트 전환 (red/blue/reset)

모든 작업은 SHA-256 해싱을 사용하여 변조 방지 기능이 있는 감사 로그 (audit log)에 기록됩니다. brain_audit_log 도구를 통해 상호작용 기록의 무결성을 검증할 수 있습니다.

PyPI에 있는 것 vs 전체 서버에 있는 것

PyPI에 공개된 nucleus-mcp 패키지에는 8개의 도구(메모리 + 거버넌스 + 하이퍼바이저)가 포함되어 있습니다. relay.nucleusos.dev에서 제공되는 전체 호스팅 서버에는 릴레이 조정 (relay coordination), 비용 라우팅 (cost routing), 멀티 테넌트 지원 (multi-tenant support)을 포함하여 17개의 도구가 있습니다.

로컬 우선 (local-first) 사용의 경우, PyPI 패키지만으로도 충분합니다. 호스팅 서버는 팀 단위의 사용 및 대규모 멀티 에이전트 조정 (multi-agent coordination)을 위한 것입니다.

사용해 보기

pip install nucleus-mcp
nucleus-init --scan

그 다음 Claude Code를 재시작하고 결정 사항을 저장하도록 요청하세요. 해당 내용이 .brain/engrams/ledger.jsonl에 지속적으로 저장되는 것을 확인할 수 있습니다. 새로운 세션을 열고 이를 다시 쿼리해 보세요. 이것이 핵심입니다.

PyPI: nucleus-mcp
GitHub: eidetic-works/nucleus-mcp
Docs: eidetic.works

공개적으로 빌드하고 있습니다. MCP 서버는 오픈 소스입니다. 호스팅되는 조정 계층 (coordination layer)이 비즈니스 모델입니다. AI 에이전트를 진지하게 운영하고 있다면, 이것이 바로 당신에게 부족한 메모리 계층 (memory layer)입니다.