Harness memory & meta-cognition

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

Harness self-memory

Lives at ~/.cerevisor/memory/harness/. Filled in automatically at the end of each run.

It holds three things:

• A readable retrospective: what has been working, what hasn't, and a log of recent runs.
• The numbers behind it: how each role has been doing, what runs cost, and which problems keep coming back.
• Your corrections: a running log of every time you corrected Cerevisor ("don't auto-add reviewers", "use the cheaper model for this role").

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

What it captures

After every workflow run, Cerevisor records:

• How each role did: how often it succeeded, what it cost, how long it took.
• Recurring patterns: "Researcher agents have been failing on EU-domain queries lately."
• A run log entry: workflow name, status, cost, duration, what worked and what didn't.

Cerevisor later reads this to surface tips ("You spent $40 on your most expensive model last week; a cheaper one would have produced the same output for $5").

Noise control

Cerevisor is deliberately conservative about what counts as a learning:

• Different wordings of the same pattern are merged into one entry.
• A pattern seen in a single run is recorded, but agents are only told about it once later runs confirm it.
• Patterns that stop being confirmed are retired over time, and the total kept is capped.
• A learning from one workflow stays with that workflow, so it doesn't leak into unrelated ones.

Meta-cognition

Lives at ~/.cerevisor/memory/meta-cognition/. Updated at the end of each run by comparing what Cerevisor knows now with what it knew before.

It holds two things:

• Observations: short notes about change over time.
• The self-portrait: a reflective summary of "what I have learned about working with you."

Visible in Memory view → Reflection tab.

What an observation can say

• A role's results are getting worse, or have recovered.
• A role has been seen for the first time.
• A pattern is growing, has gone quiet, or has reversed.
• The same problem keeps happening run after run, or has stopped happening.
• A theme keeps coming up across runs.

When the same problem persists across several runs, Cerevisor shows a learned tip: a badge on the affected agent, or a pill in the status bar.

The self-portrait

The portrait has three sections:

• Learnings about you: a few sentences on your preferences and patterns.
• What has been going well: a few sentences on what Cerevisor has been doing well lately.
• Enduring insights: a short list of insights that have repeated across runs.

The portrait is refreshed after runs that produced new observations.

Toggling enrichment

Two related settings in Settings → Memory:

Setting	Default	Effect
Meta-cognition enrichment enabled	On	Whether Cerevisor makes the optional model call that writes the narrative and the portrait. Observations are tracked either way.
Inject memory into prompts	Off	Whether the narrative and observations are given to every agent at run time.

If you turn enrichment off, Cerevisor 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 model call when:

• Enrichment is turned off in Settings → Memory.
• None of your providers can answer it. (If your default provider can't, Cerevisor uses another provider you have connected rather than skipping.)
• No new observations were produced this run, so there is nothing to narrate.
• The provider call itself failed.

The reason is recorded so the Memory view can show why the portrait or narrative is out of date.

How Situational Awareness uses this

Situational Awareness reads the observations, the self-portrait, your open disagreements and the per-role learnings, and presents them while you build and run. When these memories grow stale or contradict each other, the Situational Awareness panels say so. If you want to understand why a badge looks the way it does, the answer almost always lives in the memory described above.

Resetting

If Cerevisor's learned state has drifted in a bad direction (for example, 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.

Cerevisor rebuilds from scratch on the next run.

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