빠른 시작

1. 클라이언트 및 인증 모드 선택

에이전트 클라이언트와 선호하는 연결 경로를 선택합니다. Claude Code, Codex 및 호환 에이전트의 경우 '에이전트에 요청'과 함께 독립형 Skill 설치 프로그램을 사용합니다. ChatGPT와 같이 스킬이 없는 클라이언트의 경우 OAuth를 통한 호스팅형 MCP를 사용합니다. Cursor 또는 VS Code와 같은 직접 실행 및 헤드리스 러너의 경우 XMEMO_KEY를 사용하는 Direct MCP를 사용합니다. 전용 클라이언트 가이드는 /docs/mcp/claude-code, /docs/mcp/codex, /docs/connect/openclaw, /docs/mcp/chatgpt, /docs/mcp/cursor 및 /docs/mcp/copilot에서 확인할 수 있습니다.

• 경로 1 (Skill): 에이전트에게 Claude Code, Codex 및 OpenClaw (/docs/connect/openclaw)용 독립형 XMemo Skill을 설치하도록 요청합니다.
• 경로 2 (OAuth MCP): ChatGPT (/docs/mcp/chatgpt) 및 Claude Desktop (/docs/mcp/overview)을 포함한 스킬이 없는 클라이언트를 위한 OAuth 기반 호스팅형 MCP.
• 경로 3 (Direct MCP): Cursor (/docs/mcp/cursor) 및 VS Code (/docs/mcp/copilot)용 로컬 환경의 ${XMEMO_KEY}를 참조하는 Direct Streamable HTTP MCP.
• 인증 모드: OAuth (권장, 브라우저 승인) 대 Direct MCP (환경 변수 XMEMO_KEY).
• 중간 상태: 클라이언트를 선택하고 구성을 복사하는 것은 중간 단계일 뿐이며 활성화가 아닙니다.

2. 토큰을 노출하지 않고 클라이언트 설정

독립형 Skill을 설치하거나 호스팅된 MCP 엔드포인트(https://xmemo.dev/mcp)를 사용하여 클라이언트를 구성합니다. Skill 클라이언트의 경우 기본 복사 작업으로 공식 설치 프롬프트를 에이전트에 제공하거나 표준 설치 프로그램을 수동으로 실행합니다. Direct MCP의 경우 로컬 환경 또는 시크릿 저장소에서 ${XMEMO_KEY}를 참조합니다. 일반 텍스트 베어러 토큰을 클라이언트 구성 파일이나 버전 제어에 하드코딩하지 마십시오.

• 경로 1 (에이전트에 요청): 독립형 XMemo Skill을 스킬 디렉터리에 설치합니다. XMEMO_SKILL_DIR을 스킬 디렉터리 + /xmemo-memory로 설정하고 https://xmemo.dev/skill/install (Windows의 경우 https://xmemo.dev/skill/install.ps1)에서 설치 프로그램을 실행합니다. 출력되는 doctor 명령을 실행하여 설치를 확인한 다음 스킬을 다시 로드하고 Skill의 첫 실행 단계를 따릅니다. 일반적인 보안 검사를 따르고 승격된 권한을 사용하지 마십시오.
• 수동 복사 대체: XMEMO_SKILL_DIR을 명시적으로 설정하고 'curl -fsSL https://xmemo.dev/skill/install | sh' (Windows PowerShell: 'irm https://xmemo.dev/skill/install.ps1 | iex')를 실행합니다.
• OAuth 클라이언트: https://xmemo.dev/mcp를 구성하고 브라우저에서 memory:read 및 memory:write를 승인합니다.
• Direct MCP: 구성에서 ${XMEMO_KEY}를 참조합니다. 실제 토큰은 로컬 환경이나 시크릿 저장소에 보관합니다.
• 시크릿 제로: 구성 파일에는 암호화되지 않은 베어러 토큰이 포함되어서는 안 됩니다.

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

3. 읽기 전용 검사로 연결 확인

데이터를 쓰기 전에 항상 읽기 전용 요청으로 연결을 확인하십시오. 설치, 인증 및 활성화는 서로 다른 마일스톤입니다. 독립형 Skill의 경우 설치 프로그램이 출력한 doctor 명령을 실행합니다. 로그인하기 전에 자격 증명 경로를 선택하십시오. 시크릿 저장소에서 XMEMO_KEY를 제공하거나 관리형 자격 증명을 사용하는 것이 좋습니다. --allow-plaintext를 사용하여 대화형 디바이스 로그인을 사용하는 경우 이 플래그는 이 컴퓨터에 암호화되지 않은 자격 증명을 저장합니다. 인증 후 상태를 확인합니다. MCP 클라이언트의 경우 get_mcp_identity는 클라이언트가 서버에 연결할 수 있고 memory:read 스코프가 유효한지 확인합니다.

• Skill doctor 명령: node scripts/xmemo-skill.mjs doctor --anonymous (런타임 및 연결 확인).
• Skill 자격 증명 대체 수단: 시크릿 저장소에서 XMEMO_KEY를 제공하거나 관리형 자격 증명을 사용합니다.
• Skill 디바이스 로그인: node scripts/xmemo-skill.mjs login --allow-plaintext (브라우저 확인을 엽니다. --allow-plaintext는 이 컴퓨터에 암호화되지 않은 자격 증명을 저장함에 유의하십시오).
• Skill 인증 확인: node scripts/xmemo-skill.mjs auth status --verify (자격 증명 유효성 확인).
• MCP 도구: get_mcp_identity() (또는 제한 1의 recall).
• 스코프 게이트: memory:read.
• 성공 신호: 식별 메타데이터가 서버에 연결 가능하고 승인되었음을 확인합니다.

get_mcp_identity()

4. 명시적인 합성 팩트 저장

memory:write에서 쓰기 기능을 확인하기 위해 합성 프로젝트 규칙을 기록합니다. 후속 쿼리가 프로젝트 범위 내에서 찾을 수 있도록 메모리에 특정 경로를 지정합니다. 통합 표면에 올바른 구문을 사용하십시오.

• Skill 명령: node scripts/xmemo-skill.mjs remember --content "Demo project timestamps use UTC." --path "projects/demo-onboarding/conventions".
• MCP 도구: 명시적인 합성 콘텐츠를 사용한 remember.
• 경로 범위: projects/demo-onboarding/conventions.
• 성공 신호: 영수증은 할당된 ID 및 Location과 함께 'Saved to XMemo.'로 시작합니다.

remember({
  content: "Demo project timestamps use UTC.",
  path: "projects/demo-onboarding/conventions"
})

5. 새로운 클라이언트 세션 열기

새 대화 스레드를 시작하거나 클라이언트를 다시 시작하여 임시 인메모리 컨텍스트를 지웁니다. 이 무상태 전환을 통해 다음 리콜 시 로컬 대화 기록 재생 대신 서버 측 지속성이 검증됩니다.

• 작업: 클라이언트에서 현재 대화 세션을 닫거나 재설정합니다.
• 컨텍스트 재설정: 무상태 테스트를 보장하기 위해 임시 클라이언트 컨텍스트가 지워집니다.
• 지속성 확인: 후속 리콜은 원격 저장소를 직접 쿼리합니다.

6. 소스 귀속과 함께 팩트 리콜

새 세션에서 저장된 규칙을 쿼리합니다. 활성화는 소스 귀속을 통한 첫 번째 검증된 메모리 리콜을 완료하는 것으로 엄격하게 정의됩니다. 구성을 복사하거나 스니펫을 검사하는 것은 중간 설정 단계일 뿐입니다.

• Skill 명령: node scripts/xmemo-skill.mjs recall --query "demo project timestamp format" --limit 1.
• MCP 도구: 'demo project timestamp format' 쿼리를 사용한 recall.
• 영수증 형식: Reference, Location, 선택적 Created/Updated/Revision 및 콘텐츠를 표시하는 '### XMemo Memory Results:'로 시작하는 텍스트 출력.
• 성공 신호: 소스 귀속을 통한 첫 번째 검증된 리콜이 진정한 활성화를 나타냅니다.

recall({
  query: "demo project timestamp format",
  limit: 1
})

7. update_memory로 규칙 수정

프로젝트 규칙이 발전하거나 설명이 필요한 경우 리콜에서 반환된 정확한 활성 메모리 ID 또는 Reference로 메모리를 업데이트합니다. Skill 클라이언트의 경우 update 명령을 사용합니다. MCP 클라이언트의 경우 update_memory를 사용합니다. 선택적 정리는 사용자가 forget을 통해 지시합니다.

• Skill 명령: node scripts/xmemo-skill.mjs update --id "mem_01hxyz..." --content "Demo project timestamps use UTC with ISO 8601 formatting.".
• MCP 도구: 유효한 memory_id를 사용한 update_memory.
• 개정 추적: 불변 기록을 보존하면서 이전 개정을 대체합니다.
• 선택적 정리: 삭제하려면 'node scripts/xmemo-skill.mjs forget --id mem_01hxyz... --confirm' (Skill)을 실행하거나 forget (MCP)을 호출하십시오.
• 성공 신호: 영수증은 Reference 및 Revision을 표시하는 'XMemo memory updated.'로 시작합니다.

update_memory({
  memory_id: "mem_01hxyz...",
  content: "Demo project timestamps use UTC with ISO 8601 formatting."
})

복구: 클립보드 접근 거부됨

브라우저에서 클립보드 액세스를 거부하거나 권한이 차단된 경우 코드 블록 내의 스니펫 텍스트를 수동으로 선택하고 Ctrl+C(또는 Cmd+C)로 복사하십시오. 모든 코드 블록은 키보드 스크롤 및 선택을 위해 tabIndex=0을 제공합니다.

• 증상: 브라우저가 자동 클립보드 복사를 차단하거나 권한 프롬프트가 실패합니다.
• 조치: 코드 컨테이너를 클릭하거나 탭하여 이동한 후 Ctrl+C 또는 Cmd+C를 사용하십시오.
• 확인: 붙여넣은 구성이 표시된 스니펫과 정확히 일치합니다.

복구: 인증 만료 또는 권한 부족

클라이언트가 HTTP 401 Unauthorized, HTTP 403 Forbidden 또는 SetupRequiredMCPError를 수신하는 경우 인증 토큰이 만료되었거나 필요한 스코프가 부족한 것입니다.

• 증상: 도구 호출 시 HTTP 401, HTTP 403 또는 SetupRequiredMCPError 발생.
• 조치: OAuth를 통해 다시 인증하거나 로컬 환경에서 XMEMO_KEY를 설정합니다.
• 확인: 토큰이 memory:read 및 memory:write 스코프를 모두 부여하는지 확인합니다.

복구: 클라이언트에 도구가 표시되지 않음

구성 후 클라이언트 팔레트에 XMemo 도구가 나타나지 않으면 구성 파일에 구문 오류가 있거나 MCP 연결 프로세스를 다시 시작해야 할 수 있습니다.

• 증상: 클라이언트에 0개의 도구가 표시되거나 XMemo MCP 서버를 인식하지 못합니다.
• 조치: 클라이언트 개발자 로그를 확인하고, JSON 구문의 유효성을 검사하고, 클라이언트를 다시 시작하십시오.
• 확인: 클라이언트 로그에 성공적인 MCP 초기화 및 도구 검색이 표시됩니다.

복구: 리콜 결과가 비어 있음

recall이 일치하는 메모리를 반환하지 않는 경우('No matching memories found' 또는 'No strong memory match') 4단계의 쓰기가 성공적으로 완료되었는지 확인하고 검색 쿼리를 확인하십시오.

• 증상: recall이 일치하는 메모리를 찾을 수 없음을 나타내는 텍스트 메시지를 반환합니다.
• 조치: 쿼리 키워드('timestamp', 'UTC')를 확인하고 경로 범위를 확인합니다.
• 확인: 리콜하기 전에 remember가 'Saved to XMemo'로 시작하는 영수증을 반환했는지 확인합니다.

복구: 업데이트 시 알 수 없는 메모리 ID

memory_id를 알 수 없거나 유효하지 않아 update_memory가 호출을 거부하는 경우 식별자를 임의로 추측하지 마십시오.

• 증상: update_memory에서 memory_id를 찾을 수 없다는 오류를 반환합니다.
• 조치: 먼저 recall을 호출하여 활성 메모리 Reference를 가져온 후 이를 memory_id로 전달합니다.
• 확인: recall의 활성 메모리 Reference를 update_memory에 전달합니다.

복구: 잘못된 설치 대상

설치 프로그램이 격리된 스킬 하위 디렉터리가 아닌 에이전트의 스킬 루트 디렉터리에 스크립트를 직접 저장한 경우 에이전트는 scripts/xmemo-skill.mjs를 찾을 수 없거나 원시 설치 파일을 로드합니다.

• 증상: scripts/xmemo-skill.mjs를 찾는 중 오류가 발생하거나 파일이 스킬 루트에 직접 추출됩니다.
• 조치: XMEMO_SKILL_DIR을 스킬 디렉터리 + /xmemo-memory로 명시적으로 설정합니다(예: export XMEMO_SKILL_DIR="$HOME/.claude/skills/xmemo-memory").
• 확인: SKILL.md 및 scripts/xmemo-skill.mjs가 xmemo-memory 폴더 바로 안에 있습니다.

복구: Node 22.22.0 런타임 누락

독립형 Skill에는 Node.js >= 22.22.0이 필요합니다. node가 없거나 이전 버전이 활성화되어 있으면 doctor 및 스킬 작업이 실패합니다.

• 증상: 'command not found: node', 시작 시 런타임 오류, 또는 node -v가 22.22.0 미만 버전을 보고합니다.
• 조치: nvm(nvm install 22.22.0 && nvm use 22.22.0) 또는 운영 체제 패키지 관리자를 사용하여 Node.js 22.22.0 이상을 설치하거나 전환합니다.
• 확인: 'node -v'를 실행하고 출력이 v22.22.0 이상인지 확인합니다.

복구: Skill 다시 로드 필요

Skill이 설치되고 doctor를 통과했음에도 에이전트의 활성 세션에 XMemo 도구나 작업이 나열되지 않으면 에이전트의 인메모리 스킬 캐시를 다시 로드해야 합니다.

• 증상: 설치 후 에이전트가 XMemo 스킬에 대한 지식이 없다고 보고합니다.
• 조치: 에이전트 세션을 다시 시작하여 인메모리 스킬을 다시 로드합니다.
• 확인: 에이전트에게 'what skills are available?'이라고 묻고 xmemo-memory가 나열되어 있는지 확인합니다.

복구: 중단된 로그인

디바이스 로그인이 중단되었거나 시간 초과되었거나 확인 코드를 입력하기 전에 닫힌 경우 자격 증명이 디스크에 기록되지 않습니다.

• 증상: 승인 전에 브라우저가 닫혔거나 일회용 코드가 만료되었거나 'auth status --verify'에서 auth_valid: false를 보고합니다.
• 조치: 시크릿 저장소 XMEMO_KEY나 관리형 자격 증명을 사용하지 않는 경우 'node scripts/xmemo-skill.mjs login --allow-plaintext'(이 컴퓨터에 자격 증명을 암호화되지 않은 상태로 저장함)를 다시 실행하고 표시된 URL을 열어 만료 전에 코드를 입력하십시오.
• 확인: 'node scripts/xmemo-skill.mjs auth status --verify'를 실행하고 'auth_valid: true'와 함께 'status: ok'를 확인합니다.