Continuity

Continuity is the system of record for agent work: an agent continuity layer that captures task state, memory, decisions, provenance, and handoff context across models, sessions, and tools.

The event log is the product. Task context, project memory, agent memory, workflow state, gates, timeline rows, and the Console are projections of one append-only, hash-chained ledger.

Launch Capabilities

Continuity ships three related but distinct capabilities:

Capability	What it means today	Not claiming yet
Persistent memory	Project and agent memory are stored as ledger events and survive across sessions, hosts, and models with source sequences and conflict signals.	A consumer-app personalization platform or vector-memory benchmark competitor.
Source-cited recall	resume() and task continuation projections recall the active task, prior decisions, chronology, conflicts, next action, and relevant memory from the ledger.	Semantic/vector search over arbitrary past conversations.
Verified handoff	checkpoint() captures resumable state, and proof artifacts export sanitized continuation context, timeline, provenance, ledger integrity, and Merkle root verification. Publish packages can generate JSON, Markdown, and standalone HTML from the same sanitized artifact.	Authenticated human identity, external timestamp notarization, hosted receipt links, or standalone proofs for omitted ledger events.

In short: persistent memory stores what should survive, source-cited recall finds the task state a fresh agent needs, and verified handoff turns that state into an inspectable receipt.

Every event can carry optional payload-level provenance and usage telemetry: task/session identity, agent/model identity, parent and consumed ledger sequence numbers, handoff source, token counts, usage source, and exact microdollar cost. This metadata stays in the payload layer so the immutable chain remains stable while provenance evolves.

The primary continuation path is checkpoint() followed by resume(). checkpoint() captures resumable task state in one MCP call. resume() lets a fresh agent discover the active task without a project or task ID when the ledger is unambiguous. The lower-level task-chain projection still returns current task state, ordered chronology, decisions, unresolved conflict signals, and provenance chain through the Python helper, FastAPI at /projects/{project_id}/tasks/{task_id}/continuation, and MCP as compile_task_context.

Operational conflicts are first-class ledger events. When two agents produce contradictory task assessments, Continuity records an OPERATIONAL_CONFLICT that links the exact event sequences in disagreement. The conflict remains in compiled context, FastAPI at /projects/{project_id}/tasks/{task_id}/conflicts, and MCP until a human records an OPERATIONAL_CONFLICT_RESOLVED event.

Quick Start

As a user:

pip install continuity-mcp
claude mcp add continuity --env CONTINUITY_DB="$HOME/continuity.db" -- continuity-mcp

For Claude Code hook-verified autosave, add the continuity-hooks command to your Stop and SessionEnd hooks as shown in site/docs.html.

As a developer:

make setup
make test
make serve

Then open the read-only Console:

http://127.0.0.1:8000/console

Common Commands

make setup   # create/update continuity-core/.venv and install requirements
make test    # run the test suite
make serve   # run FastAPI at http://127.0.0.1:8000
make mcp     # run the MCP server
make demo    # run the recursive proof demo
make proof   # export and verify the multi-model proof artifact
make ollama-chain # run the local multi-model Ollama chain proof
make codex-persistence-proof  # run two isolated Codex sessions through Continuity
make claude-persistence-proof # run two isolated Claude sessions through Continuity
make cross-agent-persistence-proof # run the Codex-to-Claude handoff proof
make capture-reliability-trials CLIENT=codex # run Stage 2 live capture trials
make capture-reliability-report DBS="trial-1.db trial-2.db trial-3.db trial-4.db trial-5.db"
continuity-handoff --db "$HOME/continuity.db" --list-tasks # list exportable tasks
continuity-hooks # Claude Code Stop/SessionEnd hook command

Proof Artifact

The completed Phase 4 Trust and Proof work exports a shareable Continuity proof artifact from real ledger events:

make proof

The command writes examples/multi_model_code_review.jsonl, a permissioned internal artifact showing a real multi-agent review sequence: external review, Codex triage, operational conflict, human resolution, gate approval, selected timeline, continuation context, provenance, and ledger integrity.

The artifact intentionally exports sanitized summary payloads. It retains original ledger hashes and verifies exported chain-entry metadata, but it is not yet a standalone public notary proof for omitted ledger events.

For a portable handoff bundle, the MCP tool export_publish_package writes:

handoff.json   # structured sanitized proof artifact
HANDOFF.md     # readable handoff receipt
handoff.html   # standalone escaped HTML for publishing anywhere

The package only generates files. It does not upload, host, or share them.

Local Model Proofs

The local Ollama chain proof tests continuity across installed local models:

make ollama-chain

The dated finding and corrected targeted rerun are recorded in docs/testing/2026-06-19-local-ollama-chain-proof.md. Across three corrected runs, Continuity achieved 18/18 context-fidelity assertions, 9/9 provenance assertions, 9/9 exact model outputs, and 3/3 valid ledgers using independent Qwen, Gemma, and Ministral model families.

Persistent Agent Proofs

The same-agent proof harness starts two fresh client processes connected only through a dedicated Continuity SQLite ledger. Session A captures initial task state with checkpoint(). After Session A exits, the harness creates a random challenge. Session B must start with resume() and no project or task identifiers, then Continuity verifies the output, linked validation, completion turn, ledger integrity, and sanitized proof artifact from recorded events.

make codex-persistence-proof
make claude-persistence-proof
make cross-agent-persistence-proof

Codex runs ephemerally with native memories disabled. Claude runs without session persistence and with only the explicit Continuity MCP configuration. See the persistent-agent proof runbook for exact boundaries, authentication checks, and troubleshooting. The cross-agent mode stores its post-Codex challenge in shared project memory and requires Claude's output and completion turn to carry Codex handoff provenance.

Model Adapters

The core test suite does not call external model providers. Provider SDKs are optional and imported lazily by their adapters.

• OpenAI/OpenAI-compatible endpoints use OPENAI_API_KEY and optional OPENAI_BASE_URL.
• Anthropic uses ANTHROPIC_API_KEY.
• Ollama uses local HTTP by default at http://localhost:11434, includes a request timeout, and raises AdapterError with contextual failures instead of hanging or leaking low-level urllib errors.

Capture Reliability

checkpoint() and resume() solve the capture/discovery ceremony without a durable runner. The remaining launch question is model/host compliance: will a real agent call checkpoint() before stopping when given installed capture guidance?

Stage 2 is split into two rungs:

• Stage 2A: installed capture guidance plus a light trial nudge to follow that guidance before stopping.
• Stage 2B: no capture nudge in the task prompt; only installed project guidance and MCP tool descriptions can trigger capture.

Stage 2 measures capture reliability with five real host trials per host:

make capture-reliability-trials CLIENT=codex
make capture-reliability-trials CLIENT=claude
make capture-reliability-report DBS="trial-1.db trial-2.db trial-3.db trial-4.db trial-5.db"

Four passing ledgers out of five means MCP-only capture is launch-worthy for that host. Below that threshold, build a host-native stop/session-end hook and rerun. Only if hooks fail does the durable runner become justified by evidence.

Current Stage 2A launch-host result:

• Codex CLI: 5/5 passing ledgers.
• Claude Code: 5/5 passing ledgers.

Current Stage 2B zero-nudge result:

• Codex CLI organic: 5/5 passing ledgers.
• Claude Code organic: 1/5 passing ledgers.
• Claude Code with Stop/SessionEnd hooks: 5/5 passing ledgers.

Do not claim zero-nudge organic capture for Claude Code from MCP alone. The supported launch claim is Codex CLI organic autosave and Claude Code hook-verified autosave. Hard-kill crash capture remains a documented gap; hooks do not fire on hard-killed processes.

See the Stage 2 protocol.

Repository Layout

continuity-core/
  continuity/       # ledger, projections, API, MCP, Console, adapters
  scripts/          # demos and proof scripts
  tests/            # pytest suite
  README.md         # core package details

docs/
  strategy/         # canonical strategy and implementation plans
  strategy/archive/ # older strategy/research source material
  superpowers/      # design specs and implementation plans
  testing/           # evidence notes from local and integration tests

examples/           # shareable proof artifacts generated from real ledger data

AGENTS.md
architecture_decisions.md
ROADMAP_AND_HANDOFF.md

Plans

• Roadmap & Handoff is the canonical execution tracker and current Phase 0-7 sequence. Its Execution Checkpoint controls current implementation work.
• Idea Backlog captures ideas without promoting them into active execution.
• Continuity Implementation Plan v3.4 preserves strategic background and the historical phase labels used during its adversarial review.

CI

GitHub Actions runs the Python test suite on pushes and pull requests to main. If Actions are disabled in repository settings, enable them once; no manual test initiation is otherwise required.

Notes

• Runtime artifacts such as SQLite databases and exported ledgers are ignored under continuity-core/.
• The known Starlette/FastAPI TestClient deprecation warning is third-party dependency churn and does not indicate a Continuity test failure.