Retomada e transferência de agentes

Objetivo do usuário e limites do fluxo de trabalho

Este fluxo de trabalho prático permite que desenvolvedores e agentes de IA retomem sessões interrompidas, recuperem o contexto ativo após reinicializações de CLI/IDE e transfiram o trabalho em andamento entre diferentes agentes (como Claude Code, Codex, Cursor ou Hermes) sem perder decisões arquiteturais, bloqueios ativos ou continuidade de tarefas. O fluxo de trabalho garante que as transferências de contexto transmitam um estado estruturado e delimitado, em vez de despejar históricos irrestritos de conversas ou vazar credenciais.

Disponibilidade e pré-requisitos

Os recursos necessários para retomada e transferência estão disponíveis por meio da Skill XMemo autônoma e de perfis de cliente MCP nativos com limites explícitos de permissão:

• Skill autônoma (Claude Code, Codex, OpenClaw): comandos textuais da versão 1.1.35 servida de help.mjs: save-state e restore-state (linhas 88-95), restart-snapshot e restart-restore (linhas 104-111), recall-context (linhas 84-87), remember (linhas 72-75) e todo-add/list/done (linhas 112-123).
• Perfil MCP claude-plugin: inclui update_state, create_restart_snapshot, restore_restart_snapshot, record_event, recall_context, remember, recall, todo, create_pending_decision e resolve_decision.
• Perfis MCP cursor-plugin e ordinary-full: incluem 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 e query_audit.
• Perfis MCP generic-public, chatgpt-public e public-only: expõem projeções resumidas somente leitura como get_project_summary(project_id, focus) e memory_overview; ferramentas de gravação exigem uma sessão de plugin autenticada.
• Pré-requisitos: token de autenticação ativo (XMEMO_KEY ou arquivo local skill-credentials.json) com escopo memory:write para persistência de pontos de verificação e memory:read para recuperação contextual.

Uma tarefa completa: transferência sintética multiagente

Neste cenário sintético, o Agente Alpha (executado no Claude Code CLI) trabalha na refatoração do pool de conexões do banco de dados no projeto proj_payments_v2, registra uma decisão explícita e um bloqueio, sela um instantâneo de reinicialização (restart snapshot) e transfere a execução para o Agente Beta (executado no Cursor IDE).

Capturar estado ativo e bloqueio

O Agente Alpha registra sua tarefa atual e o bloqueio ativo antes da transferência usando save-state ou 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

Criar instantâneo de reinicialização para continuidade

O Agente Alpha captura o pacote completo de continuidade da sessão antes da transferência usando restart-snapshot ou create_restart_snapshot:

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

Retomar e restaurar na sessão do agente receptor

O Agente Beta é iniciado no Cursor IDE, restaura o instantâneo e recupera o contexto de segundo plano delimitado:

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

Resultado observável

Uma transferência bem-sucedida produz uma confirmação explícita e verificável na resposta da ferramenta sem floreios conversacionais:

• Saída de criação de instantâneo: create_restart_snapshot retorna: "✅ Restart snapshot created. ID: snap_xxx Captured: state=1, events=1, reminders=0, decisions=1".
• Comprovante de restauração: restore_restart_snapshot restaura o slot de estado ativo, registra um evento de auditoria de restauração sob target_session_id e retorna o conteúdo exato do estado restaurado e o motivo do bloqueio.
• Fundamentação contextual: recall_context retorna itens de memória estruturados etiquetados com session_id de origem, agent_id e carimbos de data/hora de criação exatos, permitindo que o Agente Beta verifique imediatamente a origem da decisão.

O que os agentes podem acessar

O acesso ao contexto entre sessões é estritamente delimitado por escopos autorizados e procedência:

• Contexto de memória delimitado: agentes restauradores recebem slots de estado estruturados, marcos de linha do tempo e memórias explicitamente recuperadas correspondentes à consulta; eles não recebem memórias de desenvolvedores irrelevantes nem projetos estranhos.
• Consistência de leitura após gravação (Read-Your-Writes): atualizações de estado e instantâneos de reinicialização são gravados imediatamente no armazenamento transacional de metadados, evitando condições de corrida de consistência eventual entre os agentes de transferência.
• Procedência do chamador: o contexto recuperado inclui a identidade do chamador (source_identity, agent_id e node_id) para que os agentes subsequentes possam distinguir instruções de usuários humanos de propostas automatizadas de agentes pares.

Limites de compartilhamento e armazenamento

Regras rígidas de privacidade e isolamento de segurança aplicam-se a todas as operações de retomada e transferência:

• Sem despejo de transcrições brutas: nunca armazene transcrições completas de conversas nem rastros de pensamento do modelo no estado ou na memória. A transferência transmite apenas resumos de estado estruturados, eventos de decisão explícitos e fatos verificados.
• Vazamento zero de credenciais: tokens, chaves de API, senhas e cabeçalhos de autorização nunca devem ser gravados em state_key, content ou metadata_json.
• Limite de isolamento de projeto: instantâneos vinculados a project:proj_payments_v2 são estritamente inacessíveis a sessões autenticadas em um projeto diferente ou escopo pessoal sem permissões explícitas de equipe.

Recuperação de falhas

Trate erros comuns de retomada e transferência usando estratégias de fallback determinísticas:

• Instantâneo expirado ou TTL: quando um instantâneo excede ttl_seconds (padrão de 7 dias para instantâneos, 24 horas para estado ativo), restore_restart_snapshot informa que o instantâneo expirou. Recorra a get_project_context(project_id="proj_payments_v2") ou recall_context com uma consulta delimitada ao projeto.
• ID de sessão ausente: se source_session_id estiver indisponível ou perdido, recupere o registro de estado mais recente usando node scripts/xmemo-skill.mjs restore-state --key active_task ou liste os TODOs ativos usando todo-list.
• Incompatibilidade de escopo ou locatário: se um agente tentar restaurar um instantâneo entre um locatário não autorizado ou escopo de projeto incompatível, o servidor rejeitará a solicitação com HTTP 403 Forbidden. Verifique o ID do projeto vinculado na configuração do seu cliente.

Referência relacionada

Para consultar a arquitetura relacionada, definições de escopo e catálogos de ferramentas, explore os seguintes guias:

• Fluxo de trabalho entre agentes: /docs/operations/cross-agent-workflow para conceitos de orquestração.
• Escopos e isolamento: /docs/concepts/scopes para a hierarquia ortogonal de 4 níveis de escopos.
• Espaços de trabalho de projetos: /docs/concepts/projects para associações de projetos e aplicação de limites.
• Início rápido: /docs/quickstart para configuração de clientes e autenticação inicial.
• Referência de ferramentas MCP: /docs/tools/recall-context e /docs/tools/remember para parâmetros de ferramentas de baixo nível.