RegimeBank

RegimeBank gives a lifelong agent separate memories for operating regimes that can disappear and later return.

Most memory policies assume that recent experience is always the most relevant. That assumption breaks on streams such as API v1, API v2, then API v1 again. A sliding window must relearn the first API. A global memory can mix incompatible procedures. RegimeBank detects the change, keeps the memories separate, and reactivates the earlier bank when the first regime returns.

The repository is runnable on a laptop. It includes a recurring contextual-bandit benchmark, Bayesian online change-point detection, regime-aware memory, six baselines, an oracle, metrics, plots, tests, and a JSONL adapter for real agent traces.

What is implemented

• Bayesian online change-point detection with a multivariate Student-t predictive model
• Episodic memory for concrete task, action, and outcome records
• Procedural memory with one regularized reward model per action
• An invariant pool for action evidence validated in more than one regime
• Regime reactivation from learned signal prototypes
• Posterior-weighted retrieval when regime identity is uncertain
• Bank merging only after validation succeeds in both directions
• Abrupt, gradual, cyclic, and recurring schedules
• API, tool-schema, and hidden-transition synthetic domains
• Global, sliding-window, reservoir, periodic-deletion, exponential-decay, and oracle baselines
• Prequential and recurrence-focused evaluation
• Reproducible CSV, JSON, and PNG artifacts

Quick start

RegimeBank requires Python 3.11 or newer.

python -m venv .venv

# Windows
.venv\Scripts\activate

# macOS and Linux
source .venv/bin/activate

python -m pip install -e ".[dev]"
regimebank run --config configs/aba.toml --output artifacts/latest

For a short smoke test:

regimebank run --config configs/aba.toml --output artifacts/quick --quick

The command writes:

artifacts/latest/
  benchmark.png
  metrics_by_run.csv
  metrics_summary.csv
  summary.json
  trace.csv

Expected behavior

The default schedule has three equal segments:

alpha -> beta -> alpha

The first boundary is a new regime. The second boundary is a recurrence. RegimeBank should create a new bank at the first boundary and reactivate the original alpha bank at the second boundary.

The benchmark is useful when these conditions hold:

1. RegimeBank recovers faster on the returning alpha segment than a sliding window or periodic deletion policy
2. Alpha memories do not dominate decisions during beta
3. Dynamic regret remains below the global-memory baseline
4. Change alarms stay close to true boundaries

Treat these as behavioral checks, not guaranteed research conclusions. Results depend on the schedule, seed set, memory capacity, and detector settings.

Architecture

flowchart LR
    A["Streaming task signals"] --> B["Bayesian change detector"]
    B --> C["Regime posterior"]
    C --> D["Episodic banks"]
    C --> E["Procedural banks"]
    D --> F["Posterior-weighted retrieval"]
    E --> F
    G["Invariant memory"] --> F
    F --> H["Action scores"]
    H --> I["Outcome feedback"]
    I --> A
    I --> D
    I --> E
    I --> G

Loading

Each detector signal contains:

tool-schema fingerprint
task embedding
previous outcome
transition prediction error
memory agreement

The synthetic environment produces all five signals. A real agent can provide the same normalized event shape through the JSONL adapter.

Memory routing

At every step, the agent updates the run-length posterior. A detected change triggers one of two paths:

1. Reactivate an existing bank when its signal prototype receives enough posterior mass
2. Create a new bank when no previous regime is a credible match

Retrieval remains weighted across banks while the posterior is uncertain. The system does not force an early hard assignment.

Bank merging is conservative. Two inactive banks merge only when prototype similarity is high and each procedural model predicts the other bank's held-out episodes with sufficient accuracy.

See docs/design.md for the model and implementation details.

Benchmark configurations

Config	Domain	Schedule	Purpose
configs/aba.toml	API	Abrupt A-B-A	Main recurrence test
configs/gradual.toml	API and dynamics	Gradual A-B-A	Slow adaptation test
configs/transition.toml	Hidden transition	Abrupt A-B-A	Outcome-driven detection

All environments are synthetic and generated locally. No external benchmark data is distributed.

Metrics

The runner reports:

• Prequential success
• Mean reward
• Dynamic regret
• Change-detection delay
• False alarms
• Recovery time
• Recurrence gain
• Backward transfer
• Forward transfer
• Post-hoc regime identification accuracy
• Mean and final storage
• Retrieval token proxy

Metrics are calculated for every seed and then aggregated with the standard error.

Use real agent traces

Export one JSON object per line:

{
  "step": 0,
  "task_embedding": [0.21, -0.08, 0.44],
  "tool_schema": {"name": "lookup", "arguments": {"query": "string"}},
  "outcome": 1.0,
  "transition_error": 0.05,
  "memory_agreement": 0.91,
  "metadata": {"request_id": "local-0001"}
}

Validate the stream before integrating it:

regimebank validate-stream examples/events.jsonl

Tool schemas are canonicalized before hashing, so key order does not change the fingerprint. Embeddings must have a consistent dimension across the stream.

Python API

from regimebank import ExperimentConfig, run_experiment

config = ExperimentConfig.from_toml("configs/aba.toml")
result = run_experiment(config, "artifacts/latest")

for row in result.aggregate_metrics:
    print(row["agent"], row["prequential_success_mean"])

Development

python -m pip install -e ".[dev]"
pytest
ruff check .

The test suite covers detector normalization, abrupt shift detection, recurrence reactivation, canonical schema fingerprints, JSONL validation, and the full artifact pipeline.

Scope

This release is an engineering reference for recurrence-aware memory. It is not a production policy for autonomous decisions and it does not include integrations that require redistribution of third-party code or datasets.

The adapter boundary is intentionally small. Connectors for larger agent systems can translate their traces into StreamEvent without changing the detector or memory implementation.

Provenance and license

The repository contains only original implementation code and generated synthetic outputs. It does not package source papers, third-party archives, figures, or datasets. See NOTICE.md for the provenance statement.

RegimeBank is available under the MIT License.