Metadata-Version: 2.4
Name: cloudtantrix-continuum
Version: 0.4.0
Summary: Open remote state and memory backend for AI coding agents.
Author: CloudTantrix
License: MPL-2.0
Project-URL: Homepage, https://github.com/CloudTantrix/Continuum
Project-URL: Repository, https://github.com/CloudTantrix/Continuum
Project-URL: Issues, https://github.com/CloudTantrix/Continuum/issues
Project-URL: Documentation, https://github.com/CloudTantrix/Continuum/tree/main/docs
Keywords: ai-agents,mcp,memory,remote-state,model-context-protocol,claude-code,codex
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Mozilla Public License 2.0 (MPL 2.0)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: boto3>=1.36
Requires-Dist: fastapi>=0.111
Requires-Dist: pydantic>=2.7
Requires-Dist: pydantic-settings>=2.2
Requires-Dist: uvicorn[standard]>=0.29
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: httpx>=0.27; extra == "dev"
Requires-Dist: pytest>=8.2; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Requires-Dist: moto[s3]>=5.1; extra == "dev"
Requires-Dist: mcp>=2.3; extra == "dev"
Provides-Extra: bedrock
Provides-Extra: semantic
Requires-Dist: sentence-transformers>=3; extra == "semantic"
Dynamic: license-file

<p align="center">
  <img src="https://raw.githubusercontent.com/CloudTantrix/Continuum/main/assets/continuum-mark.svg" alt="Continuum logo" width="220">
</p>

# 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.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](docs/gap-analysis-2026-10.md) 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](docs/team-s3.md).
- **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](docs/dashboard.md).
- **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](docs/diagrams/architecture.png)

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

```bash
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](https://docs.astral.sh/uv/):

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

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

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

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

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

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

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

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

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

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

Configure Codex once for all repos:

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

Generate AWS/S3 Vectors configuration without storing secrets:

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

Run the API server:

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

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

```bash
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](docs/team-s3.md) 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

- [Gap Analysis and Plan (Oct 2026)](docs/gap-analysis-2026-10.md)
- [Dashboard](docs/dashboard.md)
- [Diagrams (Lucid sources + snapshots)](docs/diagrams/README.md)
- [Teams, Multiple Machines and CI on S3](docs/team-s3.md)
- [Competitive Strategy](docs/competitive-strategy.md)
- [Architecture](docs/architecture.md)
- [Continuum Init](docs/init.md)
- [Backend Strategy](docs/backends.md)
- [First-Class Use Cases](docs/use-cases.md)
- [Freshness And Safety](docs/freshness.md)
- [Production Architecture](docs/production-architecture.md)
- [Token Economics](docs/token-economics.md)
- [Local Vector And Dashboard](docs/local-vector-dashboard.md)
- [AWS S3 Vectors](docs/aws-s3vectors.md)
- [Agent-Native Install](docs/agent-install.md)
- [Automatic Agent Integration](docs/agent-automation.md)
- [Memory Model](docs/memory-model.md)
- [Local Workflow](docs/local-workflow.md)
- [Testing with Codex](docs/codex-testing.md)
- [Roadmap](ROADMAP.md)
- [Contributing](CONTRIBUTING.md)
- [Governance](GOVERNANCE.md)
- [Security](SECURITY.md)
