# 재개 및 에이전트 인수인계

명시적인 세션 체크포인트를 캡처하고, 프로젝트 컨텍스트를 복구하며, 출처와 함께 결정 및 블로커를 추적하고, 범위 확장 없이 에이전트 간에 작업을 인수인계합니다.

- Canonical: https://docs.xmemo.dev/ko/docs/guides/resume-and-handoff
- Locale: ko-KR
- Content-Locale: ko-KR
- Canonical-Content-Digest: f7f1e02f35c3c797c1b7fcc4aee1048fa1f409ef7ed79ecaf362c4d2d5f7b15a
- Edition-Digest: 1455aa4ebb4ca207aab81a71ce4e5f68a3f7cfba0a916cfc5e6ea544ac53557a
- Source-Revision: sha256:dacab21c9fc471e388ff6bbe4a84e7266ffca6eed88baebabcf7f68ee9957d6a

## 사용자 목표 및 워크플로 경계

이 실용적인 워크플로는 개발자와 AI 에이전트가 중단된 세션을 재개하고, CLI/IDE 재시작 전반에 걸쳐 활성 컨텍스트를 복구하며, 아키텍처 결정, 활성 블로커 또는 작업 연속성을 잃지 않고 서로 다른 에이전트(Claude Code, Codex, Cursor, Hermes 등) 간에 진행 중인 작업을 인수인계할 수 있도록 지원합니다. 이 워크플로는 제한 없는 대화 기록을 덤프하거나 자격 증명을 유출하지 않고 컨텍스트 핸드오프가 범위가 지정된 구조화된 상태를 전송하도록 보장합니다.

## 이용 가능성 및 사전 요구 사항

재개 및 핸드오프에 필요한 기능은 명시적인 권한 경계를 갖춘 독립형 XMemo Skill 및 기본 MCP 클라이언트 프로필 전반에서 제공됩니다:

- 독립형 Skill(Claude Code, Codex, OpenClaw): 제공되는 1.1.35 help.mjs의 축자 CLI 명령어: save-state 및 restore-state(88-95줄), restart-snapshot 및 restart-restore(104-111줄), recall-context(84-87줄), remember(72-75줄), todo-add/list/done(112-123줄).
- MCP claude-plugin 프로필: update_state, create_restart_snapshot, restore_restart_snapshot, record_event, recall_context, remember, recall, todo, create_pending_decision 및 resolve_decision을 포함합니다.
- MCP cursor-plugin 및 ordinary-full 프로필: update_state, create_restart_snapshot, restore_restart_snapshot, record_event, recall_context, remember, recall, update_project_decision, update_project_todo, list_memory_todos, complete_memory_todo 및 query_audit을 포함합니다.
- MCP generic-public, chatgpt-public 및 public-only 프로필: get_project_summary(project_id, focus) 및 memory_overview와 같은 읽기 전용 요약 프로젝션을 노출합니다. 쓰기 도구에는 인증된 플러그인 세션이 필요합니다.
- 사전 요구 사항: 체크포인트 지속성을 위한 memory:write 범위 및 컨텍스트 검색을 위한 memory:read 범위를 가진 활성 인증 토큰(XMEMO_KEY 또는 로컬 skill-credentials.json).

## 단일 완료 작업: 합성 멀티 에이전트 핸드오프

이 합성 시나리오에서 Agent Alpha(Claude Code CLI에서 실행)는 proj_payments_v2 프로젝트의 데이터베이스 연결 풀링 리팩터링 작업을 수행하고, 명시적인 결정과 블로커를 기록하며, 재시작 스냅샷(restart snapshot)을 봉인한 다음 Agent Beta(Cursor IDE에서 실행)에게 실행을 인수인계합니다.

## 활성 상태 및 블로커 캡처

Agent Alpha는 save-state 또는 update_state를 사용하여 핸드오프 전에 현재 작업과 활성 블로커를 기록합니다:

```bash
node scripts/xmemo-skill.mjs save-state --key active_task --content "Refactoring database connection pooling to asyncpg: blocked on internal CA bundle" --ttl_seconds 86400
```

## 연속성을 위한 재시작 스냅샷 생성

Agent Alpha는 restart-snapshot 또는 create_restart_snapshot을 사용하여 핸드오프 전에 전체 세션 연속성 패키지를 캡처합니다:

```bash
node scripts/xmemo-skill.mjs restart-snapshot --state_key active_task --session_id sess_alpha_0928 --ttl_seconds 604800
```

## 수신 에이전트 세션에서 재개 및 복원

Agent Beta는 Cursor IDE에서 시작하여 스냅샷을 복원하고 범위가 지정된 백그라운드 컨텍스트를 검색합니다:

```bash
node scripts/xmemo-skill.mjs restart-restore --source_session_id sess_alpha_0928 --target_session_id sess_beta_0929
node scripts/xmemo-skill.mjs recall-context --query "internal CA bundle TLS root pin database pooling" --max_items 5 --max_tokens 2000
```

## 관찰 가능한 결과

성공적인 핸드오프는 대화형 수식어 없이 도구 응답에서 명시적이고 검증 가능한 확인을 생성합니다:

- 스냅샷 생성 출력: create_restart_snapshot은 "✅ Restart snapshot created. ID: snap_xxx Captured: state=1, events=1, reminders=0, decisions=1"을 반환합니다.
- 복원 영수증: restore_restart_snapshot은 활성 상태 슬롯을 복원하고, target_session_id 아래에 감사 복원 이벤트를 기록하며, 복원된 정확한 상태 콘텐츠 및 블로커 이유를 반환합니다.
- 컨텍스트 기반: recall_context는 소스 session_id, agent_id 및 정확한 생성 타임스탬프로 태그가 지정된 구조화된 메모리 항목을 반환하여 Agent Beta가 결정 소스를 즉시 확인할 수 있도록 합니다.

## 에이전트가 액세스할 수 있는 항목

세션 간 컨텍스트 액세스는 승인된 범위와 출처에 의해 엄격하게 제한됩니다:

- 제한된 메모리 컨텍스트: 복원하는 에이전트는 쿼리와 일치하는 구조화된 상태 슬롯, 타임라인 마일스톤 및 명시적으로 검색된 메모리를 수신하며, 관련 없는 개발자 메모리나 관련 없는 프로젝트는 수신하지 않습니다.
- 자체 쓰기 읽기 일관성(Read-Your-Writes): 상태 업데이트 및 재시작 스냅샷은 트랜잭션 메타데이터 저장소에 즉시 기록되어 핸드오프 에이전트 간의 최종 일관성 경쟁 조건을 방지합니다.
- 호출자 출처: 검색된 컨텍스트에는 호출자 ID(source_identity, agent_id 및 node_id)가 포함되므로 후속 에이전트가 인간 사용자의 지시와 자동화된 동료 에이전트 제안을 구별할 수 있습니다.

## 공유 및 스토리지 경계

모든 재개 및 핸드오프 작업에는 엄격한 개인정보 보호 및 보안 격리 규칙이 적용됩니다:

- 원시 대화 내용 덤프 금지: 전체 채팅 기록이나 모델 사고 추적을 상태나 메모리에 절대 저장하지 마십시오. 핸드오프는 구조화된 상태 요약, 명시적 결정 이벤트 및 검증된 사실만을 전송합니다.
- 자격 증명 유출 제로: 토큰, API 키, 비밀번호 및 권한 부여 헤더를 state_key, content 또는 metadata_json에 절대 기록해서는 안 됩니다.
- 프로젝트 격리 경계: project:proj_payments_v2에 바인딩된 스냅샷은 명시적인 팀 권한 없이 다른 프로젝트 또는 개인 범위에서 인증된 세션에서 절대 액세스할 수 없습니다.

## 오류 복구

결정론적 대체 전략을 사용하여 일반적인 재개 및 핸드오프 오류를 처리합니다:

- 만료된 스냅샷 또는 TTL: 스냅샷이 ttl_seconds(스냅샷의 경우 기본 7일, 활성 상태의 경우 24시간)를 초과하면 restore_restart_snapshot이 스냅샷 만료를 보고합니다. get_project_context(project_id="proj_payments_v2") 또는 프로젝트 범위 쿼리를 사용하는 recall_context로 대체하십시오.
- 세션 ID 누락: source_session_id를 사용할 수 없거나 분실한 경우 node scripts/xmemo-skill.mjs restore-state --key active_task를 사용하여 최신 상태 레코드를 복구하거나 todo-list를 사용하여 활성 TODO를 나열하십시오.
- 범위 또는 테넌트 불일치: 에이전트가 승인되지 않은 테넌트 또는 일치하지 않는 프로젝트 범위에서 스냅샷 복원을 시도하면 서버는 HTTP 403 Forbidden으로 요청을 거부합니다. 클라이언트 구성에서 바인딩된 프로젝트 ID를 확인하십시오.

## 관련 참조

관련 아키텍처, 범위 정의 및 도구 카탈로그에 대해서는 다음 가이드를 참조하십시오:

- 교차 에이전트 워크플로: 오케스트레이션 개념은 /docs/operations/cross-agent-workflow를 참조하십시오.
- 범위 및 격리: 4계층 직교 범위 계층은 /docs/concepts/scopes를 참조하십시오.
- 프로젝트 워크스페이스: 프로젝트 연결 및 경계 적용은 /docs/concepts/projects를 참조하십시오.
- 빠른 시작: 클라이언트 구성 및 초기 인증은 /docs/quickstart를 참조하십시오.
- MCP 도구 참조: 하위 수준 도구 매개변수는 /docs/tools/recall-context 및 /docs/tools/remember를 참조하십시오.

## ChatGPT 사용자

채팅에 전달자 토큰을 붙여넣지 않고도 XMemo 기본 설정, 프로젝트 사실, 결정 및 TODO에 대한 지속 가능한 액세스를 ChatGPT에 부여하세요.

ChatGPT/OpenAI 앱 OAuth 흐름을 통해 호스팅된 XMemo MCP 서버를 연결한 다음 XMemo 계정에 대한 메모리:읽기 및 메모리:쓰기 권한을 승인합니다.

종합 기본 설정이나 프로젝트 노트를 저장하고 새 채팅을 시작한 다음 작업을 계속하기 전에 XMemo를 통해 ChatGPT에 이를 불러오도록 요청하세요.

OAuth가 실패하거나 도구가 표시되지 않으면 호스트 앱의 MCP 서버에서 로그아웃하고 XMemo 서버 URL을 다시 연결한 후 직접 토큰을 생성하기 전에 다시 시도하세요.

## 부조종사/Codex 개발자

IDE와 CLI 에이전트 간에 리포지토리 결정, 코딩 규칙, 버그 수정 메모, 작업 기록을 전달합니다.

가능한 경우 VS Code / GitHub Copilot 및 Gemini CLI에 OAuth를 사용하세요. Copilot CLI, Codex, Cursor 또는 기타 직접 MCP 클라이언트의 경우 로컬 환경 또는 보안 저장소에 XMEMO_KEY를 유지하고 안정적인 XMEMO_AGENT_INSTANCE_ID를 설정하세요.

코드베이스 결정이나 버그 수정을 기록한 후 편집하기 전에 다음 IDE 또는 CLI 에이전트에게 관련 XMemo 컨텍스트를 기억하도록 요청하세요.

회수가 비어 있는 경우 선택한 MCP 구성 경로, 직접 클라이언트용 XMEMO_KEY 환경 변수 및 호스트 앱의 오래된 OAuth 자격 증명을 확인하세요.

## 팀/엔터프라이즈 파일럿 소유자

계정 제어, 소스 속성, 내보내기/삭제 워크플로, 검토자에게 안전한 설정 증거를 통해 공유 메모리를 평가합니다.

보호된 XMemo 작업 공간을 생성하거나 입력하고 승인된 사용자를 초대한 다음 준비 배지에 따라 OAuth 또는 범위가 지정된 직접 자격 증명을 통해 각 클라이언트를 연결합니다.

파일럿 멤버에게 가상 팀 메모리를 저장하고 XMemo에서 소스 속성을 확인한 다음 삭제/내보내기 및 지원 경로를 검토하도록 합니다.

구성원이 연결할 수 없는 경우 새 토큰을 발급하기 전에 역할 권한, OAuth 승인, 클라이언트 준비 상태 및 지원 지침을 확인하세요.

## 자율 에이전트 운영자

헤드리스 또는 예약 에이전트가 진행 상황을 기록하고, 이전 결정을 검색하고, 안정적이고 비밀이 아닌 인스턴스 ID를 유지하도록 합니다.

/api/v1/mcp/config/autonomous-agent를 가져옵니다. 실행기가 OAuth + 사용자 정의 헤더를 지원하는 경우 auth_modes.oauth를 선호합니다. 완전 헤드리스 러너에 대해서만 비밀 저장소의 XMEMO_KEY와 함께 auth_modes.xmemo_key를 사용하십시오.

XMemo에 진행 상황을 기록하는 하나의 합성 작업을 실행하고 실행기를 다시 시작한 다음 동일한 XMEMO_AGENT_INSTANCE_ID를 사용하여 해당 진행 상황을 호출하는지 확인합니다.

속성이 변경되거나 인스턴스 간에 분할된 경우 git 외부에서 XMEMO_AGENT_INSTANCE_ID를 유지하고 실행기가 시작할 때마다 이를 다시 생성하지 않는지 확인하세요.