Skip to main content

Continuum logo

Continuum

Continuum is an open remote state and memory backend for AI coding agents. It gives agents a shared source of truth for project state, serialized work locks, and durable episodic memory without forcing every agent to reread the whole repository on every prompt.

The ambition is an open protocol and reference implementation for the whole developer ecosystem: Claude Code, Codex, local agents, CI agents, IDE agents, and future MCP-compatible tools. The closest infrastructure precedent is OpenTofu/Terraform remote state: a small authoritative state file, backend-provided locking, and protections against stale writes.

What's New in 0.5: Agents Stop Overwriting Each Other

  • File reservations across tools and machines. Before editing, Claude Code reserves the files a session touches; Codex, Cursor or CI can reserve paths and globs through MCP (reserve_paths). A conflicting edit is denied in Claude Code with the holder's name and reason, and a git pre-commit guard blocks commits of files reserved from another machine.
  • Automatic memory.
    • Hooks capture what a session edited and ran, and write one redacted session episode at compaction and at session end.
    • Each prompt gets up to three relevant memories injected automatically.
    • The agent no longer has to remember to save or search.
  • See File Reservations and Automatic Capture.

What's New in 0.4 — Agentic, Multi-Machine, Team-Ready

0.4 was rebuilt from three months of daily use with Claude Code and Codex (320 episodes, 28 projects, ~500 agent tool calls). See Gap Analysis and Plan for the evidence.

  • One engine behind every entry point. stdio MCP, HTTP MCP, REST, CLI and hooks all get redaction, supersession, indexing, leases and metrics. (In 0.3 the MCP path, 98% of real writes, bypassed them.)
  • Current MCP. 2026-07-28 stateless (server/discover, per-request _meta) and the 2024-11-05…2025-11-25 handshake; tool annotations, outputSchema/structuredContent, server instructions, resources and a continuum_start prompt. Verified with the official MCP SDK client over stdio and Streamable HTTP.
  • Leases that actually exclude. CAS-backed, renewable, named resources, monotonic fencing tokens. In a 24-process race 0.3 let all 24 "win"; 0.4 lets exactly one.
  • Recall that pays for itself. BM25 plus optional semantic ranking, a relevance floor, snippets, token budgets and cross-project search. On the real corpus, natural-language queries went from 50% to 96% Recall@1 with about 5x fewer tokens at p95.
  • Shared across machines and teams. An S3 backend using only conditional writes (no DynamoDB), an offline outbox, repo-committed config, git-remote project ids, and S3 Vectors + Bedrock embeddings. See Teams on S3.
  • Fault tolerant locally. Atomic writes, immutable append-only episodes (safe in OneDrive/Dropbox/iCloud), conflict-copy detection, and a self-healing local index. Run continuum doctor.
  • Live dashboard at /dashboard: every memory and its history, measured token savings, recall hit rate, leases, agents and health. It keeps showing the last good data through outages. See Dashboard.
  • New tools: context_get, task_start/task_finish, state_patch, memory_write/memory_get/memory_invalidate, lock_renew/lock_status, projects_list/project_resolve. All 0.3 tool names still work.

Architecture

What It Provides

State and concurrency

  • state.json API for semantic project summaries, branches, dependency maps, and known bugs.
  • Lock API for preventing concurrent agents from clobbering the same project.
  • lineage and serial checks to reject stale state pushes.

Memory intelligence

  • Hybrid memory retrieval that fuses keyword (BM25) and vector similarity via reciprocal rank fusion, with a zero-dependency default embedder and optional sentence-transformers/OpenAI adapters.
  • Extraction and consolidation that distills raw logs into compact summaries and deduplicates near-identical episodes (ADD / UPDATE / SKIP).
  • Temporal validity so a superseded fact is invalidated rather than duplicated, preserving the timeline of what was true when.
  • A lightweight knowledge graph for entity and relationship (multi-hop) recall, with temporal edges.
  • Automatic redaction of secrets and PII before any memory is persisted.
  • Observability metrics (recall hit-rate, estimated tokens saved) and a recall@k evaluation harness.
  • A prompt-cache-aware context assembler that orders content most-stable-first for maximum provider cache reuse.
  • A procedural-memory template library for repeated Terraform/AWS/Databricks workflows.

Storage

  • Local filesystem backend with a SQLite memory index and usage dashboard for development.
  • AWS backend shape for S3 state/memory objects and DynamoDB lock rows, with optional at-rest payload encryption.
  • Postgres + pgvector backend and an embedding-aware wrapper that wires any vector store to the pluggable embedder.
  • Pluggable backend strategy so S3 Vectors is optional, not required.

Open-Source Principles

  • Vendor-neutral core protocol.
  • Storage adapters instead of hard-coded infrastructure.
  • Public design notes for schema, locking, and compatibility changes.
  • Small, inspectable state objects that can be pulled, reviewed, backed up, and migrated.
  • Maintainer governance that can grow into a broader community model.

Install

pip install cloudtantrix-continuum

This installs two executables:

  • continuum — the local workflow CLI (init, task-start, task-finish, search, dashboard, and more).
  • continuum-mcp — the stdio MCP server for Claude Code, Cursor, Copilot/VS Code, Codex, and other MCP clients.

Or run either without installing, via uv:

uvx --from cloudtantrix-continuum continuum init
uvx --from cloudtantrix-continuum continuum-mcp

Zero-Config Setup for Claude Code

One command configures a project end to end — no further manual steps:

continuum init --agent claude --write-agent-config

This writes everything Claude Code needs and wires it to run automatically every session:

  • .mcp.json — registers the continuum-mcp server (absolute executable path, so it works without an activated venv), merged non-destructively with any MCP servers you already have.
  • CLAUDE.md — memory-usage instructions loaded each session.
  • .claude/settings.json hooks — a SessionStart hook injects a compact memory context (project summary + recent memories) at the start of every session, and a Stop hook prevents a session from ending while a Continuum lock is still held, so learnings are always stored and locks released.

To register Continuum once for all your projects instead:

continuum install-claude-global --write

continuum --help documents the full workflow, token-savings tooling, and dashboard access.

Run as a Service

For an always-on backend that starts at boot and restarts automatically on failure:

continuum serve --port 8080                   # HTTP API + MCP on 127.0.0.1, foreground
continuum install-service --write             # macOS LaunchAgent / Linux systemd user unit
continuum doctor                              # backend, sync-conflict, index and service checks

Binding a non-loopback address requires a bearer token (CONTINUUM_AUTH_TOKEN, or the macOS keychain item continuum-http-token). Requests from non-local browser origins are rejected. Per-request access logging is off by default.

Run Locally

Try the dependency-free local workflow first:

./install-local.sh

This one-command bootstrap discovers a usable Python 3.10+ interpreter, runs local init, configures Codex globally when codex is installed, and verifies the MCP server. Use ./install-local.sh --skip-codex-global if you do not want it to write ~/.codex/config.toml.

The lower-level checkout commands remain available:

./scripts/continuum.py init
./scripts/continuum.py identify
./scripts/continuum.py demo --reset
./scripts/continuum.py index-local
./scripts/continuum.py search-local "S3 Vectors adapter" --mode hybrid
./scripts/continuum.py dashboard --port 8765

A typical task cycle, with consolidation, redaction, and graph relations:

# Acquire a lock and surface relevant memory
./scripts/continuum.py task-start "Diagnose the Databricks job failure" --agent codex

# Finish: extract a summary from a raw log, record a relationship, release the lock.
# Secrets and PII are redacted automatically before anything is stored.
./scripts/continuum.py task-finish --lock-id "$LOCK_ID" \
  --raw-log-file run.log \
  --relation "job:etl-nightly:runs-on:cluster:prod-shared" \
  --path jobs/etl_nightly.py

# Replace a stale memory; the old one is invalidated, not duplicated
./scripts/continuum.py task-finish --lock-id "$LOCK_ID" \
  --summary "Cluster count is now seven" --supersedes "$OLD_EPISODE_ID"

Inspect relationships, recall quality, and savings:

./scripts/continuum.py graph-neighbors --type job --name etl-nightly --depth 2
./scripts/continuum.py graph-stats
./scripts/continuum.py metrics
./scripts/continuum.py eval-recall --cases cases.json --k 5 --mode hybrid

Seed reusable safe processes, assemble cache-friendly context, and emit schemas:

./scripts/continuum.py templates                 # list built-in procedural templates
./scripts/continuum.py install-template --all     # seed them as procedural memory
./scripts/continuum.py context "Diagnose the failure" --format anthropic
./scripts/continuum.py schemas --write docs/schemas

Local data is written under .remote-state/ by default.

Memory Intelligence

Continuum keeps run-start context small and retrieves detail only when relevant.

  • Hybrid retrieval. Recall fuses full-text (SQLite FTS5 / BM25) and vector cosine similarity with reciprocal rank fusion, so a memory surfaces if either signal ranks it highly. The default embedder is deterministic and dependency-free; sentence-transformers and OpenAI adapters are optional and loaded lazily, never required by the core.
  • Consolidation. Raw logs are distilled into compact, high-signal summaries. New memories are compared against existing ones and either added, used to supersede a near-duplicate, or skipped, which keeps recall both cheaper and more accurate over time.
  • Temporal validity. Memories and graph edges carry valid_at/invalid_at. Superseding a memory invalidates it (and the relationships it asserted) rather than deleting history, and invalidated entries are excluded from recall.
  • Knowledge graph. A dependency-free SQLite graph stores entities and relationships (modules, accounts, jobs, clusters, files) for multi-hop recall.
  • Redaction. A configurable rule set removes secrets, keys, tokens, private keys, emails, account IDs, and similar values before persistence. It is on by default.
  • Observability and evaluation. Recall and store events are recorded so metrics can report recall hit-rate and estimated tokens saved, and eval-recall measures recall@k against labelled cases.

Bind an agent during init:

./scripts/continuum.py init --agent codex --write-agent-config --dashboard

Configure Codex once for all repos:

./scripts/continuum.py install-codex-global --write

Generate AWS/S3 Vectors configuration without storing secrets:

./scripts/continuum.py init --backend aws --vector-backend s3vectors

Run the API server:

python -m venv .venv
. .venv/bin/activate
pip install -e ".[dev]"
uvicorn continuum.server.main:app --reload

Key Endpoints

  • GET /health
  • GET /projects/{project_id}/state
  • PUT /projects/{project_id}/state
  • POST /projects/{project_id}/locks
  • DELETE /projects/{project_id}/locks/{lock_id}
  • POST /projects/{project_id}/episodes
  • GET /projects/{project_id}/memories/search?q=...
  • PATCH /projects/{project_id}/state — RFC 7386 merge patch with compare-and-swap
  • GET /projects, GET /doctor
  • POST /mcp — MCP Streamable HTTP (JSON responses); GET /mcp returns 405 to SSE clients

Remote MCP for Fleets

Agents can connect over stdio locally or over HTTP for hosted/team setups. The POST /mcp endpoint speaks the same MCP protocol and tool set as the stdio server, so behavior is identical across transports. Point an agent at a running server:

# Local stdio (Claude Code, Cursor, Copilot/VS Code, generic MCP, Codex)
./scripts/continuum.py install-agent cursor --write

# Remote HTTP endpoint for a shared deployment
./scripts/continuum.py install-agent claude --remote-url https://memory.example.com/mcp --write

install-agent writes the correct config location per client (.mcp.json for Claude Code and generic MCP, .cursor/mcp.json for Cursor, .vscode/mcp.json for Copilot/VS Code, and ~/.codex/config.toml for Codex).

State writes increment serial. If the submitted lineage or serial does not match the current remote state, the API returns 409 Conflict. Use ?force=true only for manual recovery workflows after pulling and backing up the current state.

AWS Mode

continuum team-init --bucket my-agent-memory --region us-east-1 --write   # commits .continuum/config.json
# or, per machine/server:
CONTINUUM_BACKEND=s3 CONTINUUM_S3_BUCKET=my-agent-memory AWS_REGION=us-east-1 continuum serve

State, leases and memory live in one S3 prefix. Coordination uses S3 conditional writes (If-Match / If-None-Match), so no DynamoDB table is needed. Writes made offline are queued and replayed. See Teams on S3 for the IAM policy and a GitHub Actions example.

Backend Portability

The project should run locally, on AWS, on S3-compatible object stores, on Azure, on GCP, or on Postgres. S3 Vectors is an optional vector adapter. Users who do not have it can use local keyword search, pgvector, Azure AI Search, OpenSearch, Qdrant, LanceDB, Milvus, Weaviate, or another adapter behind the same memory search contract.

Project Docs

Metadata

Release files for cloudtantrix-continuum 0.5.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for cloudtantrix-continuum 0.5.0
File Size Uploaded Provenance Actions
cloudtantrix_continuum-0.5.0.tar.gz 168.2 kB With provenance Details for cloudtantrix_continuum-0.5.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for cloudtantrix-continuum 0.5.0
File Interpreter ABI Platform Actions
cloudtantrix_continuum-0.5.0-py3-none-any.whl Python 3 none any Details for cloudtantrix_continuum-0.5.0-py3-none-any.whl

Total release size: 319.6 kB

Release files / cloudtantrix_continuum-0.5.0.tar.gz

Download URL cloudtantrix_continuum-0.5.0.tar.gz
Size 168.2 kB
Tags Source
SHA-256 checksum
How to use checksums
c587775153bb31adce2b0f2c37d25a1322963f21ec892f348c9b87567f630ef4
BLAKE2b-256 checksum
How to use checksums
593539dacf2267c5df421b77f6038446acf2f50002f4c31808ad856ed859d45c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 31, 2026.

Transparency log

Release files / cloudtantrix_continuum-0.5.0-py3-none-any.whl

Download URL cloudtantrix_continuum-0.5.0-py3-none-any.whl
Size 151.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
435c2b969c92e4fb0b3a0082478d201c58db4525bd90c1978d73d8519608075c
BLAKE2b-256 checksum
How to use checksums
9cd73898296bed663e590acdef449624080f32db024b2867c91e6b53b03b5be4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 31, 2026.

Transparency log

Security for cloudtantrix-continuum 0.5.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for cloudtantrix_continuum-0.5.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 31, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page