Harness memory & meta-cognition

Two stores, one purpose: capture what the harness has learned from your past runs, then use it to improve future ones.

Harness self-memory

Lives at ~/.cerevisor/memory/harness/. Auto-populated at end-of-run.

Three files:

• self.md: human-readable retrospective. What's been working, what hasn't, recent run log.
• self.json: structured data: per-role success rates, average cost, recurring patterns, error frequencies.
• corrections.ndjson: append-only log of every time you corrected the harness ("don't auto-add reviewers", "use the cheaper model for this role").

Visible in Memory view → Harness tab. Read-only: the harness manages this itself.

What it captures

After every workflow run, run-finalization.ts writes:

• Per-role metrics: how often each role succeeded, average cost, average duration.
• Recurring patterns: "Researcher agents have been failing on EU-domain queries 3 times in a row."
• Run log entry: one line per run with workflow name, status, cost, duration, what worked / didn't work.

The harness later reads this to surface tips ("You've spent $40 on Opus in the last week; switching to Sonnet would have produced the same output for $5") and to drive meta-cognition.

Meta-cognition

Lives at ~/.cerevisor/memory/meta-cognition/. Computed at end-of-run from a diff of harness-self snapshots.

Two files:

• observations.{md,json}: typed observations like "role X drift", "blind spot Y persistent", "pattern Z reversal", "run-log recurring theme".
• harness-self-portrait.{md,json}: a compiled reflective summary of "what I have learned about working with you."

Visible in Memory view → Reflection tab.

Observation kinds

Kind	When emitted
role_metric_drift	A role's success rate dropped by ≥10% across runs.
role_metric_recovery	Recovered after a drift.
role_new	First-ever observation for a previously-unseen role.
pattern_growth / pattern_stale / pattern_reversal	Patterns in the run log changing over time.
blind_spot_persistent	Same failure mode in 3+ consecutive runs.
blind_spot_resolved	A previously-persistent blind spot stopped occurring.
run_log_recurring_theme	Themes appearing in multiple run logs.
baseline	First-ever observation (single emission on first run).

The harness emits learned tips when a blind spot persists across 3+ runs. These show in the canvas as a badge on the affected agent or as a status-bar pill.

The self-portrait

The portrait has three sections:

• Learnings about user: 2-4 sentences describing what the harness has noticed about your preferences and patterns.
• Self-capabilities: 2-4 sentences on what the harness has been doing well lately.
• Enduring insights: up to 6 bullet-point insights that have repeated across runs.

The portrait is refreshed on every run by the same LLM call that writes the meta-cognition narrative, so no extra round-trip.

Toggling enrichment

Two related settings in Settings → Memory:

Setting	Default	Effect
Meta-cognition enrichment enabled	On	Whether the optional LLM call runs to produce the narrative + portrait. Detectors + observations always run regardless.
Inject memory into prompts	Off	Whether the narrative + observations are injected into every agent's system prompt at run time.

If you turn enrichment off, the harness still tracks observations; you just won't get the prose narrative. If you turn injection off, the data is still collected and visible in the Memory view but agents don't see it.

When meta-cognition skips

Meta-cognition skips its LLM call when:

• The current run's default provider is Codex CLI or Cursor Agent (no chat API).
• No provider is configured at all.
• No new observations were produced this run (nothing to narrate).

The reason is recorded so the Memory view can show why the portrait or narrative is stale.

Downstream consumers: the Situational Awareness pillar

The meta-cognition observations, the harness self-portrait, the disagreement records, and the per-role learnings are all read by Cerevisor's Situational Awareness pillar, which composes them into typed SituationSnapshot objects for the chat builder and the run drawer. SA does not duplicate this subsystem; it presents the same data through a different lens (taskwork / agent / teamwork slices, with belief attribution and context-freshness scoring).

In practice this means: when the harness-memory entries grow stale, drift across runs, or contradict each other, the SA panels will surface that explicitly (context-stale or fixation-risk state labels, "verifier rejected" badges on agents, open disagreements in the Teamwork slice). If you want to understand why an SA badge looks the way it does, the answer almost always lives in the memory artifacts described above.

Resetting

If the harness's learned state has drifted in a bad direction (e.g. you accidentally trained it toward something you didn't mean), you can reset:

1. Open ~/.cerevisor/memory/harness/ and ~/.cerevisor/memory/meta-cognition/.
2. Delete the files (or move them to a backup folder).
3. Restart Cerevisor.

The harness rebuilds from scratch on the next run.

Less drastic: use Memory History to restore a snapshot from a known-good earlier date.