CONTINUUM

CONTINUUM: Verifiable semantic recovery for long-running AI agents. Semantic checkpoints (not conversation dumps), an idempotent action ledger that refuses duplicate side effects, and a hash-chained tamper-evident event log, all exposed as a deny-by-default MCP server. Framework-agnostic, Python 3.11+.

Visit the CONTINUUM website

Contents

Why · Quick Start · How it works · Features · Security Extension · Empirical Verification · MCP Integration · Framework Integration · Core Concepts · Architecture · API and CLI · Roadmap · What CONTINUUM Is Not · Related work · Status and limitations · Contributing · License

Why

Modern AI agents run long tasks (hundreds of LLM calls, tool invocations, file and database writes). When they crash, the usual response is to replay everything from scratch, which duplicates work, duplicates side effects, wastes tokens, and loses decisions.

CONTINUUM asks a narrower, harder question: can an agent resume from a compact semantic representation of its task state while independently verifying that state is still valid in the current environment? Its differentiator is three-part:

• Semantic checkpoints: a compact, versioned representation of what the agent needs to continue, not a conversation dump.
• Independent environment revalidation: every checkpoint component is verified against the current environment before resume, with staleness propagating through the dependency graph.
• Provenance-aware state: every fact traces to its origin, so agent-reported progress is never self-certifying.

Quick Start

Not published to PyPI yet. Install from a clone. One clone is enough to get the library, CLI, MCP server, and every adapter ready for contribution.

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]

pip fallback: replace uv pip install with pip install in every command above.

Verify:

continuum --help                 # CLI entrypoint
continuum-mcp --help             # MCP server entrypoint (needs [mcp] or [dev])
pytest -q                        # ~1,300 passed (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

The core library has one runtime dependency (pydantic>=2.7); everything else is opt-in. The full package map, extras matrix, Postgres test setup, and per-command verification are in references/install.md.

Wire a coding agent in two minutes

For Claude Code, Gemini CLI, or Codex, you do not write Python and do not need a prompt file:

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

From then on every file the agent writes is captured as hash-chained evidence, its session starts with an automatic status briefing, unclaimed side effects registered in .continuum/gate.json are refused before they fire, and a fresh session after any crash resumes with executable next steps. No CLAUDE.md required.

Minimal library example, record and recover:

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

Run the proof yourself:

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

The e2e-autonomy-test/ kit scripts a real invoice-batch task, a hard-kill mid-run, and a fresh resume session, then scores the outbox, ledger, and event chain out of band. Run 1 scored 7/7 mechanics against a real Claude Code session. Full walkthrough in references/e2e.md.

How it works

CONTINUUM separates LLM context (temporary) from durable task state (permanent). Instead of saving conversation history, it constructs a semantic checkpoint, the minimum verified information required to continue.

The detailed explanation, the projection model, and the recovery context are in references/architecture.md.

Features

Security Extension

Two additive security extensions sit on top of the recovery and checkpoint substrate. They do not change resume, replay, or the existing crash-time revalidation path.

• Secure Planning Loop: observations carry provenance and are verified by two independent signals (verified / unverified / contested). A plan branch gated on an unverified or contested observation is escalated to REQUIRES_REVIEW. Decisions are appended to the ledger as PERCEPTION_OBSERVED and BRANCH_RESOLVED events.
• Periodic Revalidation: reuses the recovery engine on a step interval (default 25) and on app switch, so mid-run environment drift is caught within one cycle instead of only at the next crash.

See docs/PROBLEM.md, docs/RESULTS.md, and STATUS.md.

Empirical Verification

CONTINUUM is verified against real LLM agents, live protocol boundaries, and hard process crashes, not just mock unit tests.

• Real agents: multi-session Claude Code invoice batches with mid-run SIGKILL, scored 7/7 on mechanics; resumed sessions queried continuum_resume, routed side effects through the two-phase ledger, refused to duplicate verified writes, and respected request_human. Live testing surfaced prompt-drift dedup gaps, closed by canonical path normalization and token-based fallback in ActionLedger.claim().
• Third-party clients: Gemini CLI and Kilo Code connected over stdio JSON-RPC against the live SQLite store, validating multi-agent co-existence and authorization isolation.
• Protocol compliance: driven end to end with @modelcontextprotocol/inspector --cli across process deaths; mutating tools deny by default behind CONTINUUM_MCP_MUTATING_CLIENTS; external claims degrade to REQUIRES_REVIEW (safe: false).
• Self-healing: hard-killed servers recover from orphaned SQLite -wal/-shm sidecars via single-retry cleanup at startup.
• Scale: roughly 1,300 tests passing on Python 3.11, 3.12, and 3.13 (unit, hypothesis property-based, concurrency, adversarial); CONTINUUM-Bench runs five crash scenarios proving 0 duplicate work and 0 duplicate side effects.
• Adversarial audit: the full MCP surface was audited over the live protocol; three defects were found and fixed. Method and reproduction steps in test.md.

MCP Integration

CONTINUUM ships an MCP server so an agent can record progress, checkpoint, and route external side effects through the ledger without embedding the library:

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

Eleven tools over stdio. Three are read-only (continuum_validate, continuum_resume, continuum_list_actions); eight mutate. Side effects are two-phase (claim, perform, complete), and mutating tools deny by default behind an allowlist. Agent-reported state is recorded with Origin.EXTERNAL_AGENT provenance and marked REQUIRES_REVIEW.

Verification details, including crash recovery at startup and the end to end Claude Code test, are in references/mcp.md. If a registered server reports CONNECTION_CLOSED, the cause is almost always PATH resolution rather than the server itself: docs/api/mcp.md has the diagnosis and two remedies.

Framework Integration

Nine adapters ship in src/continuum/adapters/ (one in-process facade plus eight integrations), all optional installs so the core stays standard-library-only:

Each adapter records progress through the ledger and routes external effects through the two-phase intercept/complete protocol. All three framework adapters have end-to-end integration tests and have been driven against a live OpenRouter model, where the runs surfaced and then closed an LLM argument-drift dedup gap and two OpenAI-adapter bugs. Full usage, live-model results, and runnable examples for every adapter are in references/adapters.md.

Three further production frameworks are covered by thin, SDK-free hook surfaces in adapters/thin.py:

For stacks none of these reach: continuum gateway enforces claims on outbound HTTP from any language, and continuum.otel.make_span_processor(storage) turns existing OpenTelemetry tool spans into evidence.

Resuming agent- or MCP-reported runs

State reported over MCP, or through the OpenAI adapter, carries Origin.EXTERNAL_AGENT provenance and resolves to request_human until confirmed. LangGraph and LangChain runs use Origin.DETERMINISTIC and resume directly. To clear review and resume:

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

Over MCP the equivalent is the continuum_confirm tool followed by continuum_resume. Confirmation is a one-time, human-attested event: the escape hatch for the self-certification safety, so an externally-driven run is never permanently stuck.

Core Concepts

The deep reference for each concept lives in references/concepts.md.

• Semantic Checkpoints - a compact, versioned representation of what the agent needs to continue.
• State Validation - every component independently verified; staleness propagates through the dependency graph.
• Idempotent Action Ledger - external side effects tracked and de-duplicated; uncertain outcomes raise instead of silently retrying.
• Recovery Modes - RESUME, REPAIR_AND_RESUME, ROLLBACK, WAIT, REQUEST_HUMAN, ABORT (plus REPLAN).
• Recovery Contract - a deterministic, integrity-sealed, gated next action.

Architecture

The system is built on immutable Pydantic v2 models with a cryptographic hash chain. State is projected from an append-only event log by a pure fold, not stored and mutated. The full reference is in references/architecture.md; a system diagram and enumerated reference in references/architecture-diagram.md.

Key guarantees: append-only events, atomic sequence allocation, durability on append_event return, write races fail loudly, and corruption is refused rather than returned.

CONTINUUM is one library (src/continuum, 100 Python files) plus a large test suite (93 files, roughly 1,300 tests). All modules append to and replay one hash-chained event log:

Three entry points: the continuum CLI, the continuum-mcp server, and the continuum serve sidecar. The storage, state, adapters, mcp, cli, actions, and checkpoint layers hold roughly 72% of the core and are the mature, heavily-tested layers. security/, the Postgres backend, migrations, and concurrency/ are committed but newer; the Postgres backend skips without a live DSN. interchange/ is done and tested.

API and CLI

Python surface (EventType, Run, SQLiteStorage, diff_states, project) and the adapter API are documented with runnable examples in references/api.md. The CLI is the same surface in shell form:

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

All wiring is host-side; the model's cooperation is optional:

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

Optional registries live beside your code and are data, not code: .continuum/gate.json (side-effect tools + stable-key templates), .continuum/reconcilers.json (probes that check external systems), .continuum/gateway.json (upstream routes).

Every command accepts --json, and read-only commands never write, so they are safe against a live database while an agent is mid-run. Exit codes are a safety contract (only a verified-safe run exits 0). Full command list, exit-code table, and state-diff output in references/cli.md.

Roadmap

Beyond the original plan: the MCP server, MCP authorization layer, provenance and anti-self-certification, community files, schema versioning, and a bounded recovery context are shipped. See STATUS.md for the verified-vs-believed breakdown and open correctness bugs.

What CONTINUUM Is Not

The core abstraction: semantic state + environment validation + action reconciliation = safe recovery.

Related work

CONTINUUM sits at the overlap of durable execution, idempotent side-effect tracking, and crash recovery for LLM agents. The closest neighbors are machine-checked resume contracts (Khan 2026), agentic transaction processing with constraint-gated admission (Mnemosyne 2026), checkpoint-rollback attack analysis (ACRFence 2026), and design-level prompt-injection defense (CaMeL 2025). The full annotated list, foundations, and citation audit are in references/related-work.md.

Status and limitations

• Tested: roughly 1,300 tests passing across Python 3.11, 3.12, and 3.13; exact counts and skips vary by platform and optional services such as Postgres (see STATUS.md). The MCP surface has also been audited adversarially over the live protocol; see test.md.
• Not on PyPI. Install from a clone (see Quick Start).
• MCP caller authentication is opt-in per deployment. When CONTINUUM_MCP_TOKEN is set, the server refuses every mutating tool unless the caller presents that shared secret in the initialize handshake's _meta.authToken. Without it, authorization is by declared identity only (the historical default, preserved for local single-user use).
• Confirming self-reported state over MCP requires a separate secret. continuum_confirm refuses every caller until the operator sets CONTINUUM_MCP_CONFIRM_TOKEN, because an agent allowed to record progress must not also be able to confirm it. The default path stays human-driven: run continuum confirm <run_id> on the host.
• Unbuilt components: Cloud API (Phase 13).
• Framework adapters are experimental. The OpenAI Agents SDK and LangGraph adapters do not yet carry the same crash-and-resume verification coverage as the generic facade. Prefer GenericAgentAdapter for production recovery.
• Agent/MCP runs need an explicit confirm before auto-resume. Externally-reported state is REQUIRES_REVIEW, so continuum resume returns request_human until a human confirms. By design, not a bug; see Framework Integration.
• e2e autonomy test series (issue #6): three full Claude Code runs scored 7/7 mechanics with unprompted recovery behavior observed. Further iterations across diverse prompt styles remain open.

Contributing

Contributions are welcome. This project is open source under Apache 2.0 and deliberately built to be extended: by researchers validating the recovery semantics, by engineers porting the ledger or MCP server to other frameworks or languages, and by anyone turning the planned roadmap into reality. A good place to start is the good first issue label on the issue tracker, or the open correctness bugs listed in STATUS.md.

Open an issue before submitting large PRs. See CONTRIBUTING.md for the full contribution guide, including the Code of Conduct.

Contributors

License

Apache 2.0 - see LICENSE.

Deep reference material:

• references/install.md - prerequisites, install levels, package map, verification
• references/concepts.md - semantic checkpoints, validation, ledger, recovery modes, contract
• references/architecture.md - data model, event log, projection, storage, checkpointing, recovery engine, security
• references/adapters.md - framework adapter usage and live-model validation results
• references/api.md - Python and adapter API
• references/cli.md - full CLI command list, exit codes, state diff
• references/mcp.md - MCP server status, verification, open questions
• references/bench.md - CONTINUUM-Bench design
• references/quickstart.md - install, examples, the proof scripts
• references/e2e.md - end to end autonomy test walkthrough
• references/testing.md - test suite layout and conventions
• references/related-work.md - annotated related work and citation audit