CONTINUUM

Recuperação semântica universal e verificável para agentes de IA de longa duração com checkpoints semânticos, ledger de ações idempotente e log encadeado por hash como um servidor MCP com negação por padrão

GitHub

Experimente este MCPPatrocinado

Documentação

CONTINUUM Banner

CONTINUUM: Recuperação semântica verificável para agentes de IA de longa duração. Checkpoints semânticos (não despejos de conversa), um registro de ações idempotente que recusa efeitos colaterais duplicados e um log de eventos encadeado por hash à prova de adulteração, tudo exposto como um servidor MCP com negação por padrão. Independente de framework, Python 3.11+.

Visite o site do CONTINUUM

_{Se o CONTINUUM ajudar seus agentes a se recuperarem, por favor, dê uma estrela no repositório. Isso ajuda outras pessoas a descobri-lo e mantém boas primeiras issues chegando.}

Conteúdo

Por quê · Início Rápido · Como funciona · Onde o CONTINUUM se encaixa · Recursos · Extensão de Segurança · Verificação Empírica · Integração MCP · Integração com Frameworks · Conceitos Centrais · Arquitetura · API e CLI · Roadmap · O que o CONTINUUM Não É · Trabalhos relacionados · Status e limitações · Contribuindo · Licença

Por quê

Agentes de IA modernos executam tarefas longas (centenas de chamadas de LLM, invocações de ferramentas, gravações de arquivos e bancos de dados). Quando eles falham, a resposta usual é repetir tudo do zero, o que duplica trabalho, duplica efeitos colaterais, desperdiça tokens e perde decisões.

O CONTINUUM faz uma pergunta mais restrita e difícil: um agente pode retomar a partir de uma representação semântica compacta do estado de sua tarefa enquanto verifica de forma independente que esse estado ainda é válido no ambiente atual? Seu diferencial tem três partes:

Checkpoints semânticos: uma representação compacta e versionada do que o agente precisa para continuar, não um despejo de conversa.
Revalidação independente do ambiente: cada componente do checkpoint é verificado contra o ambiente atual antes da retomada, com a propagação de obsolescência pelo grafo de dependências.
Estado com consciência de proveniência: cada fato rastreia sua origem, então o progresso relatado pelo agente nunca é autocertificado.

Início Rápido

Publicado no PyPI como continuum-agent 0.1.0 — pip install continuum-agent (pip install continuum-agent==0.1.0 para fixar). Tags de release também enviam wheels compilados anexados aos GitHub Releases.

Caminhos sem configuração (sem clone, sem instalação, nada publicado em lugar algum):

Caminho	Como
Instalar do PyPI	`pip install continuum-agent==0.1.0` — depois `continuum --help`
Ver a recuperação de falhas de ponta a ponta	`docker run --rm ghcr.io/cyrax321/continuum`
Usar a CLI via Docker	`docker run --rm ghcr.io/cyrax321/continuum continuum --help`
Executar a CLI sem clonar	`uvx --from git+https://github.com/Cyrax321/CONTINUUM.git continuum --help`
Ambiente de desenvolvimento completo no navegador

A imagem Docker é publicada no GHCR pela CI a cada push para main e a cada tag de release (.github/workflows/docker-publish.yml). O Codespace é definido em .devcontainer/.

git clone https://github.com/Cyrax321/CONTINUUM.git
cd CONTINUUM

uv venv && source .venv/bin/activate     # macOS / Linux; Windows: .venv\Scripts\activate

# Contributors (recommended): library + CLI + all test tooling + every adapter
uv pip install -e ".[dev]"

# Or pick only what you need: . (minimal), [mcp], [otel], [langgraph],
# [openai], [langchain], [attest], [postgres]

# Or skip the clone entirely:
uv pip install git+https://github.com/Cyrax321/CONTINUUM.git
uv pip install "continuum-agent[mcp] @ git+https://github.com/Cyrax321/CONTINUUM.git"

fallback do pip: substitua uv pip install por pip install em todos os comandos acima.

Verifique:

continuum --help                 # CLI entrypoint
continuum-mcp --help             # MCP server entrypoint (needs [mcp] or [dev])
pytest -q                        # ~1,380 collected (exact count and skips vary by environment)
ruff check src/ tests/ examples/ && ruff format --check src/ tests/ examples/
mypy src/continuum               # the three gates CI enforces

A biblioteca principal tem uma dependência de runtime (pydantic>=2.7); todo o resto é opcional. O mapa completo de pacotes, a matriz de extras, a configuração de teste do Postgres e a verificação por comando estão em references/install.md.

Conecte um agente de codificação em dois minutos

Para Claude Code, Gemini CLI ou Codex, você não escreve Python e não precisa de um arquivo de prompt:

continuum start my-task --goal "What the agent should do"
continuum hooks install claude-code --with-gate   # also: gemini, codex

A partir daí, cada arquivo que o agente escreve é capturado como evidência encadeada por hash, sua sessão começa com um briefing de status automático, efeitos colaterais não reivindicados registrados em .continuum/gate.json são recusados antes de dispararem, e uma nova sessão após qualquer falha retoma com próximos passos executáveis. Nenhum CLAUDE.md é necessário.

Exemplo mínimo da biblioteca, registrar e recuperar:

from continuum import EventType, Run, SQLiteStorage, project

store = SQLiteStorage("agent.db")
store.create_run(Run(run_id="run_4821", goal="Analyze 10,000 documents"))
store.append_event("run_4821", EventType.RUN_STARTED, {"goal": "Analyze 10,000 documents", "total": 10_000})

for i, doc in enumerate(documents):
    analyze(doc)
    store.append_event("run_4821", EventType.WORK_COMPLETED, {"doc": i})

# After a crash, a new process picks up exactly where it stopped:
state = project("run_4821", store.read_events("run_4821"))
print(state.progress.completed)            # already done, not repeated
print(store.verify_events("run_4821").ok)  # True, chain intact after the crash

Execute a prova você mesmo:

python examples/crash_recovery_agent.py   # real process kill, real side effect
python examples/context_compaction.py     # transcript lost, checkpoint survives
python examples/model_switch.py           # Model A dies, Model B resumes safely
python scripts/mcp_smoke.py               # real subprocess, real JSON-RPC traffic

O kit e2e-autonomy-test/ roteiriza uma tarefa real de lote de faturas, uma interrupção forçada no meio da execução e uma nova sessão de retomada, depois pontua a caixa de saída, o registro e a cadeia de eventos fora da banda. A execução 1 pontuou 7/7 mecânicas contra uma sessão real do Claude Code. Passo a passo completo em references/e2e.md.

Como funciona

O CONTINUUM separa o contexto do LLM (temporário) do estado durável da tarefa (permanente). Em vez de salvar o histórico da conversa, ele constrói um checkpoint semântico, a informação mínima verificada necessária para continuar.

CONTINUUM how it works

A explicação detalhada, o modelo de projeção e o contexto de recuperação estão em references/architecture.md.

Onde o CONTINUUM se encaixa

Quatro preocupações se sobrepõem em todo agente de longa duração. O CONTINUUM possui apenas a última e toca as outras três por meio de costuras explícitas. Nenhum concorrente é nomeado e nenhuma afirmação é feita sem um módulo enviado ou uma suíte publicada que já a imprima.

Camada	Responde	Como se conecta (módulos enviados ou saída publicada)
Harness	Como o agente chama ferramentas e progride em direção a um objetivo?	Fora do CONTINUUM. Pontos de conexão enviados em `src/continuum/adapters/generic.py` (`GenericAgentAdapter`), `src/continuum/adapters/thin.py` (hooks CrewAI, AutoGen, Pydantic AI), `src/continuum/mcp/server.py` (MCP stdio), `src/continuum/hooks.py` e `src/continuum/clienthooks.py` (hooks de ciclo de vida de CLI de codificação), `src/continuum/gateway.py` (aplicação de proxy HTTP para qualquer linguagem) e `src/continuum/otel.py` (ponte OpenTelemetry). Receitas estão em `docs/recipes/` e `references/adapters.md`.
Execução durável	O que aconteceu antes de uma falha e o que pode ser repetido sem perder trabalho?	Log de eventos encadeado por hash `src/continuum/events.py` com `verify()` e `trusted_through`, armazenamento durável `src/continuum/storage/sqlite.py` (WAL, `synchronous=FULL`, schema v6) e `src/continuum/storage/postgres.py` mais `src/continuum/storage/migrations.py`, checkpoints orientados por política `src/continuum/checkpoint/manager.py` e `src/continuum/checkpoint/policy.py` que repetem a lacuna em `restore()`. Passo a passo em `docs/recovery_walkthrough.md` (saída de `examples/recovery_walkthrough.py`).
Plano de controle	Qual execução está ativa, quem pode agir sobre ela e para onde vai a saída?	Registro de execuções e hierarquia pai/filho `src/continuum/storage/` e `src/continuum/recovery/family.py` (`continuum tree`), autorização por lista de permissões `src/continuum/mcp/authz.py` (`CONTINUUM_MCP_MUTATING_CLIENTS` / `CONTINUUM_MCP_TOKEN`), superfícies de apresentação `src/continuum/dashboard/app.py` e `src/continuum/serve/server.py`, CLI `src/continuum/cli/main.py` (`continuum runs`, `continuum tree`, `continuum health`).
Substrato de verificação	Dado o checkpoint no tempo T e o mundo como está agora, ainda é seguro e correto continuar?	`src/continuum/state/validator.py` (obsolescência `dependency -> evidence -> finding -> decision` mais `PlanStep.depends_on`), `src/continuum/provenance_map.py` (`Origin` a `REQUIRES_REVIEW` até `REVIEW_CONFIRMED`), `src/continuum/actions/ledger.py` com `src/continuum/actions/idempotency.py` e `src/continuum/gate.py` / `src/continuum/gateway.py` (reivindicar antes de disparar, recusa duplicatas, levanta `UnknownSideEffect` para reconciliação), `src/continuum/replayguard.py` (guarda portátil), `src/continuum/pinning.py` e `src/continuum/replay_similarity.py` (correção de repetição), `src/continuum/budgets.py` (limites de tentativas), `src/continuum/recovery/engine.py` + `src/continuum/recovery/contract.py` + `src/continuum/recovery/planner.py` + `src/continuum/recovery/observations.py` (severidade máxima `RESUME < ... < ABORT`, contrato selado com `evidence` / `reason` / `next_allowed_action` / `human_steps`), `src/continuum/checkpoint/rewind.py` (rebobinamento atômico de estado duplo), `src/continuum/analysis/prefix_trust.py` (confiança consultiva). Verificações publicadas: `docs/recovery_walkthrough.md`, `benchmarks/fault_injection/` (suíte que imprime `detection_rate` / `unsafe_resume_rate`), `src/continuum/benchmark/phase6/` (suíte de correção de recuperação), `docs/RESULTS.md` e o visual regenerável abaixo.

Cada linha acima é rastreável a um caminho que existe em main no commit marcado. Nada nesta tabela reafirma um número de benchmark; benchmarks vivem apenas na saída da suíte que já imprimem. Veja docs/research.md para a lista completa de suítes publicadas e documentos de design.

Recuperação de falhas, de verdade

A imagem abaixo não é uma simulação. É a saída de python demo-run/generate_crash_visual.py, que executa demo-run/worker.py até os._exit(9) no documento 399, chama continuum resume --env dataset=v4 e mostra o caminho de recusa (REQUEST_HUMAN, safe:false, saída 20), reconcilia o efeito colateral incerto com uma sonda, depois retoma do mesmo banco de dados e termina sem trabalho duplicado. A transcrição também é salva como docs/assets/crash-recovery.txt para auditoria.

Regenere:

python demo-run/generate_crash_visual.py
# or: python scripts/generate_crash_visual.py

Crash recovery: hard kill mid-batch, refusal, reconcile, resume

Passo a passo completo com código em docs/recovery_walkthrough.md (examples/recovery_walkthrough.py). O harness mínimo de benchmark está em references/bench.md (continuum benchmark).

Recursos

Capacidade	O que ela oferece
Checkpoints semânticos	Estado compacto, versionado e inspecionável, não um despejo de transcrição
Registro de ações idempotente	Recusa efeitos colaterais externos duplicados; expõe os incertos para reconciliação
Revalidação de ambiente	Cada componente do checkpoint é verificado contra o mundo atual antes de retomar
Estado ciente de proveniência	Progresso relatado pelo agente é marcado como `REQUIRES_REVIEW`, nunca autocertificado
Mecanismo de recuperação	Sete modos de recuperação com um contrato determinístico e selado de próxima ação
Servidor MCP com negação por padrão	Onze ferramentas, divisão somente leitura/mutação, lista de permissões do chamador
Adaptadores de framework	Integrações genéricas para Python, OpenAI Agents SDK, LangGraph e LangChain
Loop de planejamento seguro	Verificação de observação com dois sinais eleva ramos de alto risco para REQUER_REVISÃO
Revalidação periódica	Ambiente re-verificado em um cronograma, capturando desvios no meio da execução dentro de um ciclo
Log à prova de adulteração	Log de eventos encadeado por hash (36 tipos de eventos) com verificação de integridade
Portão de aplicação	Chamadas de efeitos colaterais não reivindicadas são recusadas antes de disparar; mensagens de negação ensinam o protocolo de reivindicação
Ganchos de observação	Cada arquivo que um CLI de codificação escreve torna-se evidência verificada por digest, fora do controle do modelo
Briefing de sessão	Novas sessões aprendem o estado da execução deterministicamente no início, incluindo o resumo de raciocínio da última sessão
Sondas de reconciliação	Comandos registrados resolvem efeitos colaterais incertos automaticamente; humanos veem apenas o restante
Orientação executável	Retomar/validar renderiza os próximos passos como comandos executáveis, não status
Gateway HTTP de aplicação	Chamadas de saída em qualquer idioma exigem reivindicações; respostas as resolvem a partir da realidade
Ponte OpenTelemetry	Spans de chamadas de ferramentas do rastreamento de produção tornam-se evidência com zero mudanças de código
Índice de ações	Consultas de idempotência entre execuções são leituras indexadas, não varreduras de log completo
Fixação de versão	Hashes de prompt/ferramenta/modelo afirmados pelo chamador são armazenados por reivindicação; desvios são expostos na retomada
Orçamentos de tentativas	Limites de tentativas por tipo de ação aplicados no momento da reivindicação; agentes veem tentativas restantes
Pai/filho multiagente	Retomada do pai compõe o pior estado da família; filho incerto bloqueia o pai
Nova tentativa informada	Resumos de falha escritos pelo mecanismo são injetados em retomadas pós-recuperação
Semântica de fork	Continuações divergentes ramificam em execuções filhas com autoridade renovada
Compactação de log	Prefixo pré-âncora arquivado verbatim; log ativo limitado para execuções de um mês
Rastreamento de concessões consumidas	Referências de autoridade de uso único são marcadas como gastas no status terminal; reutilização após restauração é recusada (`GRANT_DENIED`), defendendo o caminho de checkpoint-restauração contra Ressurreição de Autoridade
Atestação de cadeia	`continuum attest` assina a cabeça da cadeia de uma execução com Ed25519 para que um verificador externo possa provar que o histórico não foi alterado a partir de uma chave conhecida
Superfície de painel HITL	Botões confirmar/reconciliar/completar com paridade de auditoria com o CLI

Extensão de Segurança

Duas extensões de segurança aditivas ficam sobre o substrato de recuperação e checkpoint. Elas não alteram retomada, replay ou o caminho de revalidação em tempo de falha existente.

Loop de Planejamento Seguro: observações carregam proveniência e são verificadas por dois sinais independentes (verified / unverified / contested). Um ramo de plano condicionado a uma observação não verificada ou contestada é elevado para REQUIRES_REVIEW. Decisões são anexadas ao registro como eventos PERCEPTION_OBSERVED e BRANCH_RESOLVED.
Revalidação Periódica: reutiliza o mecanismo de recuperação em um intervalo de passos (padrão 25) e na troca de aplicativo, para que desvios de ambiente no meio da execução sejam capturados dentro de um ciclo em vez de apenas na próxima falha.

Veja docs/PROBLEM.md, docs/RESULTS.md e STATUS.md.

Verificação Empírica

CONTINUUM é verificado contra agentes LLM reais, limites de protocolo ao vivo e falhas de processo severas, não apenas testes unitários simulados.

Agentes reais: lotes de faturas do Claude Code em múltiplas sessões com SIGKILL no meio da execução, pontuados 7/7 em mecânica; sessões retomadas consultaram continuum_resume, rotearam efeitos colaterais pelo registro de duas fases, recusaram duplicar gravações verificadas e respeitaram request_human. Testes ao vivo revelaram lacunas de deduplicação por desvio de prompt, fechadas por normalização de caminho canônico e fallback baseado em token em ActionLedger.claim().
Clientes de terceiros: Gemini CLI e Kilo Code conectados via stdio JSON-RPC contra o armazenamento SQLite ao vivo, validando coexistência multiagente e isolamento de autorização.
Conformidade de protocolo: conduzido de ponta a ponta com @modelcontextprotocol/inspector --cli através de mortes de processo; ferramentas de mutação negam por padrão atrás de CONTINUUM_MCP_MUTATING_CLIENTS; reivindicações externas degradam para REQUIRES_REVIEW (safe: false).
Autocura: servidores mortos à força se recuperam de sidecars SQLite órfãos -wal/-shm via limpeza de tentativa única na inicialização.
Escala: aproximadamente 1.380 testes coletados (~1.360 passando; o restante pula sem serviços opcionais) em Python 3.11, 3.12 e 3.13 (unitários, hypothesis baseados em propriedades, concorrência, adversarial). CONTINUUM-Bench executa cinco cenários de falha mais um cenário dedicado de desvio de argumento, medindo 0 trabalho duplicado e 0 efeitos colaterais duplicados para CONTINUUM contra duplicação total para replay ingênuo; uma suíte separada de correção de recuperação com 12 cenários (continuum.benchmark.phase6) codifica os pontos de falha do levantamento de execução durável como asserções executáveis.
Auditoria adversarial: toda a superfície MCP foi auditada sobre o protocolo ao vivo; três defeitos foram encontrados e corrigidos. Método e passos de reprodução em test.md.

Integração MCP

CONTINUUM inclui um servidor MCP para que um agente possa registrar progresso, fazer checkpoint e rotear efeitos colaterais externos pelo registro sem embutir a biblioteca:

uv pip install -e ".[mcp]"
CONTINUUM_MCP_MUTATING_CLIENTS=your-client-name continuum-mcp

Onze ferramentas via stdio. Três são somente leitura (continuum_validate, continuum_resume, continuum_list_actions); oito mutam. Efeitos colaterais são de duas fases (reivindicar, executar, completar), e ferramentas de mutação negam por padrão atrás de uma lista de permissões. Estado relatado pelo agente é registrado com proveniência Origin.EXTERNAL_AGENT e marcado como REQUIRES_REVIEW.

Detalhes de verificação, incluindo recuperação de falha na inicialização e o teste de ponta a ponta do Claude Code, estão em references/mcp.md. Se um servidor registrado relatar CONNECTION_CLOSED, a causa é quase sempre resolução de PATH em vez do próprio servidor: docs/api/mcp.md tem o diagnóstico e dois remédios.

Integração de Framework

Nove adaptadores são fornecidos em src/continuum/adapters/ (uma fachada em processo mais oito integrações), todos instaláveis opcionalmente para que o núcleo permaneça apenas com a biblioteca padrão:

Adaptador	Classe	Notas
Agente Python genérico	`GenericAgentAdapter`	Fachada em processo; grava estado confiável (`Origin.DETERMINISTIC`).
Sandbox de sistema de arquivos	`FilesystemSandboxAdapter`	Sandbox de diretório local, sem serviço externo, padrão para docs e CI.
Python em processo	`PythonInProcAdapter`	Executa Python em um diretório de trabalho temporário, registra via ledger.
Contêiner	`ContainerAdapter`	Suportado por Docker, pulo protegido quando `docker` está ausente.
Navegador	`BrowserAdapter`	Suportado por Playwright, pulo protegido quando não instalado.
Kubernetes	`KubernetesAdapter`	Suportado por `kubectl`, pulo protegido quando não configurado.
OpenAI Agents SDK	`OpenAIAgentAdapter`	Experimental. Ganchos `ToolContext` / `RunHooks`; `openai-agents` opcional.
LangGraph	`LangGraphAgentAdapter`	Experimental. Envolve um `StateGraph`; `langgraph` opcional.
LangChain	`LangChainAgentAdapter`	Experimental. Insere `checkpoint_node` em um pipeline LCEL `Runnable` e no loop de chamada de ferramentas `create_agent`; `langchain` opcional.

Cada adaptador registra progresso pelo ledger e roteia efeitos externos pelo protocolo de interceptação/complete de duas fases. Todos os três adaptadores de framework têm testes de integração de ponta a ponta e foram conduzidos contra um modelo OpenRouter ao vivo, onde as execuções revelaram e depois fecharam uma lacuna de deduplicação por desvio de argumento LLM e dois bugs do adaptador OpenAI, incluindo uma prova de falha severa ao vivo (os._exit(137) no meio de efeito colateral) por adaptador. Uso completo, resultados de modelo ao vivo e exemplos executáveis para cada adaptador estão em references/adapters.md.

Aplicativos LangGraph de produção também podem manter sua API de persistência nativa: make_continuum_checkpointer(storage) implementa o BaseCheckpointSaver do LangGraph sobre o armazenamento do CONTINUUM, para que cada put caia no mesmo log de eventos encadeado por hash e marcado por proveniência (veja references/adapters.md).

Três frameworks de produção adicionais são cobertos por superfícies de gancho finas, sem SDK, em adapters/thin.py:

Framework	Superfície de interceptação	Ponto de entrada
CrewAI	ganchos globais antes/depois de chamada de ferramenta	`install_crewai_hooks(storage, run_id)`
AutoGen core	`FunctionTool.run_json` envolvido no lugar	`wrap_autogen_tool(tool, storage, run_id)`
Pydantic AI	capacidade de Hooks assíncrona	`Agent(capabilities=[wrap_pydantic_ai_hooks(storage, run_id)])`

Para stacks que nenhum desses alcança: continuum gateway aplica reivindicações em HTTP de saída de qualquer idioma, continuum.otel.make_span_processor(storage) transforma spans de ferramentas OpenTelemetry existentes em evidência, e continuum serve expõe as mesmas operações que as ferramentas MCP sobre um protocolo de fio JSON agnóstico de idioma (stdio, ou HTTP via --transport http com autenticação CONTINUUM_SERVE_TOKEN).

Retomando execuções relatadas por agente ou MCP

Estado relatado via MCP, ou através do adaptador OpenAI, carrega proveniência Origin.EXTERNAL_AGENT e resolve para request_human até confirmação. Execuções LangGraph e LangChain usam Origin.DETERMINISTIC e retomam diretamente. Para limpar revisão e retomar:

continuum confirm <run_id>   # records REVIEW_CONFIRMED, then re-assesses
continuum resume <run_id>    # now reports RESUME

Via MCP, o equivalente é a ferramenta continuum_confirm seguida por continuum_resume. Confirmação é um evento único, atestado por humano: a saída de emergência para a segurança de autocertificação, para que uma execução dirigida externamente nunca fique permanentemente travada.

Conceitos Centrais

A referência profunda para cada conceito vive em references/concepts.md.

Checkpoints Semânticos - uma representação compacta e versionada do que o agente precisa para continuar.
Validação de Estado - cada componente verificado independentemente; obsolescência propaga pelo grafo de dependências.
Registro de Ações Idempotente - efeitos colaterais externos rastreados e deduplicados; resultados incertos levantam em vez de tentar novamente silenciosamente.
Modos de Recuperação - RESUME, REPAIR_AND_RESUME, ROLLBACK, WAIT, REQUEST_HUMAN, ABORT (mais REPLAN).
Contrato de Recuperação - uma próxima ação determinística, selada por integridade e condicionada.

Arquitetura

CONTINUUM é organizado em torno de um invariante: todo fato carrega sua origem, e confiança é conquistada, nunca assumida. O sistema tem cinco camadas, cinco costuras de integração e três garantias.

As três garantias

Sem autocertificação. Estado relatado por agente é marcado como EXTERNAL_AGENT e degrada para revisão humana na retomada. Apenas escritores confiáveis (adaptadores em processo, operadores de CLI) produzem estado DETERMINISTIC.
Efeitos colaterais exigem reivindicações. Efeitos externos são reivindicados em um ledger idempotente antes de disparar; efeitos não reivindicados são bloqueados no limite do harness.
Decisões de recuperação verificam contra a realidade. Contratos de retomada verificam o estado do checkpoint contra o ambiente atual (versões de dependências, digests de arquivos, identidade do modelo) antes de declarar segurança.

Cinco costuras de integração

Qualquer harness de agente conecta-se através de exatamente uma destas; nenhuma cooperação de framework é necessária.

Seam 1: In-process adapters     GenericAgentAdapter.intercept_action(...);
         Python frameworks       wrap_tool(key_fn=...) on LangChain/LangGraph,
                                 OpenAI Agents SDK hooks
Seam 2: MCP server              continuum-mcp (11 tools over stdio)
         MCP-capable clients
Seam 3: CLI lifecycle hooks     continuum hooks install <client> [--with-gate]
         Coding CLIs             claude-code, gemini, codex
Seam 4: Enforcing HTTP gateway  continuum gateway --port N
         Any language            routes: .continuum/gateway.json
Seam 5: OpenTelemetry bridge    make_span_processor(storage)
         Traced applications     spans -> TOOL_COMPLETED evidence

Pipeline de aplicação

O pipeline de portão-para-observar fecha a lacuna de durabilidade no limite do harness:

PreToolUse hook                    PostToolUse hook
    |                                    |
    v                                    v
continuum gate                    continuum observe
    |                                    |
    |-- no claim? DENY (exit 2)          |-- TOOL_COMPLETED event:
    |   + instructions to claim          |     path, bytes, sha256
    |                                    |
    |-- live claim? ALLOW                |-- disk-checked status:
    |                                    |     verified / changed / missing
    v
agent performs effect
    |
    v
continuum_complete_action
    |
    v
claim settled from reality

Árvore de decisão de recuperação

O mecanismo de recuperação avalia sinais em ordem de severidade e retorna o máximo:

RESUME < REPAIR_AND_RESUME < REPLAN < WAIT < REQUEST_HUMAN < ROLLBACK < ABORT

Cada retomada produz um contrato selado com: status de recuperação, componentes verificados/invalidados, próximos passos executáveis (human_steps), observações pós-checkpoint (verificadas em disco), deriva de pinning e agregação de família (multiagente).

Arquitetura de armazenamento

Schema v6. SQLite é o principal; Postgres é verificado por CI.

Tabela	Finalidade
`events`	Log somente de acréscimo encadeado por hash (36 tipos de eventos)
`runs`	Metadados de execução com parent_run_id para multiagente
`versions`	Snapshots de SemanticState por checkpoint
`checkpoints`	Registros de checkpoint selados
`action_index`	Projeção de idempotência entre execuções (schema v3+)
`events_archive`	Armazenamento de prefixo compactado (schema v5+)
`lg_checkpoints` / `lg_writes`	Persistência nativa do LangGraph (schema v4+)

Mapa de módulos

CONTINUUM é uma biblioteca (src/continuum, 104 módulos) mais uma grande suíte de testes (98 arquivos de teste, ~1.380 testes). Todos os módulos anexam e reproduzem um único log de eventos encadeado por hash:

Módulo	Função
`events.py`	Log de eventos somente de acréscimo, encadeado por hash e `verify()`
`state/`	Projeção, validação, extração
`storage/`	SQLiteStorage (schema v6), postgres.py, migrations.py, actionindex.py
`actions/`	Livro-razão de ações idempotente, reconciliação, reivindicação/conclusão, rastreamento de concessões consumidas
`checkpoint/`	Checkpoints orientados por política com ancoragem forçada
`recovery/`	Mecanismo, planejador, contrato selado, orientação, observações, rollup de família, semântica de fork, resumos de nova tentativa informados
`gate.py`	Aplicação pré-uso de ferramenta: permitir/negar contra reivindicações do livro-razão
`gateway.py`	Proxy HTTP de aplicação: reivindicar antes de disparar para solicitações de saída
`replayguard.py`	Guarda portátil de segurança de reprodução: evaluate/protected_call/langgraph_protected_node
`hooks.py`	Hooks de checkpoint compartilhados (auto-checkpoint, progresso derivado de arquivo)
`clienthooks.py`	Perfis de instalador de cliente e gerenciamento de comandos de hook
`budgets.py`	Registro e avaliação de orçamento de nova tentativa
`pinning.py`	Normalização de pinning de versão e detecção de deriva
`replay_similarity.py`	Backends de similaridade semântica (exato/aproximado/embedding)
`reconcilers.py`	Registro de sondas para liquidação automática
`adapters/`	9 adaptadores baseados em classe + hooks finos (CrewAI/AutoGen/Pydantic AI) + armazenamento LangGraph
`mcp/`	11 ferramentas stdio mais autorização (auth de token, allowlist, token de confirmação)
`serve/`	Sidecar (wire JSON stdio + transporte HTTP)
`dashboard/`	Painel web com botões HITL (confirmar/reconciliar/concluir)
`cli/`	33 comandos argparse, códigos de saída como veredito
`otel.py`	Ponte de processador de spans OpenTelemetry

Limitações honestas

O gate não vê dentro de comandos de shell (Bash/curl contornam reivindicações de ferramentas estruturadas)
O backend Postgres é testado por CI, mas não testado em batalha em produção
Sem webhook-out para notificações de request_human ainda
Um nível de hierarquia multiagente v1
Descarregamento de payload (#254) ainda não implementado

Referência completa em references/architecture.md.

API e CLI

A superfície Python (EventType, Run, SQLiteStorage, diff_states, project) e a API de adaptadores são documentadas com exemplos executáveis em references/api.md. A CLI é a mesma superfície em forma de shell:

continuum runs                                   # list runs
continuum inspect <run_id>                       # semantic state
continuum validate <run_id> --env dataset=v4     # validate, read-only
continuum resume <run_id> --env dataset=v4       # recovery decision + contract + next steps
continuum checkpoint <run_id>                    # force a checkpoint, mutates
continuum actions <run_id>                       # external side effects
continuum reconcile <run_id>                     # settle uncertain effects with probes
continuum complete <run_id>                      # close a run as done, from the keyboard
continuum verify <run_id>                        # re-audit the event hash chain
continuum budget <run_id>                        # retry-budget usage per action type
continuum compact <run_id>                       # archive pre-anchor log prefix
continuum tree <parent_run_id>                   # show parent + children with recovery states
continuum attest <run_id> --key signer.pem       # sign the chain head for an external verifier

Toda a fiação é do lado do host; a cooperação do modelo é opcional:

continuum hooks install claude-code --with-gate   # coding CLIs: evidence, briefing, gate
continuum gateway --port 8765                     # enforcing HTTP proxy for everything else
provider.add_span_processor(continuum.otel.make_span_processor(storage))  # OTel to evidence
continuum-mcp                                     # anything MCP-capable: the eleven-tool server
continuum briefing                                # session-start context injection
continuum budget <run_id>                         # retry-budget usage report
continuum tree <parent_run_id>                    # multi-agent hierarchy view

Registros opcionais ficam ao lado do seu código e são dados, não código: .continuum/gate.json (ferramentas de efeito colateral + modelos de chave estável), .continuum/reconcilers.json (sondas que verificam sistemas externos), .continuum/gateway.json (rotas upstream).

Todo comando aceita --json, e comandos somente leitura nunca gravam, então são seguros contra um banco de dados ativo enquanto um agente está em execução. Códigos de saída são um contrato de segurança (apenas uma execução verificada como segura sai com 0). Lista completa de comandos, tabela de códigos de saída e saída de diff de estado em references/cli.md.

Roadmap

Fase	Componente	Status
1-11	Modelos de dados, estado semântico, persistência, checkpointing, validação, livro-razão de ações, mecanismo de recuperação, CLI, exemplos de recuperação de crash, snapshots/diffs de ambiente, adaptadores de framework	Completo
12	Suíte de benchmark (CONTINUUM-Bench)	Completo (harness mínimo)
13	API em nuvem (FastAPI + PostgreSQL)	Parcial: o backend de armazenamento PostgreSQL e o transporte sidecar HTTP (`continuum serve --transport http`) são enviados e testados por CI; o serviço multi-tenant hospedado não foi iniciado
14	Painel	Completo (`continuum dashboard`)
15+	Plano de durabilidade aplicado: hooks de observação, gate, briefing de sessão, sondas de reconciliação, gateway de aplicação, ponte OTel, índice de ações, orientação executável, instaladores multi-cliente, detecção de reprodução semântica, pinning de versão, orçamentos de nova tentativa, compactação de log, superfície HITL, semântica de fork, nova tentativa informada, agregação multiagente	Completo (ver issue #213)
Próximo	Plano de durabilidade em escala de meses: planos ancorados em marcos (#312), memória de tentativa estruturada (#313), rebobinamento atômico de estado duplo (#292), benchmark público de correção de recuperação (#293), notificações webhook-out (#305)	Planejado (especificação de rascunho em docs/UPGRADE_SPEC.md)

Além do plano original: o servidor MCP, as camadas de autorização MCP e autenticação de chamador, proveniência e anti-autocertificação, arquivos da comunidade, versionamento de schema com migrações para frente, um contexto de recuperação limitado, rastreamento de concessões consumidas, atestação de cadeia de eventos Ed25519, o checkpointer nativo do LangGraph e artefatos wheel em cada push para main são enviados. Veja STATUS.md para o detalhamento verificado-vs-acreditado e bugs de correção em aberto.

O que CONTINUUM não é

Não é isto	Em vez disso, é isto
Um LLM	Uma camada de confiabilidade para agentes que usam LLMs
Um framework de agentes	Uma camada de recuperação que se conecta a qualquer framework
Um banco de dados vetorial	Estado semântico estruturado, não embeddings
Um sistema RAG	Checkpoints verificados, não memória de recuperação aumentada
Um mecanismo de workflow	Uma camada de recuperação, não um orquestrador

A abstração central: semantic state + environment validation + action reconciliation = safe recovery.

Trabalho relacionado

CONTINUUM fica na interseção de execução durável, rastreamento de efeitos colaterais idempotente e recuperação de crash para agentes LLM. Os vizinhos mais próximos são contratos de retomada verificados por máquina (Khan 2026), processamento transacional agêntico com admissão controlada por restrições (Mnemosyne 2026), análise de ataque de rollback de checkpoint (ACRFence 2026) e defesa contra injeção de prompt em nível de design (CaMeL 2025). A lista anotada completa, fundamentos e auditoria de citações estão em references/related-work.md.

Status e limitações

Testado: 1.360 aprovados + 23 ignorados em uma execução completa na auditoria de 2026-08-24 desta árvore; CI aplica a suíte em Python 3.11, 3.12 e 3.13, e as contagens variam por plataforma e serviços opcionais como Postgres (veja STATUS.md). A superfície MCP também foi auditada adversariamente sobre o protocolo ao vivo; veja test.md.
No PyPI como continuum-agent 0.1.0 (pip install continuum-agent; o clone ainda funciona via pip install ., veja Quick Start).
A autenticação de chamador MCP é opt-in por implantação. Quando CONTINUUM_MCP_TOKEN está definido, o servidor recusa toda ferramenta de mutação a menos que o chamador apresente esse segredo compartilhado no initialize do handshake _meta.authToken; segredos por chamador estão disponíveis via CONTINUUM_MCP_CLIENT_TOKENS (pares name:secret). Sem nenhum token configurado, a autorização é apenas por identidade declarada (o padrão histórico, preservado para uso local de usuário único).
Confirmar estado auto-relatado via MCP requer um segredo separado. continuum_confirm recusa todo chamador até que o operador defina CONTINUUM_MCP_CONFIRM_TOKEN, porque um agente autorizado a registrar progresso não deve também ser capaz de confirmá-lo. O caminho padrão permanece orientado por humanos: execute continuum confirm <run_id> no host.
Componentes não construídos: API em nuvem (Fase 13).
Lacuna de aplicação de comandos de shell: o gate aplica reivindicações para chamadas de ferramentas estruturadas, mas não pode ver dentro de comandos Bash/curl. Documentado como recusa de escopo v1.
Adaptadores de framework permanecem experimentais. Todos os três adaptadores de framework agora têm provas de retomada suave e crash duro com modelo ao vivo (OpenRouter, gpt-4o-mini), incluindo o contrato de crash que bloqueia a retomada em um efeito colateral incerto, e agora têm testes de verificação de crash-e-retomada alcançando paridade com a fachada genérica (Refs #285). Prefira GenericAgentAdapter para recuperação em produção.
Execuções de agente/MCP precisam de uma confirmação explícita antes da retomada automática. Estado relatado externamente é REQUIRES_REVIEW, então continuum resume retorna request_human até que um humano confirme. Por design, não é um bug; veja Integração de Framework.
Série de testes de autonomia e2e (issue #6): três execuções completas do Claude Code pontuaram 7/7 em mecânica com comportamento de recuperação não solicitado observado. Iterações adicionais em diversos estilos de prompt permanecem em aberto.

Contribuindo

Contribuições são bem-vindas. Este projeto é open source sob Apache 2.0 e deliberadamente construído para ser estendido: por pesquisadores validando a semântica de recuperação, por engenheiros portando o livro-razão ou o servidor MCP para outros frameworks ou linguagens, e por qualquer pessoa transformando o roadmap planejado em realidade. Um bom lugar para começar é o rótulo good first issue no rastreador de issues, ou os bugs de correção em aberto listados em STATUS.md.

Abra uma issue antes de enviar PRs grandes. Veja CONTRIBUTING.md para o guia completo de contribuição, incluindo o Código de Conduta.

Contribuidores

Também com contribuições mescladas: Adhi1-2, yuki-fuyutsuki e okestroHjJeong.

Patrocinador

Se CONTINUUM ajuda seus agentes a se recuperarem de forma confiável, considere patrocinar para apoiar a manutenção de longo prazo.

Torne-se um patrocinador — GitHub Sponsors, ou adicione um link personalizado FUNDING.yml se preferir outra plataforma.

Licença

Apache 2.0 - veja LICENSE.

Material de referência aprofundado:

references/install.md - pré-requisitos, níveis de instalação, mapa de pacotes, verificação
references/concepts.md - checkpoints semânticos, validação, livro-razão, modos de recuperação, contrato
references/architecture.md - modelo de dados, log de eventos, projeção, armazenamento, checkpointing, mecanismo de recuperação, segurança
references/adapters.md - uso de adaptadores de framework e resultados de validação com modelo ao vivo
references/api.md - API Python e de adaptadores
references/cli.md - lista completa de comandos CLI, códigos de saída, diff de estado
references/mcp.md - status do servidor MCP, verificação, perguntas em aberto
references/bench.md - design do CONTINUUM-Bench
references/quickstart.md - instalação, exemplos, os scripts de prova
references/e2e.md - passo a passo do teste de autonomia de ponta a ponta
references/testing.md - layout e convenções da suíte de testes
references/related-work.md - trabalho relacionado anotado e auditoria de citações