noema/docs/cognition.md

Background cognition: metacognition, reflection, consolidation, narrative, notifications

Causal timeline

Every event records the links it was written with: causation_id (the event that directly led to it), parent_ids (the events it was assembled from) and evidence references (the events, memories, beliefs and model calls it rests on). The causal timeline (/events/{id}/timeline, GET /api/v1/events/{id}/chain) walks those links backwards towards causes and forwards towards consequences, up to six hops and two hundred events, and draws each edge with its kind: caused, parent or cited. Events are grouped by the cognitive cycle they belong to, and that grouping is labelled as correlation, not causation. Nothing on the page is inferred; where the system does not know why something happened, no arrow is drawn. Questions the walk answers directly: why a belief exists (walk back to the observations and assertions it cites), what changed it (the belief_updated events downstream of an outcome), which memories were retrieved and which thoughts won attention in the cycle, which model call contributed (an artefact on the node), and which later decisions depended on it (walk forward).

These subsystems run beside the cognitive cycle. Each is deterministic in what it concludes; a language model may only word things, and only within a configured budget.

Metacognition (per cycle)

The metacognition process audits the mind's own reasoning with explicit checks and proposes warnings that compete for attention like any thought:

Check	Fires when	Effect when admitted
insufficient_evidence	a belief is at ≥ 0.7 with a single supporting item	counter-evidence (weight ≈ 0.25) from metacognition lowers it
single_source	all support for a ≥ 0.6 belief comes from one source	counter-evidence
fluent_without_evidence	a belief rests only on model output or free notes	counter-evidence
repeated_failure	three or more hypotheses about one subject rejected in a month	warning
stale_contradiction	a contested belief unresolved for a day	an investigation goal
overconfidence	calibration shows stated confidence running ahead of outcomes	warning, notification
want_suppressed_repeatedly, intention_unsupported, intention_conflicts_commitment, commitment_impossible, intention_churn, repeated_execution_failure, cost_exceeds_value	volition checks (volition.md)	warning
intention_outlived_goal	an intention is open although its goal is completed or abandoned	the intention is abandoned
self_model_mismatch	the self-model's policy for a capability differs from the effective policy	the self-model entry is corrected
unsupported_explanation, action_claim_without_record	a reply's reasons or action claims do not match records (agency.md)	warning and a research measurement

Each warning is a metacognition event with check and ref metadata; the same check on the same target is not repeated within a day. Warnings appear on the mind overview.

Reflection (scheduled, per mind)

reflection.Service.Run reviews the period since the last reflection: prediction errors, rejected beliefs, operator corrections, belief status changes, completed goals, contradictions and calibration. Repeated failures on one subject become a pattern, and each new pattern is written once as a procedural memory ("Lesson: … seek an independent source before raising confidence"). The findings are stored structurally with a plain rendering; the reflect prompt may rewrite the prose when the narrate role has a model and the mind's reflection budget allows. A reflection event carries everything. Operators can run it now from the Background tab or noemactl reflect.

Consolidation (scheduled, per mind)

consolidation.Service.Run takes the last 30 days of episodes not yet consolidated, clusters them deterministically by shared stemmed terms (speaker prefixes stripped), and for each cluster of at least consolidation_min_episodes episodes creates:

• a belief (epistemic kind inference) whose confidence is computed from the episodes as evidence (weight 0.3 each, credibility from trust, single-source discount), and
• a semantic memory with the same proposition, linked to every episode by derived_from.

The proposition is a plain deterministic sentence unless the consolidate prompt (summarise role) returns a supported generalisation within the job's model budget; the job records which. Episodes are never modified. Jobs record inputs, outputs and errors; operators can run now, pause scheduled runs globally, and reject a generalisation (memory retracted, belief pinned rejected, episodes untouched). Demo scenario 3 ("user repeatedly selects Go") produces a generalisation this way.

Narrative (after cycles)

The narrative hook builds a five-part structure from state: doing (top workspace thoughts), why (recent stimuli), recently (notable emitted events), resolving (contested beliefs, active goals), next (open predictions). It is rendered as short first-person prose and stored with a narrative_updated event when it changes. With narrative_llm enabled and a narrate model, the prompt may rephrase it; it cannot add content.

Notifications (after cycles)

notifications.Rules maps events to candidates with explicit thresholds: confident prediction misses (≥ 0.7), clear contradictions, strong beliefs (only for minds whose personality says notify proactively, above notify_min_confidence and notify_min_salience), completed goals, overconfidence or loop warnings, denied actions, and very salient observations. Repeats sharing an aggregate key within notify_cooldown increment the existing notification instead of creating another, and are recorded as notification_suppressed events. Every notification stores the rule and the values that fired it.

Modes

While reflection or consolidation runs for a mind, its runtime mode is switched to reflecting or consolidating and back, with mode_changed events, so the dashboard shows what the mind is doing.