continuum-recall 0.1.3

Structured memory for AI coding agents that records what breaks if context is forgotten.

Status: v0.1.3 beta — installable and tested; schema may change before v1.0. Report issues.

Continuum

Memory should prevent failure.

Continuum is a structured memory system for AI coding agents. Its consistent measured advantage in ContinuumBench 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:

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

Benchmark (summary)

Measured on the license-decision-history fixture from ContinuumBench — a hand-authored fixture of a real licensing discussion, scored against six methods including structured state dumps, summarization, and vector retrieval:

Method	Failure Prevention Rate	Rejected Path Avoidance
continuum	0.937	1.000
structured_state	0.797	1.000
rolling_summary	0.725	0.000
vector_retrieval	0.662	0.000

Failure Prevention Rate is the one metric Continuum reliably wins. On retrieval and decision recall, a flat structured state dump is competitive. Full 12-metric results → | Methodology →

Install

pip install continuum-recall

For the full install including vector similarity search:

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.
• A secret store. Raw events are appended to events.jsonl verbatim before any validation. The sensitivity scanner prevents credential patterns from entering active state, but the raw event log on disk is not redacted. Do not ingest real credentials.

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 or Zep. If you need a full agent framework with runtime memory management, look at Letta. If you need a long-context conversational memory benchmark, look at LongMemEval.

Full prior-art comparison →

Five-Minute Quickstart

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

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.

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:

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.

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

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

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

python -m pip install continuum-recall==0.1.3
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 → | Benchmark methodology →

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 about a commercial license.

Why not MIT or Apache? That decision is in the project's own memory.

---

• Documentation: https://gutsy03.github.io/continuum/
• Repository: https://github.com/gutsy03/continuum
• Issues: https://github.com/gutsy03/continuum/issues