# Retomada e transferência de agentes Capture pontos de verificação de sessão explícitos, recupere o contexto do projeto, acompanhe decisões e bloqueios com fontes, e transfira o trabalho entre agentes sem desvios de escopo. - Canonical: https://docs.xmemo.dev/pt-br/docs/guides/resume-and-handoff - Locale: pt-BR - Content-Locale: pt-BR - Canonical-Content-Digest: f7f1e02f35c3c797c1b7fcc4aee1048fa1f409ef7ed79ecaf362c4d2d5f7b15a - Edition-Digest: 189f6ae00db7bcd31a343ab06e0887e80c46fa69617dbfcc946f384c4861ecfa - Source-Revision: sha256:dacab21c9fc471e388ff6bbe4a84e7266ffca6eed88baebabcf7f68ee9957d6a ## 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: ```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 ``` ## 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: ```bash 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: ```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 ``` ## 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. ## Usuário do ChatGPT Dê ao ChatGPT acesso duradouro às suas preferências do XMemo, fatos do projeto, decisões e TODOs sem colar tokens bearer no chat. Conecte o servidor MCP hospedado do XMemo pelo fluxo OAuth do app ChatGPT/OpenAI e aprove a concessão memory:read e memory:write para sua conta do XMemo. Salve uma preferência de teste ou anotação de projeto, inicie um novo chat e peça ao ChatGPT para recuperá-la via XMemo antes de prosseguir. Se o OAuth falhar ou as ferramentas não aparecerem, saia do servidor MCP no app host, reconecte a URL do servidor XMemo e tente novamente antes de criar tokens diretos. ## Desenvolvedor Copilot / Codex Transfira decisões do repositório, convenções de código, notas de correção de bugs e histórico de tarefas entre agentes de IDE e CLI. Use OAuth para VS Code / GitHub Copilot e Gemini CLI quando disponível. Para Copilot CLI, Codex, Cursor ou outros clientes MCP diretos, mantenha XMEMO_KEY no ambiente local ou cofre de segredos e defina um XMEMO_AGENT_INSTANCE_ID estável. Registre uma decisão da base de código ou correção de bug e peça ao próximo agente de IDE ou CLI para recuperar o contexto relevante do XMemo antes de editar. Se as recuperações estiverem vazias, verifique o caminho da configuração MCP selecionada, a variável de ambiente XMEMO_KEY para clientes diretos e eventuais credenciais OAuth desatualizadas no app host. ## Líder de piloto de equipe / corporativo Avalie a memória compartilhada com controles de conta, atribuição de origem, fluxos de exportação/exclusão e evidências de configuração seguras para revisores. Crie ou acesse o espaço de trabalho protegido do XMemo, convide usuários aprovados e conecte cada cliente via OAuth ou credencial direta com escopo de acordo com os selos de disponibilidade. Peça para um membro do piloto salvar uma memória de equipe de teste, confirme a atribuição de origem no XMemo e revise os caminhos de exclusão/exportação e suporte. Se um membro não conseguir se conectar, verifique as permissões de função, aprovação OAuth, status de prontidão do cliente e orientações de suporte antes de emitir um novo token. ## Operador de agentes autônomos Permita que agentes headless ou agendados registrem progresso, recuperem decisões anteriores e mantenham uma identidade estável e não secreta de instância. Obtenha /api/v1/mcp/config/autonomous-agent. Prefira auth_modes.oauth quando o executor suportar OAuth + cabeçalhos personalizados; use auth_modes.xmemo_key com XMEMO_KEY de um cofre de segredos apenas para executores totalmente headless. Execute uma tarefa de teste que grave progresso no XMemo, reinicie o executor e confirme se ele recupera esse progresso usando o mesmo XMEMO_AGENT_INSTANCE_ID. Se a atribuição mudar ou as recuperações se dividirem entre instâncias, persista XMEMO_AGENT_INSTANCE_ID fora do git e verifique se o executor não o está gerando a cada início.