> ## Documentation Index
> Fetch the complete documentation index at: https://docs.overcut.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Workflow Self-Improvement

> How Overcut reviews past workflow runs, creates memories, and refines what agents know over time.

## Overview

Workflow self-improvement turns completed workflow runs into reusable knowledge. Overcut periodically reflects on past runs, identifies patterns, and saves findings as [workflow memories](/docs/how-to/workflows/workflow-memory) so agents can apply those lessons in future runs.

Workflow-level self-improvement settings appear in the workflow dashboard's **Self-Improvement** panel. Open the panel's **Settings** dialog to control when automatic retrospectives run and how much eligible execution history each retrospective analyzes.

These workflow-level settings only apply when **Account → Settings → Auto-Improve Workflows** is enabled. When that workspace setting is off, the workflow dashboard shows a prompt that links you to workspace settings instead of running retrospectives.

## The retrospective process

A retrospective reviews one or more completed workflow runs and then:

1. **Investigates recent runs**: reads their steps, agent decisions, tool calls, and outcomes.
2. **Reviews tentative memories** from earlier retrospectives: promotes ones that show up again and discards ones that do not.
3. **Creates new memories** from patterns found in the runs.
4. **Adjusts memory weights** based on how existing memories performed.
5. **Produces a summary** of runs reviewed, findings, and memory changes.

Each retrospective creates its own run, so you can open it to read the findings and see exactly what changed.

## How retrospectives create memories

Retrospectives are the primary source of workflow memories. They write two kinds:

* **Active memories**: guidance Overcut is confident about. These are immediately available to agents in future runs.
* **Tentative memories**: single-occurrence observations that look useful but haven't been confirmed yet. A later retrospective promotes a tentative memory to active when it sees the same pattern again.

You can review both kinds on the workflow's **Memories** tab, filtered by **Status** (All statuses, Active, Tentative, Archived). The workflow dashboard also shows counts as **Active Memories** and **Pending Memories** (tentative).

<Tip>
  If a tentative memory looks correct and you don't want to wait for a second occurrence, use the **Confirm** action on the memory card to promote it to active immediately.
</Tip>

## Memory weights and scoring

Every memory has a **weight** that reflects how useful it has been. Retrospectives adjust this score based on what they observe:

* **Helpful memories**: weight goes up when a memory contributed to a successful run.
* **Harmful or misleading memories**: weight goes down when a memory led the agent in the wrong direction.
* **Unused memories**: weight decays slowly when a memory is never referenced.

When a memory's weight falls below the minimum threshold, Overcut automatically archives it. Archived memories stop influencing agents but remain visible under the **Archived** filter so you can restore them if they become relevant again.

Memory cards also show a use count so you can see how often each memory has been referenced.

## Automatic retrospectives

When **Auto-Improve Workflows** is enabled, Overcut runs retrospectives on its own after a workflow has accumulated enough completed or failed runs. No manual step is required. The next retrospective starts automatically and its result appears in the **Self-Improvement** panel on the workflow dashboard.

Open the **Settings** dialog in the **Self-Improvement** panel to configure two workflow-level values:

* **Cadence**: how many new completed or failed runs must accumulate before the next automatic retrospective starts.
* **Sample size**: what fraction of that eligible run window is analyzed in each retrospective.

For example, a cadence of `10` means Overcut waits for 10 new eligible runs before starting an automatic retrospective. A sample size of `0.5` means Overcut randomly analyzes about half of that window instead of reviewing every eligible run. Because analyzed runs are rounded to a whole number, the exact count is based on the configured window and sample size.

Automatic retrospectives run the full process: they investigate runs, create and update memories, adjust weights, and produce a summary.

<Info>
  Automatic retrospectives only run when the workspace-level toggle is on. If **Auto-Improve Workflows** is disabled, the workflow dashboard prompts you to enable it in workspace settings before you can use workflow-level self-improvement controls.
</Info>

### Settings dialog

The settings dialog shows two fields: **Run retrospective after N executions** (cadence) and **Sample size (0–1)**. A preview below the fields shows the effective analyzed-run count before you save.

Overcut validates settings before saving: cadence must be a whole number from `1` to `1000`, sample size must be between `0.01` and `1`, and the resulting analyzed run count cannot exceed `5` per retrospective. If a combination exceeds the limit, reduce cadence, sample size, or both.

## Manual retrospectives

You can start a retrospective yourself at any time. There are two entry points, and they behave differently.

### Run Now: a full manual retrospective

Use **Run Now** in the workflow dashboard's **Self-Improvement** panel when you want feedback sooner than the next automatic cycle: for example, after a release, after a major process change, or after a cluster of runs you want to learn from.

**Run Now** performs the same full retrospective as the automatic cycle: it investigates unreviewed runs, creates and updates memories, adjusts weights, and summarizes. The only difference is that you triggered it manually instead of waiting.

### Investigate: focused review of a single run

Use **Investigate This Run** from a workflow run's detail page when you want to analyze one specific run in depth: for example, to understand why a particular run failed or behaved unexpectedly.

Investigate opens a dialog where you can optionally provide a **Focus Question** (e.g., *"Why did this run fail at the deploy step?"*) to guide the analysis. Overcut then creates a retrospective on that single run and navigates you to it. Investigate can create new memories from findings in that run, but it intentionally skips the broader bookkeeping steps. It does not confirm tentative memories from earlier retrospectives and does not adjust weights on existing ones. This keeps Investigate safe to run repeatedly on the same run without compounding effects on existing memories.

## Manual run vs. automatic run

| Aspect                      | Automatic retrospective                      | Run Now (manual)                                  | Investigate (manual)                                        |
| --------------------------- | -------------------------------------------- | ------------------------------------------------- | ----------------------------------------------------------- |
| Trigger                     | Automatic, after enough runs accumulate      | User clicks **Run Now** in Self-Improvement panel | User clicks **Investigate This Run** on a run's detail page |
| Runs analyzed               | Unreviewed runs since the last retrospective | Unreviewed runs since the last retrospective      | The single run you selected                                 |
| Focus Question              | Not used                                     | Not used                                          | Optional: you can steer the analysis                        |
| Creates memories            | Yes                                          | Yes                                               | Yes (from findings in the selected run)                     |
| Confirms tentative memories | Yes                                          | Yes                                               | No                                                          |
| Updates memory weights      | Yes                                          | Yes                                               | No                                                          |
| Produces a summary          | Yes                                          | Yes                                               | Yes                                                         |
| When to use                 | Ongoing, hands-off learning                  | You want feedback on recent runs immediately      | You want to dig into one specific run                       |

<Tip>
  **Run Now** and the automatic retrospective are equivalent in what they change: both create memories, confirm tentative ones, and adjust weights. **Investigate** is narrower: it still captures lessons from the run as new memories, but leaves prior tentative memories and existing weights untouched. That makes it safe to run more than once on the same workflow run without repeatedly shifting the broader picture.
</Tip>

## Viewing retrospective results

Every retrospective, automatic or manual, creates its own run that you can open and inspect.

* The **Self-Improvement** panel on the workflow dashboard always shows the most recent retrospective and updates in real time when one is in progress.
* When automatic retrospectives are enabled, the panel also summarizes the configured cadence and sampling percentage.
* Click into the retrospective run to see the findings, the memories it created or updated, weight changes, and the final summary.
* Open the workflow's **Memories** tab to see the current set of active and tentative memories and their weights.

## Related documentation

* [Workflow Memory](/docs/how-to/workflows/workflow-memory): how agents use memories during runs
* [Workspace Settings](/docs/reference/workspace-settings): enable Auto-Improve Workflows
* [Workflow Version History](/docs/reference/workflow-history): drafts and published workflow versions