--- title: "Harness memory & meta-cognition" description: "What the harness learns from your runs, per-role metrics, learned tips, observations, self-portrait." slug: guides/memory-and-learning/harness-memory-and-meta-cognition section: guides subsection: memory-and-learning canonical_url: https://cerevisor.com/docs/guides/memory-and-learning/harness-memory-and-meta-cognition last_verified: 2026-05-18 last_verified_version: "1.2.0" updated_at: 2026-05-18T15:08:18.053416+00:00 --- 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](../situational-awareness/overview.md), 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.