Metadata-Version: 2.4
Name: continuity-mcp
Version: 0.2.1
Summary: Agent memory with receipts: an MCP server over an append-only, hash-chained ledger for task state, memory, and verified handoffs across sessions and models.
License-Expression: Apache-2.0
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: mcp>=1.2
Provides-Extra: api
Requires-Dist: fastapi>=0.110; extra == "api"
Requires-Dist: uvicorn>=0.29; extra == "api"
Requires-Dist: pydantic>=2.6; extra == "api"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: fastapi>=0.110; extra == "dev"
Requires-Dist: uvicorn>=0.29; extra == "dev"
Requires-Dist: pydantic>=2.6; extra == "dev"
Dynamic: license-file

# 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:

```bash
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 [the Stage 2 protocol](docs/testing/2026-07-05-capture-reliability-stage-2.md).

For Codex CLI/Desktop, add this to `~/.codex/config.toml`, using an absolute
path for the shared ledger:

```toml
[mcp_servers.continuity]
command = "continuity-mcp"
startup_timeout_sec = 30

[mcp_servers.continuity.env]
CONTINUITY_DB = "/absolute/path/to/continuity.db"
```

Agents only share state when their hosts point at the same `CONTINUITY_DB`.

## What Users Do

Continuity is local-first: install the MCP server once, choose one ledger file
per project or workspace, and connect every participating agent host to that
same file.

During normal work:

1. A fresh agent calls `resume()`. If exactly one current task is safe to
   resume, Continuity supplies its state, next action, source sequences, memory,
   and captured-artifact headers. Otherwise it returns an honest task list.
2. After meaningful work, the agent calls `checkpoint()` with what changed and
   the next useful action. Codex CLI has verified organic capture; Claude Code
   reaches the autosave tier when its documented hooks are installed.
3. Use `write_memory` / `read_memory` for durable facts, and
   `capture_artifact` / `get_artifact` when exact text such as approved copy,
   commands, or configuration must survive without summary loss.
4. When a person needs a receipt, run `continuity-handoff` or call
   `export_publish_package`. The MCP package export writes `handoff.json`,
   `HANDOFF.md`, and `handoff.html`; Continuity creates the files but does not
   upload them.

For any other MCP-capable host, install the same project instruction snippet
shown in [the capture-reliability protocol](docs/testing/2026-07-05-capture-reliability-stage-2.md).
Compatibility means the host can call Continuity's tools; it does not mean that
host has passed the capture-reliability gate.

As a developer:

```bash
make setup
make test
make serve
```

Then open the read-only Console:

```text
http://127.0.0.1:8000/console
```

## Common Commands

```bash
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:

```bash
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:

```text
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:

```bash
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.

```bash
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](docs/testing/persistent-agent-proof-runbook.md)
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:

```bash
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](docs/testing/2026-07-05-capture-reliability-stage-2.md).

## Repository Layout

```text
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](ROADMAP_AND_HANDOFF.md) is the canonical execution
  tracker. Its Execution Checkpoint and Forward Roadmap control current work.
- [Idea Backlog](docs/IDEA_BACKLOG.md) captures ideas without promoting them
  into active execution.
- [Continuity Implementation Plan v3.4](docs/strategy/Continuity_Implementation_Plan_v3_4.md)
  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.
