Metadata-Version: 2.4
Name: continuum-recall
Version: 0.1.2
Summary: Structured memory for AI coding agents that records what breaks if context is forgotten.
Project-URL: Homepage, https://github.com/gutsy03/continuum
Project-URL: Documentation, https://gutsy03.github.io/continuum/
Project-URL: Repository, https://github.com/gutsy03/continuum
Project-URL: Issues, https://github.com/gutsy03/continuum/issues
Author: Continuum Contributors
License-Expression: AGPL-3.0-or-later
License-File: LICENSE
Keywords: agents,ai,context,continuity,memory,rag
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
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
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: python-dateutil>=2.9
Requires-Dist: rich>=13.0
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: build>=1.0; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest-mock>=3.12; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Requires-Dist: twine>=5.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material<9.7,>=9.5; extra == 'docs'
Requires-Dist: mkdocs>=1.6; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.25; extra == 'docs'
Provides-Extra: sqlite
Requires-Dist: sqlite-vec>=0.1; extra == 'sqlite'
Provides-Extra: vectors
Requires-Dist: sentence-transformers>=3.0; extra == 'vectors'
Description-Content-Type: text/markdown

> **Status: v0.1.2 beta** — installable and tested; schema may change before v1.0. [Report issues.](https://github.com/gutsy03/continuum/issues)

# Continuum

**Memory should name the failure it prevents.**

Continuum is a structured memory system for AI coding agents. Its measured advantage over structured state dumps, ADRs, Mem0, and summarization-based approaches is one thing: it reliably surfaces the specific failure that would occur if a piece of context were forgotten — the `failure_if_forgotten` signal. On recall and retrieval, a flat structured state renderer is competitive. Continuum's edge is knowing what breaks, not just what was decided.

## The Problem

Long coding sessions fail in a predictable pattern. The agent summarizes what happened and moves on. Three hours later it forgets that Apache 2.0 was explicitly rejected for license-incompatibility reasons, and suggests it again. Or it correctly remembers "use AGPL" but forgets *why* — and the next task quietly adds a dependency that violates it.

Summaries lose failure context. Continuum keeps it.

## What Continuum Stores

Most memory systems store what happened. Continuum stores what must not be forgotten and why:

```python
# Typical memory system
{"content": "The project uses AGPL"}

# A Continuum item for the same fact
{
  "type":    "decision",
  "title":   "AGPL-3.0 chosen as project license",
  "content": "Use AGPL-3.0 for strong copyleft and the network-use clause that closes the SaaS loophole.",
  "rationale": "Apache/MIT/MPL were rejected: Apache and MIT are permissive; MPL is file-level copyleft only.",
  "continuity_tests": [
    {
      "question":     "What is the project license?",
      "must_include": ["AGPL-3.0"],
      "must_avoid":   ["Apache", "MIT", "MPL"]
    }
  ],
  "causal_impact_score": 0.92
}
```

The item records the rejected alternatives and the specific failure that forgetting would cause. A reviewer model may propose this item, but a deterministic validator pipeline decides whether it enters durable state.

## Install

```bash
pip install continuum-recall
```

For the full install including vector similarity search:

```bash
pip install "continuum-recall[vectors]"
```

`sentence-transformers` (and PyTorch, ~1 GB) are optional. The base install gives you everything except vector scoring in `search`. The rule-based path — `init`, `add`, `review`, `state`, `packet`, `test` — works without it.

The PyPI distribution name is `continuum-recall`. The import name is `continuum`.
Do not install `continuum-memory`; that is a different PyPI project with the
same top-level import name.

## What This Is Not

Continuum does not replace:
- **A general knowledge base.** It stores typed project continuity items, not arbitrary documents.
- **A production memory service.** It is a local, file-backed tool. No hosted API.
- **A graph runtime.** It has no agent execution framework.
- **Your project docs.** It complements ADRs and wikis; it does not replace them.

On decision recall, constraint retention, and rationale recall, a flat structured state dump is competitive with Continuum. If you only need retrieval, `structured_state` may be sufficient and simpler. Continuum's case is specifically for teams that want failure-prevention annotations, ablation scores, deterministic continuity tests, and an auditable validator pipeline — not just recall.

If you need a hosted memory service with integrations, look at [Mem0](https://docs.mem0.ai/) or [Zep](https://help.getzep.com/v2/memory). If you need a full agent framework with runtime memory management, look at [Letta](https://docs.letta.com/concepts/memory-management). If you need a long-context conversational memory benchmark, look at [LongMemEval](https://arxiv.org/abs/2410.10813).

[Full prior-art comparison →](docs/prior-art.md)

## Five-Minute Quickstart

No Ollama, no API key, no GPU. The default reviewer is rule-based.

```bash
continuum init
continuum add "We decided to use AGPL-3.0-or-later."
continuum add "We rejected Apache 2.0 because it is permissive and has no copyleft."
continuum add "We rejected MIT because it allows closed-source derivatives without contributing changes back."
continuum review
continuum state
continuum packet --task "write the README license section"
```

The final command prints a ranked context packet — only items relevant to the task, structured so an agent sees what was decided and what was rejected before it writes anything.

Run `continuum test` to execute the continuity tests the reviewer stored alongside the items. They pass or fail deterministically without a model.

## Structured Template Mode

For predictable demos and scripts, `continuum add-template` bypasses natural-language extraction and creates typed memory items from explicit fields. Template events still go through the same append-only event log, deterministic validators, and merger as `continuum add`.

```bash
continuum init
continuum add-template decision --value "AGPL-3.0" --reason "it provides strong copyleft and closes the SaaS loophole"
continuum add-template rejection --option "Apache 2.0" --reason "it is permissive and has no copyleft"
continuum packet --task "Can we use Apache?"
```

Available templates:

```bash
continuum add-template decision --value "<decision>" --reason "<reason>"
continuum add-template rejection --option "<rejected option>" --reason "<reason>"
continuum add-template constraint --constraint "<constraint>" --reason "<reason>"
```

The packet places decisions under `## Decisions` and rejected options under `## Rejected Ideas`, including a `Why this matters` line for the failure that forgetting would cause.

## Benchmark

Three committed fixtures, six methods, 12 metrics. All numbers are from real runs. Full results are in [`bench/leaderboard.md`](bench/leaderboard.md).

From a cloned repo, `scripts/run_bench.py` is available and can write reports outside the fixture tree:

```bash
python3 scripts/run_bench.py --fixture license-decision-history --report-dir /tmp/continuum-bench
```

From an installed package, use only the packaged CLI commands:

```bash
python -m pip install continuum-recall==0.1.2
continuum bench list
continuum bench run --fixture license-decision-history
continuum bench report --fixture license-decision-history
```

**Failure Prevention Rate** (does the context surface the specific failure that forgetting would cause):

| Method | license-decision | dep-rejection | superseded-arch |
| --- | --- | --- | --- |
| **continuum** | **0.937** | **0.866** | **0.964** |
| structured\_state | 0.797 | 0.744 | 0.747 |
| recent\_messages | 0.725 | 0.663 | 0.738 |
| naive\_summary | 0.725 | 0.663 | 0.738 |
| rolling\_summary | 0.725 | 0.663 | 0.738 |
| vector\_retrieval | 0.662 | 0.632 | 0.656 |

This is the one metric Continuum reliably wins. It comes from `failure_if_forgotten` annotations on stored items.

**Rejected Path Avoidance** (does the context correctly frame rejected options as rejected, not as live choices):

| Method | license-decision | dep-rejection | superseded-arch |
| --- | --- | --- | --- |
| structured\_state | 1.000 | **1.000** | 1.000 |
| **continuum** | 1.000 | **0.000** | 1.000 |
| all raw-text baselines | 0.000 | 0.000 | 0.000 |

Continuum loses to `structured_state` on dep-rejection because the ContextPacketBuilder does not consistently place rejection framing adjacent to the rejected item's name token. `structured_state` wins there because it renders an explicit `## Rejected:` header. On the other two fixtures they tie.

**Supersession Accuracy** (does the context mark a superseded decision as superseded, not current):

All methods score 0.000 on the superseded-architecture fixture. No current implementation tracks supersession. That fixture establishes the floor.

[Full 12-metric results →](bench/leaderboard.md) | [Benchmark methodology →](docs/continuumbench.md)

## CLI

| Command | What it does |
| --- | --- |
| `continuum init` | Initialise workspace (creates `.continuum/`) |
| `continuum add "<text>"` | Ingest a manual event and run review |
| `continuum add-template decision --value "<decision>" --reason "<reason>"` | Add a deterministic decision item |
| `continuum add-template rejection --option "<option>" --reason "<reason>"` | Add a deterministic rejected-idea item |
| `continuum add-template constraint --constraint "<constraint>" --reason "<reason>"` | Add a deterministic constraint item |
| `continuum review` | Run review over the event log |
| `continuum state` | Show state summary (or `--json` for machine-readable) |
| `continuum packet --task "<task>"` | Build a ranked context packet for a task |
| `continuum search "<query>"` | BM25 + vector hybrid search over active items |
| `continuum test` | Run deterministic continuity tests |
| `continuum ablate <id> --task "<task>"` | Measure causal impact of one item |
| `continuum diff` | Show what changed since the last review |
| `continuum bench list` | List packaged benchmark fixtures |
| `continuum bench run --fixture <name>` | Run a benchmark fixture |
| `continuum bench report --fixture <name>` | Print a packaged benchmark report |

## Architecture

```
event log (events.jsonl)
    ↓
reviewer (rule-based or Ollama committee)
    ↓
validator pipeline (schema · evidence · specificity · sensitivity · contradiction)
    ↓
merger (add / update / supersede / resolve / ignore)
    ↓
state store (state.json — atomic writes)
    ↓
packet builder (ranked, token-budgeted context)
         + ablation engine (causal impact scores)
         + hybrid search (BM25 + vector)
```

The reviewer proposes; the validators decide. A candidate that fails any validator is logged to `ignored.jsonl` with the rejection reason and never enters state.

## License

AGPL-3.0-or-later. Commercial dual-license available for organizations that cannot ship AGPL software.

The AGPL choice is intentional: if you run Continuum as a service, the copyleft requirement applies. If that constraint is a problem for your use case, [contact us](https://github.com/gutsy03/continuum/issues) about a commercial license.

Why not MIT or Apache? [That decision is in the project's own memory.](src/continuum/bench/fixtures/license-decision-history/gold_state.json)

---

- Documentation: <https://gutsy03.github.io/continuum/>
- Repository: <https://github.com/gutsy03/continuum>
- Issues: <https://github.com/gutsy03/continuum/issues>
