# Claude Code

독립형 XMemo Skill을 권장 경로로 사용하고, 지원되는 대안으로 직접 MCP를 사용하여 Claude Code를 연결합니다.

- Canonical: https://docs.xmemo.dev/ko/docs/mcp/claude-code
- Locale: ko-KR
- Content-Locale: ko-KR
- Canonical-Content-Digest: 5edeeceeddc0cef8d2d6e339fda7faaccf26ce601200bc11845b78bb698132cd
- Edition-Digest: dbc60e242784035adc9838ecadea277ce349042083c9851817ba1f6aec98c407
- Source-Revision: sha256:288082ef3586e3b1f3c2f1a2efb1500c46b876aa3b4c51604bd280c04fc27027

## 사전 요구 사항

로컬 터미널에서 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 옵션으로 대화형 기기 로그인을 사용하는 경우 이 플래그는 이 컴퓨터에 암호화되지 않은 자격 증명을 저장함에 유의하세요:

```bash
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 외부에 유지하며, 세션 전반에서 재사용하여 인스턴스 귀속이 안정적으로 유지되도록 합니다.

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

## 기존 구성 블록 유지

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

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

## 클라이언트 다시 시작

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

## 실제 recall 호출로 테스트

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

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

## 예상 응답(리터럴 형태)

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

```text
### 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 구성을 제거하세요.

## Claude Desktop

Stdio bridge: Claude Desktop uses mcp-remote to connect to hosted streamable-http with XMEMO_KEY from the environment. Run npx @xmemo/client mcp add claude-desktop to configure automatically.

```
{
  "mcpServers": {
    "XMemo": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://xmemo.dev/mcp",
        "--header",
        "Authorization:Bearer ${XMEMO_KEY}",
        "--header",
        "X-Memory-OS-Agent-ID:claude-desktop",
        "--header",
        "X-Memory-OS-Agent-Instance-ID:${XMEMO_AGENT_INSTANCE_ID}"
      ],
      "env": {
        "XMEMO_AGENT_INSTANCE_ID": "${XMEMO_AGENT_INSTANCE_ID}"
      }
    }
  }
}
```