continuum-recall 0.1.1

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

Status: v0.1.1 beta — installable and tested; schema may change before v1.0. Report 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:

# 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

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.1
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.905	0.866	0.967
structured_state	0.844	0.744	0.767
recent_messages	0.745	0.663	0.745
naive_summary	0.745	0.663	0.745
rolling_summary	0.745	0.663	0.745
vector_retrieval	0.682	0.632	0.653

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 →

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.

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.

CLI

Command	What it does
continuum init	Initialise workspace (creates .continuum/)
continuum add "<text>"	Ingest a manual event and run review
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

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

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