Polymath Zero

Docs · Memory

Regression memory

When a Work item resolves, Zero writes a regression memory entry — a structured record of the problem, root cause, fix, and proof. When a similar problem appears later, you search before you dig.

What regression memory is

Regression memory is a local index of resolved Work items, indexed by symptom, root cause, and outcome. It is not a log — it is a searchable knowledge base that grows as your team resolves Work.

Each entry is a structured file describing what happened, what was found, what was changed, and what verified it. Entries are never generated by AI — they are written by Zero from the verified data in a resolved Work item.

How it’s populated

Regression memory is written automatically when a Work item reaches RESOLVED with at least one verified proof attached. Zero extracts:

  • The Work item title and description
  • Root cause summary from final-classification.md
  • Outcome classification (ConfirmedCodeBug, IntendedBehavior, etc.)
  • Proof file references (test logs, diffs, traces)
  • Session count and total duration
  • Resolution date
  • Repository path (if linked)

No manual entry is required. Resolving a Work item with proof automatically creates the memory record.

File format

Each regression memory entry is stored as a markdown file at:

zero-memory/cases/{id}/final-classification.md

Example entry:

---
id: 0b58176d-fe15-451b-965b-1e053e130d36
title: Auth token refresh fails under concurrent requests
outcome: ConfirmedCodeBug
resolved: 2026-03-14
root_cause: Race condition in token refresh — two concurrent requests both
  found token expired, both triggered refresh, second response overwrote first.
fix_summary: Added mutex lock around token refresh path in auth.rs.
proof:
  - type: test-log
    file: sessions/s003/test-output.txt
  - type: diff
    file: sessions/s003/diff.patch
repository: ~/projects/myapp
---

## Root cause

Race condition in token refresh handler. When two requests arrive within the
refresh window, both see the token as expired and both attempt refresh. The
second response silently overwrites the first token, invalidating active sessions.

## Fix

Mutex lock around the token refresh code path. First request to acquire the
lock performs the refresh; subsequent requests wait and use the updated token.

## Proof

23/23 auth tests pass. Concurrent load test (50 req/s) shows no token
invalidation under sustained load. See attached test log.

Three ways to search regression memory:

  1. Recall panel. Open the Recall panel in the desktop app (⌘K, then type your query). Results are ranked by keyword overlap with title, root cause, and fix summary.
  2. API. Query regression memory programmatically: GET /regression-memory?q=auth+timeout. Returns matching entries sorted by recency.
  3. Shell search. Because entries are local markdown files, you can search directly:
    grep -r "auth timeout" ~/project/zero-memory/cases/

Search is keyword-based across local memory files — not a remote semantic index. All matching happens on-device.

Recall on new Work

When you create a new Work item, Zero searches regression memory for similar past Work items and surfaces them in the “Similar cases” panel before your first session starts. This surfaces:

  • Root cause summaries from similar resolved Work
  • Which sessions were most productive
  • What proof was attached
  • Whether the outcome was a code change or an investigation finding

This is the recall loop: resolve Work with proof → memory is written → future Work surfaces that memory → fewer re-investigations.

Non-code outcomes

Regression memory includes Work items that resolved without a code change — IntendedBehavior, Unreproducible, EnvironmentIssue, and others. These are often the most valuable entries: they record what was investigated and ruled out, preventing re-investigation of the same dead ends.

Example. A Work item resolved as Unreproducible — the memory records what was checked, under what conditions, and what was not found. The next engineer who files the same symptom sees this history immediately.

Memory is local

Regression memory is stored locally in your workspace. It is never sent to a remote index. Your case history stays on your machine.

On the Team plan, memory can be exported and shared across a workspace. See Export.

Exporting memory

On the Team plan, resolved Work items and their memory entries can be exported as JSON + markdown for team-wide sharing or archiving.

zero export --format json --output ./zero-export.json

The export includes: case metadata, session summaries, proof references, and the full final-classification for each resolved Work item.

Related: Case memory files, Proof and evidence, Outcomes explained.