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–6 concluídos. O servidor MCP expõe memory_checkpoint e memory_resume, cobrindo o fluxo local de criação e retomada com briefing determinístico. O adapter Git opcional entra no próximo milestone.

Requisitos

• Node.js 24 ou superior
• pnpm 10
• Git opcional apenas para o repositório privado de dados

Desenvolvimento

pnpm install
pnpm check
pnpm dev init --help

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 session-handoff --scope user -- session-handoff mcp

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/. Até o milestone 7, commit e push aparecem como skipped; a persistência local já funciona sem Git e sem rede.

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.

Até o milestone 7, solicitar sync: "pull" não executa Git: o resume usa a cópia local e retorna offline_or_failed, data_may_be_stale: true e um warning explícito.

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