Codex

사전 요구 사항

Streamable HTTP MCP 및 Skill 실행 지원이 포함된 OpenAI Codex CLI 또는 Codex Desktop을 사용하세요:

• 구체적인 인터페이스: Codex CLI 및 Codex Desktop (codex).
• 런타임 요구 사항: 독립형 Skill 러너를 위한 Node.js 버전 22.22.0 이상.
• 계정: https://xmemo.dev 의 유효한 XMemo 계정.
• MCP 사전 요구 사항: ~/.codex/config.toml 에서 bearer_token_env_var 지원.

설치 / 설정

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

• 프롬프트: 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.
• 기본 설치 경로: ~/.codex/skills/xmemo-memory.
• 대체 경로: bearer_token_env_var 를 사용하여 ~/.codex/config.toml 에서 직접 MCP 프로필을 구성합니다.

자격 증명 설정

작업을 실행하기 전에 자격 증명을 구성하세요. Codex를 시작하는 데 사용되는 환경에서 XMEMO_KEY 를 설정합니다. bearer_token_env_var 는 config.toml 에 토큰을 넣지 않고 값을 읽습니다. --allow-plaintext 옵션으로 대화형 기기 로그인을 사용하는 경우 이 플래그는 이 컴퓨터에 암호화되지 않은 자격 증명을 저장함에 유의하세요:

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

XMEMO_AGENT_INSTANCE_ID 생성 / 확인

클라이언트 구성은 이 설치에 대한 안정적인 인스턴스 ID를 매핑합니다. env_http_headers 가 XMEMO_AGENT_INSTANCE_ID 를 매핑하는지 확인하고 세션 전반에서 동일한 비기밀 값을 재사용합니다.

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

기존 구성 블록 유지

검토된 Codex 구성 블록을 사용하세요. bearer_token_env_var 및 XMemo URL을 유지하고, config.toml 에 비밀을 직접 붙여넣지 마세요:

[mcp_servers.xmemo]
url = "https://xmemo.dev/mcp"
bearer_token_env_var = "XMEMO_KEY"

클라이언트 다시 시작

구성 파일을 작성하거나 환경 변수를 수정하거나 Skill을 설치한 후 Codex를 다시 시작하여 새 구성 요소를 감지하도록 합니다.

실제 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. 상태 비저장 전환: 세션 간 지속성을 확인하기 위해 새로운 Codex 터미널 세션을 엽니다.
• 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 도구).

기능 및 프로필 도구

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

• 핵심 메모리 도구: remember, recall, update_memory, forget, read_memory, explain_memory, search_memory, recall_context.
• 작업 공간 도구: get_mcp_identity, get_project_summary, project, todo, open_project_workspace, open_todo_board, ledger, open_ledger.

제한 사항 및 경계

Codex의 운영 경계 및 제약 조건:

• 작업 공간 격리: 작업은 로그인한 사용자의 작업 공간으로 엄격히 제한됩니다.
• 비밀 처리: 항상 bearer_token_env_var 를 사용하세요. config.toml 에 토큰을 하드코딩하지 마세요.
• 배포 범위: Codex의 비표준 또는 서드파티 포크는 테스트되지 않음으로 표시됩니다.

일반적인 오류

다음 복구 단계를 사용하여 일반적인 Codex 문제를 해결하세요:

• 401 invalid_token — XMEMO_KEY 가 누락되었거나 만료되었거나 유효하지 않습니다: Codex를 실행하는 환경을 확인하고 다시 시작하세요.
• 403 insufficient_scope — 토큰에 memory:read 권한이 없습니다: 필요한 범위를 가진 토큰을 생성하세요.
• 잘못된 설치 대상 — XMEMO_SKILL_DIR 이 ~/.codex/skills/xmemo-memory 로 설정되었는지 확인하세요.
• Skill 다시 로드 필요 — 인메모리 스킬이 다시 로드되도록 Codex를 다시 시작하세요.

업데이트 및 제거

Codex 유지 관리 절차:

• 업데이트: 설치 관리자 명령을 다시 실행하여 최신 Skill 릴리스를 가져오거나 MCP 엔드포인트 URL을 업데이트하세요.
• 제거: ~/.codex/skills/xmemo-memory 디렉터리를 삭제하거나 ~/.codex/config.toml 에서 [mcp_servers.xmemo] 를 제거하세요.