Memory and history

Every run leaves evidence behind in its run folder. Circuit indexes those past runs so a later run can recall what earlier ones produced, instead of starting cold.

Recall draws on two stores. The history index is built from past run folders: their evidence, reports, traces, and checkpoints. Project memory is a local store of durable notes you file about a flow, each one citing a real run artifact.

Recalled memory is hint-only. It orients the next run; it never overrides the flow's own checks.

Recall at run start

When you run a flow, Circuit recalls hints before the first step and hands them to the worker. It gathers candidates from both stores, ranks them against your goal, weighs them against what past runs measured, and keeps a small budget: three hints by default.

Ranking by your goal

Candidates are ranked by how well their text matches your goal. A note about the dashboard filter outranks a note about auth tokens when your goal is a dashboard change.

Prior-run hits are always ranked this way. To rank project notes by the same relevance score, so a matching note leads instead of riding in the order you filed it, set CIRCUIT_RANK_PROJECT_FACTS=1. Without it, project notes keep their filed order.

What gets kept

Before the budget is filled, Circuit weighs each candidate against what earlier runs measured. A hint that past runs measured as making outcomes worse is dropped. A hint whose cited source has changed, or can no longer be verified, sinks below the fresh ones. The rest fill the budget, best first.

So recall sharpens over time. A hint earns its slot by matching the goal and not correlating with worse outcomes, and the budget stays small.

Querying history

Search the index for prior work:

circuit history query 'flaky auth test' --json

During a flow, pull memory scoped to a single decision point. The pull narrows to one flow, suppresses hints that past runs measured as unhelpful, and logs what it surfaced to the run folder:

circuit history pull 'auth retry' --flow fix --decision-point plan --run-folder .circuit/runs/<run> --json

Check or rebuild the index:

circuit history status --json
circuit history rebuild --json

History commands print JSON and require --json.

Operator notes

Record a durable note about a flow, citing the latest run:

circuit memory note 'prefer the retry helper over a raw loop' --flow fix

Review or remove notes with circuit memory list and circuit memory forget <memory-id>.

Analysis reports

The history command also builds analysis reports: memory-merge consolidates recalled memory, and memory-effect measures whether recalled hints changed run outcomes. Pass --write to persist either report under the index directory.