Claude Code Substrate Memory

claude-code-substrate-memory는 Claude Code를 Substrate 조직 메모리에 연결합니다. 이 플러그인은 메모리 읽기/쓰기를 위한 7개의 MCP 도구를 제공하고, Claude Code 수명주기 훅을 통해 새 트랜스크립트 턴을 캡처하며, 실패한 전달을 제한된 로컬 스풀에 보관합니다.

버전 0.1.0은 런타임에 Python 표준 라이브러리만 사용합니다.

설치

저장소를 클론하고 Claude Code 플러그인으로 로드합니다:

git clone https://github.com/Substrate-memory/claude-code-substrate-memory.git
claude --plugin-dir /absolute/path/to/claude-code-substrate-memory

개발 또는 직접 CLI 사용을 위해 패키지를 Python 3.11+ 환경에 설치합니다:

python -m pip install -e .
substrate-claude-code status

플러그인 매니페스트는 MCP 서버, 수명주기 훅, 슬래시 명령을 제공합니다. MCP 서버는 src/가 PYTHONPATH에 있을 때 python -m claude_code_memory.server로 직접 실행할 수도 있습니다.

Related MCP server: Claude Memory MCP Server

구성

자격 증명은 환경 변수로만 받습니다:

SUBSTRATE_API_URL=https://your-substrate-server.example
SUBSTRATE_API_KEY=your-profile-scoped-bearer-key

Claude Code를 실행하는 환경에 설정하세요. SUBSTRATE_API_KEY를 .mcp.json, hooks/hooks.json, 프로젝트 설정 파일 또는 다른 일반 텍스트 구성 파일에 절대 작성하지 마세요. substrate-claude-code configure를 실행하면 비밀을 기록하지 않고 필요한 연결 구성을 출력합니다.

변수가 없거나 API에 일시적으로 연결할 수 없는 경우에도 캡처는 계속 활성화되며 새 이벤트는 ~/.substrate/claude_code_memory/ 아래의 로컬 스풀에 배치됩니다. SUBSTRATE_STATE_HOME을 설정하여 상태 루트를 옮길 수 있으며, 이는 격리된 테스트에 특히 유용합니다. 사이드체인 캡처는 기본적으로 활성화되어 있습니다. SUBSTRATE_CAPTURE_SIDECHAINS=0을 설정하여 비상 제외 킬 스위치를 사용하세요.

MCP 도구

저장소에는 /substrate-status 및 /substrate-recall 슬래시 명령도 추가되어 있습니다.

훅 캡처

Claude Code는 hooks/hooks.json에서 네 개의 명령 훅을 호출합니다:

• Stop은 이전에 체크포인트되지 않은 정규화된 사용자, 어시스턴트, 도구 호출, 도구 결과 및 시스템 블록을 캡처하고 turn 이벤트를 내보냅니다.

• PreCompact는 Claude Code가 컨텍스트를 압축하기 전에 pre_compress와 동일한 증분 트랜스크립트 창을 캡처합니다.

• SessionEnd는 정규화된 메시지 수와 세션 경계만 포함하는 콘텐츠 없는 session_end 이벤트를 내보냅니다. 영구 마커는 이 이벤트가 최대 한 번만 내보내지도록 보장합니다.

• SessionStart는 제한된 Substrate 검색을 수행하고 관련 메모리를 사용할 수 있을 때 간결한 Markdown 회상 블록을 출력합니다.

각 훅은 새 프로세스이므로 세션별 메시지 다이제스트와 일회성 마커는 플러그인 상태 디렉터리 아래에 유지됩니다. 캡처 이벤트는 네트워크 전달 전에 내구성 있게 스풀됩니다.

개인정보 보호 경계

트랜스크립트 판독기는 최상위 및 사이드체인 user, assistant, system 레코드를 캡처합니다. 사이드체인 레코드는 레코드/블록 좌표와 세션 계보를 전달합니다. 도구 호출과 결과는 tool_call_id로 짝지어진 별도의 텍스트 전용 메시지입니다. 짝지어진 결과는 도구 이름을 받고, 고아 또는 모호한 결과는 이유 코드를 받고 소스 식별자는 없습니다.

캡처된 모든 블록에 대해 65,536바이트 UTF-8 상한 전에 전체 자격 증명 감지가 실행됩니다. 인식된 자격 증명이 블록의 어디에든 나타나면 전체 블록이 콘텐츠 없음이 됩니다. 이렇게 하면 비밀이 이전 잘림 경계에서 잘리는 것을 방지합니다. 바이너리 및 미디어 본문, 숨겨진 추론, 토큰 사용량, 청구 필드 및 임의의 공급자 메타데이터는 캡처되지 않습니다.

공유 캡처 코어는 지속 및 전송 전에 인식된 비밀을 편집합니다. 편집은 심층 방어이지 임의의 민감한 산문이 없다는 증거는 아닙니다. 표시되는 프롬프트와 어시스턴트 출력 자체에 기밀 자료가 포함될 수 있으므로 신뢰할 수 있는 Substrate 서버만 구성하고 해당 서버의 액세스 및 보존 정책을 검토하세요. 실패한 전달은 제한된 소유자 전용 로컬 스풀에 남습니다. 스풀은 경계 이벤트를 위한 용량을 예약하고 압력이 가해지면 오래된 증거를 축출하는 대신 최신 이벤트를 거부합니다. substrate-claude-code status는 콘텐츠를 노출하지 않고 영구적인 evicted, quarantined, dropped, duplicates 카운터를 표시합니다.

실패 시 열림 동작

훅은 항상 상태 0으로 종료됩니다. API 실패, 잘못된 형식의 훅 입력, 읽을 수 없거나 잘린 트랜스크립트, 손상된 로컬 상태 및 회상 실패는 Claude Code 세션을 차단하거나 주석을 달지 않습니다. 일반 캡처 훅은 stdout에 아무것도 쓰지 않습니다. 선택적 진단은 SUBSTRATE_DEBUG가 설정된 경우에만 stderr로 전달됩니다. 세션 시작 회상은 유일한 의도적인 훅 출력입니다.

저장소 구조

• src/claude_code_memory/ — Claude Code 런타임, 트랜스크립트 판독기, 훅, 회상, MCP 서버 및 CLI.

• src/substrate_capture/ — 모든 호스트 플러그인에서 사용하는 고정된 공유 캡처 코어.

• .claude-plugin/ — 플러그인 및 자체 등록 마켓플레이스 메타데이터.

• .mcp.json — stdio MCP 서버 등록.

• hooks/hooks.json — Claude Code 수명주기 훅 등록.

• commands/ — /substrate-status 및 /substrate-recall 명령 프롬프트.

• tests/ — 합성 픽스처를 사용한 공유 코어 및 Claude Code 호스트 계약 테스트.

• scripts/ — 공유 코어 출처 및 게시 검증 도구.

개발

python -m pip install -e '.[dev]'
python -m pytest tests/ -q
ruff check .

src/substrate_capture/를 직접 편집하지 마세요. 해당 다이제스트는 호스트 저장소 전체에서 공유되며 테스트 스위트로 검증됩니다.

라이선스

MIT © 2026 Sightline Technologies Inc. LICENSE를 참조하세요.