Metadata-Version: 2.4
Name: cloudtantrix-continuum
Version: 0.1.1
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.34
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"
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 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
```

## 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=...`
- `GET /mcp` and `POST /mcp` — remote MCP transport (JSON-RPC over HTTP)

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

Set these environment variables:

```bash
BACKEND_DRIVER=aws
AWS_REGION=us-east-1
STATE_BUCKET=my-agent-state-bucket
LOCK_TABLE=my-agent-locks
```

The AWS adapter stores state and memory payloads in S3 and uses DynamoDB conditional writes with TTL fields for lock acquisition.

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

- [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)
