Session Handoff MCP

Session Handoff MCP preserva continuidade entre sessões de coding agents por meio de checkpoints locais, estruturados e legíveis. A V1 é focada exclusivamente no fluxo checkpoint → clear → resume entre Claude Code e Codex.

Estado atual: milestones 1–10 concluídos. O servidor MCP cobre criação, retomada e sincronização Git opcional, com integrações guiadas para Claude Code e Codex, exemplo público fictício e demonstração automatizada. O próximo milestone é o uso real por duas semanas antes da V2.

Requisitos

• Node.js 24 ou superior

• pnpm 10

• Git opcional apenas para o repositório privado de dados

Related MCP server: MCP Memory Keeper

Desenvolvimento

pnpm install
pnpm check
pnpm dev init --help

Demonstração

Para executar localmente o fluxo completo com dois clientes MCP independentes e storage temporário:

pnpm demo

A demonstração compila o servidor, cria um checkpoint como Claude Code, retoma como Codex, salva o estado atualizado e o retoma novamente como Claude Code. Ela funciona offline, não altera configurações pessoais e remove os dados temporários ao terminar.

O roteiro completo também descreve a validação manual nos clientes reais. O repositório fictício contém um checkpoint canônico que pode ser inspecionado sem expor dados privados.

Inicialização

pnpm build
pnpm dev init

Para automação:

session-handoff init \
  --non-interactive \
  --data-dir /caminho/para/agent-memory-data \
  --json

O comando cria a configuração e a pasta projects/, verifica permissões e detecta Git. Ele nunca executa git init. Um repositório Git pai é ignorado por padrão.

O servidor exige uma configuração válida antes de iniciar. O loader aceita somente caminhos absolutos ou iniciados por ~/, rejeita chaves YAML desconhecidas e valida data_repo_path/projects sem modificar o storage.

Overrides disponíveis:

SESSION_HANDOFF_CONFIG
SESSION_HANDOFF_DATA_REPO

Registro MCP

codex mcp add session-handoff -- session-handoff mcp
claude mcp add --transport stdio --scope user session-handoff -- session-handoff mcp

Para instalar a skill pessoal e os hooks opcionais de retomada automática, consulte integrations/claude-code/README.md. A instalação é manual e nunca substitui configurações existentes do Claude Code.

Para adicionar as instruções persistentes do workflow ao Codex, consulte integrations/codex/README.md. O escopo recomendado é global pessoal em ~/.codex/AGENTS.md.

Criando um checkpoint

Depois de registrar o servidor, o cliente MCP pode chamar memory_checkpoint com um snapshot completo:

{
  "project_key": "meu-projeto",
  "objective": "Entregar a funcionalidade atual.",
  "state_summary": "Implementação consolidada até este ponto.",
  "completed": ["Contrato principal implementado."],
  "decisions": [],
  "pending": ["Adicionar o teste de integração."],
  "next_step": "Implementar e executar o teste de integração.",
  "validation": [],
  "files_touched": ["src/example.ts"]
}

O checkpoint é salvo em projects/<project_id>/checkpoints/ antes de qualquer operação Git. Quando habilitado com segurança, o adapter adiciona e commita somente o checkpoint recém-criado; push é controlado por auto_push ou sync_mode: pull-push. Falhas e contenção do lock são reportadas em git_status e warnings, sem invalidar o arquivo local.

Retomando uma sessão

No início de uma nova sessão, chame memory_resume usando a mesma project_key, quando ela tiver sido adotada:

{
  "project_key": "meu-projeto",
  "sync": "none"
}

O resultado contém o checkpoint válido mais recente como briefing compacto, além de truncated, truncated_fields e uma estimativa de tokens. Checkpoints corrompidos são ignorados em favor do candidato válido anterior.

Com sync: "pull", o servidor tenta git pull --rebase antes da leitura. Em falha de rede, autenticação, timeout ou conflito, usa a cópia local e retorna offline_or_failed, data_may_be_stale: true e um warning explícito. Um sync: "none" explícito sempre desabilita o pull naquela chamada.

Consulte docs/SDD.md para o contrato normativo da V1.1.

Validação

pnpm check
pnpm test:coverage
npm pack --dry-run

Os testes automatizados cobrem o formato compartilhado e o handoff entre clientes MCP. O aceite nos aplicativos Claude Code e Codex reais, o fluxo em duas máquinas e o período de uso de duas semanas permanecem validações operacionais explícitas.