Claude Code

사전 요구 사항

로컬 터미널에서 Claude Code CLI (claude)를 사용하세요. 런타임 및 사전 요구 사항:

• 구체적인 인터페이스: Claude Code CLI (claude).
• 런타임 요구 사항: 독립형 Skill 러너를 위한 Node.js 버전 22.22.0 이상.
• 계정: https://xmemo.dev 의 유효한 XMemo 계정.
• 대체 MCP 사전 요구 사항: 로컬 환경에서 베어러 토큰을 사용하는 Streamable HTTP 전송 지원.

설치 / 설정

권장 경로는 소유자가 선택한 프롬프트를 사용하여 Claude Code의 skills 디렉터리에 독립형 XMemo Skill을 설치하는 것입니다. Claude Code의 에이전트에게 설치 실행을 요청하세요:

• 프롬프트: Install the standalone XMemo Skill into your skills directory: run the installer from https://xmemo.dev/skill/install (on Windows, https://xmemo.dev/skill/install.ps1) with XMEMO_SKILL_DIR set to your skills directory plus /xmemo-memory. Run the doctor command it prints to verify the installation, then reload your skills and follow the Skill's first-run steps. Follow your normal safety checks and do not use elevated privileges.
• 기본 설치 경로: ~/.claude/skills/xmemo-memory.
• 대체 경로: claude mcp add 또는 .mcp.json 을 통해 https://xmemo.dev/mcp 로 직접 Streamable HTTP MCP를 등록합니다.

자격 증명 설정

명령을 실행하기 전에 자격 증명 저장 경로를 구성하세요. 보안 저장소 또는 로컬 셸 환경에서 XMEMO_KEY 를 설정하는 것이 좋습니다. --allow-plaintext 옵션으로 대화형 기기 로그인을 사용하는 경우 이 플래그는 이 컴퓨터에 암호화되지 않은 자격 증명을 저장함에 유의하세요:

export XMEMO_KEY='<your-xmemo-token>'
# Interactive alternative (stores credential unencrypted on this machine):
# node ~/.claude/skills/xmemo-memory/scripts/xmemo-skill.mjs login --allow-plaintext

XMEMO_AGENT_INSTANCE_ID 생성 / 확인

로컬 Claude Code 설치당 하나의 비기밀 값을 생성하고, git 외부에 유지하며, 세션 전반에서 재사용하여 인스턴스 귀속이 안정적으로 유지되도록 합니다.

export XMEMO_AGENT_INSTANCE_ID='<stable-local-instance-id>'
# Persist and reuse this value for the same local install

기존 구성 블록 유지

직접 MCP 환경의 경우 검토된 Claude Code 구성 블록을 사용하세요. Authorization 변수 참조를 유지하고, 토큰 자리 표시자를 실제 비밀로 바꾸지 마세요:

{
  "mcpServers": {
    "xmemo": {
      "type": "http",
      "url": "https://xmemo.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${XMEMO_KEY}"
      }
    }
  }
}

클라이언트 다시 시작

환경 변수, 구성 파일을 변경하거나 Skill을 설치한 후 Claude Code를 다시 시작하여 모든 구성 요소가 메모리에 완전히 로드되도록 합니다.

실제 recall 호출로 테스트

데이터를 쓰기 전에 연결을 확인하기 위해 첫 번째 요청을 읽기 전용으로 만듭니다. 이 검사는 메모리 상태를 수정하지 않습니다.

recall({ query: "connection check", limit: 1 })

예상 응답(리터럴 형태)

성공적인 호출은 아래의 공개 순위 텍스트 형식을 반환합니다. 참조 및 콘텐츠는 승인된 메모리 공간의 실제 값입니다.

### XMemo Memory Results:
1. Reference: <opaque-memory-id> | Location: <location>
   > <memory content>

첫 번째 유용한 작업: 합성 메모리 수명 주기

메모리 지속성, 상태 비저장 세션 전환, 출처 귀속 리콜 및 수정을 확인합니다:

• 1. 합성 사실 저장: node scripts/xmemo-skill.mjs remember --content "Demo project timestamps use UTC." --path "projects/demo-onboarding/conventions" (또는 MCP remember 도구).
• 2. 상태 비저장 전환: 세션 간 지속성을 확인하기 위해 새로운 Claude Code 터미널 세션을 엽니다.
• 3. 출처 귀속 리콜: node scripts/xmemo-skill.mjs recall --query "demo project timestamp format" (또는 MCP recall 도구). 반환된 출력에서 Reference 및 Location 을 확인합니다.
• 4. 메모리 수정: node scripts/xmemo-skill.mjs update --id <active-memory-id> --content "Demo project timestamps use UTC with ISO 8601 formatting." (또는 MCP update_memory 도구).
• 5. 선택적 정리: node scripts/xmemo-skill.mjs forget --id <active-memory-id> --confirm (또는 MCP forget 도구).

기능 및 프로필 도구

Claude Code는 claude-plugin 및 claude-public 프로필에 대한 MCP 문서 계약에 정의된 프로필 한정 도구에 액세스할 수 있습니다:

• 핵심 메모리 도구: remember, recall, update_memory, forget, read_memory, explain_memory, search_memory, recall_context.
• 프로젝트 및 컨텍스트 도구: get_mcp_identity, get_project_context, project, todo, update_state.
• 세션 연속성: create_restart_snapshot, restore_restart_snapshot, record_event, create_pending_decision, resolve_decision.

제한 사항 및 경계

Claude Code의 운영 경계 및 제약 조건:

• 작업 공간 경계: 메모리 접근은 승인된 사용자의 작업 공간으로 엄격히 제한됩니다.
• 데스크톱 분리: Claude Code CLI 구성은 Claude Desktop Cowork 설정과 독립적입니다.
• claude.ai의 Claude 및 Claude Desktop: 사용자 지정 커넥터와 OAuth로 연결합니다. [Claude (claude.ai)](/docs/mcp/claude)를 참조하세요.
• 비밀 처리: 일반 텍스트 토큰을 git에 커밋하거나 체크인된 구성 파일에 비밀을 붙여넣지 마세요.

일반적인 오류

다음 단계를 통해 일반적인 연결 및 인증 문제를 해결하세요:

• 401 invalid_token — XMEMO_KEY 가 누락되었거나 만료되었거나 유효하지 않습니다: 환경 토큰을 확인하거나 기기 로그인을 다시 실행하세요.
• 403 insufficient_scope — 토큰에 memory:read 또는 memory:write 범위가 없습니다: 필요한 권한을 가진 토큰을 발급하세요.
• 잘못된 설치 대상 — XMEMO_SKILL_DIR 이 ~/.claude/skills/xmemo-memory 로 설정되었는지 확인하세요.
• Skill 다시 로드 필요 — Claude Code를 종료(/exit)하고 다시 시작하여 인메모리 스킬을 다시 로드하세요.

업데이트 및 제거

연동 업데이트 또는 제거 절차:

• 업데이트: 최신 Skill 패키지 릴리스를 가져오기 위해 설치 관리자 프롬프트를 다시 실행하세요.
• 제거: ~/.claude/skills/xmemo-memory 를 삭제하거나 claude mcp remove xmemo 를 실행하여 직접 MCP 구성을 제거하세요.