재개 및 에이전트 인수인계

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

이 실용적인 워크플로는 개발자와 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를 사용하여 핸드오프 전에 현재 작업과 활성 블로커를 기록합니다:

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을 사용하여 핸드오프 전에 전체 세션 연속성 패키지를 캡처합니다:

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

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

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

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를 참조하십시오.