feat: add metacognition, reflection, consolidation, narrative and notifications

Phase 10. Metacognition is a cognitive process with deterministic self-checks (insufficient evidence, single-source reliance, model output without evidence, repeated failed hypotheses, stale contradictions, calibration overconfidence); its warnings compete for attention and, when admitted, add counter-evidence or open an investigation goal. Reflection reviews the period since the last run (prediction errors, rejected beliefs, corrections, status changes, completed goals, contradictions, calibration), turns repeated failures into procedural lessons written once, and records a reflection event; a model may only word the prose within the mind's budget. Consolidation clusters unconsolidated episodes by shared stemmed terms, creates a belief whose confidence is computed from the episodes as evidence and a semantic memory linked to each episode by derived_from, and records jobs with inputs and outputs. Wording may come from the consolidate prompt within a per-run model budget; the job says which. Operators can run, pause and reject; originals are never touched. The narrative hook keeps a five-part first-person narrative built from state and stored with narrative_updated events. The notification hook applies explicit thresholded rules, aggregates repeats within a cooldown and records suppressions with reasons. A scheduled job runs consolidation and reflection per mind, switching the runtime mode while it works. API, Background tab, notifications page with unread badge, overview narrative and warnings, CLI commands, docs/cognition.md.
2026-06-28 22:19:38 +01:00
parent 9eb873cbe6
commit 703d080d13
38 changed files with 2321 additions and 26 deletions
@@ -0,0 +1,10 @@
+package cognition
+
+import (
+	"github.com/andydixon/noema/internal/goals"
+	"github.com/andydixon/noema/pkg/ids"
+)
+
+func goalNew(mind ids.ID, title, subject string, priority float64, origin ids.ID) goals.New {
+	return goals.New{MindID: mind, Title: title, Kind: goals.KindInvestigation, Priority: priority, Subject: subject, Owner: "mind", OriginEvent: origin}
+}
@@ -35,6 +35,7 @@ func (h Handlers) Register(r *brain.Registry) {
 	r.Handle("perceive", h.perceive)
 	r.Handle("goal", h.goal)
 	r.Handle("question", h.question)
+	r.Handle("metacognition", h.metacognition)
 }

 // emitter adapts the cycle to the beliefs store's Emitter.
@@ -0,0 +1,165 @@
+package cognition
+
+import (
+	"context"
+	"fmt"
+	"strings"
+	"time"
+
+	"github.com/andydixon/noema/internal/attention"
+	"github.com/andydixon/noema/internal/beliefs"
+	"github.com/andydixon/noema/internal/brain"
+	evstore "github.com/andydixon/noema/internal/events"
+	"github.com/andydixon/noema/internal/workspace"
+	"github.com/andydixon/noema/pkg/events"
+	"github.com/andydixon/noema/pkg/ids"
+)
+
+// Metacognition audits the mind's own reasoning with deterministic checks
+// (spec §16): insufficient evidence, single-source reliance, fluent model
+// output without evidence, repeated failed hypotheses, stale contradictions
+// and overconfidence against calibration. Warnings compete for attention;
+// when admitted they lower confidence or open an investigation.
+type Metacognition struct{}
+
+// Name implements brain.Process.
+func (Metacognition) Name() string { return "metacognition" }
+
+// Observe implements brain.Process.
+func (Metacognition) Observe(ctx context.Context, s *brain.State) ([]brain.Candidate, error) {
+	if s.Services.Beliefs == nil {
+		return nil, nil
+	}
+	var out []brain.Candidate
+	seen := map[string]bool{}
+	add := func(check, ref, summary string, severity float64, evidence []events.EvidenceRef, extra map[string]any) {
+		key := check + ":" + ref
+		if seen[key] || alreadyWarned(ctx, s, check, ref) {
+			return
+		}
+		seen[key] = true
+		content := map[string]any{"check": check, "ref": ref, "severity": severity}
+		for k, v := range extra {
+			content[k] = v
+		}
+		out = append(out, brain.Candidate{Kind: "metacognition", Subject: key, Summary: "self-check (" + check + "): " + summary, Content: content,
+			Features: attention.Features{Salience: 0.3 + 0.5*severity, Consequence: 0.5 + 0.3*severity, Contradiction: 0.5 * severity, Confidence: 0.8, Novelty: 0.4}, Confidence: 0.8, Evidence: evidence})
+	}
+	// Beliefs touched this cycle: created or updated events in the new batch.
+	for _, ev := range s.NewEvents {
+		bid, _ := ev.Metadata["belief_id"].(string)
+		if bid == "" || (ev.Type != events.BeliefCreated && ev.Type != events.BeliefUpdated && ev.Type != events.HypothesisSupported && ev.Type != events.HypothesisCreated) {
+			continue
+		}
+		b, err := s.Services.Beliefs.Get(ctx, nil, s.Mind.ID, ids.ID(bid))
+		if err != nil {
+			continue
+		}
+		rows, _ := s.Services.Beliefs.EvidenceFor(ctx, nil, s.Mind.ID, b.ID)
+		var live []beliefs.Evidence
+		modelOnly, forCount := true, 0
+		for _, r := range rows {
+			if r.Retracted {
+				continue
+			}
+			live = append(live, r.Evidence)
+			if r.Direction == "for" {
+				forCount++
+				if r.Kind != "llm_call" && r.Kind != "note" {
+					modelOnly = false
+				}
+			}
+		}
+		bd := beliefs.Compute(b.Prior, live)
+		ref := []events.EvidenceRef{{Kind: "belief", ID: string(b.ID)}}
+		switch {
+		case b.Confidence >= 0.7 && forCount <= 1:
+			add("insufficient_evidence", bid, fmt.Sprintf("%.2f confidence on one piece of evidence: %s", b.Confidence, truncate(b.Proposition, 80)), 0.6, ref, map[string]any{"belief_id": bid})
+		case b.Confidence >= 0.6 && bd.SourcesFor == 1 && forCount >= 2:
+			add("single_source", bid, fmt.Sprintf("all %d supporting items come from one source: %s", forCount, truncate(b.Proposition, 80)), 0.5, ref, map[string]any{"belief_id": bid})
+		case forCount > 0 && modelOnly:
+			add("fluent_without_evidence", bid, "belief rests only on model output: "+truncate(b.Proposition, 80), 0.7, ref, map[string]any{"belief_id": bid})
+		}
+	}
+	// Repeated failed hypotheses on one subject.
+	if rejected, err := s.Services.Beliefs.List(ctx, s.Mind.ID, beliefs.Filter{Statuses: []beliefs.Status{beliefs.StatusRejected}, Limit: 200}); err == nil {
+		bySubject := map[string]int{}
+		for _, b := range rejected {
+			if b.Subject != "" && b.LastEvaluated.After(s.Now.Add(-30*24*time.Hour)) {
+				bySubject[b.Subject]++
+			}
+		}
+		for subj, n := range bySubject {
+			if n >= 3 {
+				add("repeated_failure", subj, fmt.Sprintf("%d hypotheses about %q were rejected this month", n, subj), 0.6, nil, map[string]any{"subject": subj, "count": n})
+			}
+		}
+	}
+	// Contradictions left open for more than a day.
+	if contested, err := s.Services.Beliefs.Contested(ctx, s.Mind.ID, 20); err == nil {
+		for _, b := range contested {
+			if s.Now.Sub(b.LastEvaluated) > 24*time.Hour {
+				add("stale_contradiction", string(b.ID), "contradiction unresolved for over a day: "+truncate(b.Proposition, 80), 0.5, []events.EvidenceRef{{Kind: "belief", ID: string(b.ID)}}, map[string]any{"belief_id": string(b.ID), "subject": b.Subject})
+			}
+		}
+	}
+	// Overconfidence against calibration.
+	if s.Services.Predictions != nil {
+		if cal, err := s.Services.Predictions.Calibrate(ctx, s.Mind.ID, s.Now.Add(-90*24*time.Hour)); err == nil && cal.Overconfident {
+			add("overconfidence", "calibration", fmt.Sprintf("stated confidence exceeds hit rate (accuracy %.0f%%, Brier %.2f)", cal.Accuracy*100, cal.Brier), 0.7, nil, map[string]any{"accuracy": cal.Accuracy, "brier": cal.Brier})
+		}
+	}
+	return out, nil
+}
+
+// alreadyWarned suppresses repeats of the same check on the same target
+// within a day by looking for a prior metacognition event.
+func alreadyWarned(ctx context.Context, s *brain.State, check, ref string) bool {
+	es, ok := s.Services.Events.(*evstore.Store)
+	if !ok {
+		return false
+	}
+	evs, err := es.Query(ctx, evstore.Filter{MindID: s.Mind.ID, Types: []events.Type{events.Metacognition}, Since: s.Now.Add(-24 * time.Hour), Limit: 200})
+	if err != nil {
+		return false
+	}
+	for _, ev := range evs {
+		if ev.Metadata["check"] == check && ev.Metadata["ref"] == ref {
+			return true
+		}
+	}
+	return false
+}
+
+// metacognition is the handler: it records the warning and applies its
+// effect (a small counter-evidence item or an investigation goal).
+func (h Handlers) metacognition(ctx context.Context, c *brain.Cycle, t workspace.Thought) error {
+	check, _ := t.Content["check"].(string)
+	ref, _ := t.Content["ref"].(string)
+	severity, _ := t.Content["severity"].(float64)
+	ev, err := c.EmitNow(ctx, events.New{Type: events.Metacognition, Source: "brain.metacognition", Summary: strings.TrimPrefix(t.Summary, "self-check "), Salience: t.Score, Confidence: 0.8, CausationID: t.EventID,
+		Evidence: t.Evidence, Metadata: map[string]any{"check": check, "ref": ref, "severity": severity}, Payload: t.Content})
+	if err != nil {
+		return err
+	}
+	if bid, ok := t.Content["belief_id"].(string); ok && bid != "" && h.Beliefs != nil {
+		switch check {
+		case "insufficient_evidence", "single_source", "fluent_without_evidence":
+			_, err := h.Beliefs.AddEvidence(ctx, c.Tx, emitter(c), c.State.Mind.ID, ids.ID(bid), beliefs.EvidenceInput{Direction: "against", Kind: "metacognition", RefID: string(ev.ID), Source: "metacognition:" + check, Weight: 0.15 + 0.15*severity, Credibility: 0.9, Note: "self-check: " + check}, "metacognitive discount: "+check, ev.ID, c.State.CycleID)
+			if err != nil {
+				return err
+			}
+		case "stale_contradiction":
+			if c.State.Services.Goals != nil {
+				subj, _ := t.Content["subject"].(string)
+				if _, err := c.State.Services.Goals.FindBySubject(ctx, c.Tx, c.State.Mind.ID, "investigation", "contradiction:"+bid); err != nil {
+					if g, err := c.State.Services.Goals.Create(ctx, c.Tx, goalNew(c.State.Mind.ID, "Resolve the contradiction about "+firstNonEmpty(subj, "this belief"), "contradiction:"+bid, 0.6, ev.ID)); err == nil {
+						c.Emit(events.New{Type: events.GoalCreated, Source: "brain.metacognition", Summary: "investigation goal: " + g.Title, Salience: 0.5, Confidence: 0.8, CausationID: ev.ID, Evidence: []events.EvidenceRef{{Kind: "goal", ID: string(g.ID)}}, Metadata: map[string]any{"goal_id": string(g.ID)}})
+					}
+				}
+			}
+		}
+	}
+	c.Runtime.Hold(workspace.Item{Key: "meta:" + check + ":" + ref, Content: t.Summary, Kind: "note", SourceEvent: ev.ID})
+	return nil
+}
@@ -0,0 +1,123 @@
+package cognition
+
+import (
+	"context"
+	"fmt"
+	"strings"
+	"time"
+
+	"github.com/andydixon/noema/internal/brain"
+	"github.com/andydixon/noema/internal/goals"
+	"github.com/andydixon/noema/internal/llm"
+	"github.com/andydixon/noema/internal/narrative"
+	"github.com/andydixon/noema/pkg/events"
+)
+
+// NarrativeHook rebuilds the internal narrative after cycles that changed
+// the workspace. The structure is computed from state; a model may rephrase
+// it when the mind's configuration allows and the budget permits.
+type NarrativeHook struct {
+	Store *narrative.Store
+}
+
+// Name implements brain.Hook.
+func (NarrativeHook) Name() string { return "narrative" }
+
+// AfterCycle implements brain.Hook.
+func (h NarrativeHook) AfterCycle(ctx context.Context, c *brain.Cycle, emitted []events.Event) error {
+	if h.Store == nil {
+		return nil
+	}
+	ws := c.Runtime.Workspace()
+	st := narrative.Structured{Mode: string(c.State.Mode), Cycle: c.State.Cycle, GeneratedAt: c.State.Now}
+	for i, t := range ws.Workspace {
+		if i >= 3 {
+			break
+		}
+		st.Doing = append(st.Doing, doingLabel(t.Kind, t.Summary))
+	}
+	for _, ev := range c.State.NewEvents {
+		if ev.Type == events.Observation && len(st.Why) < 2 {
+			st.Why = append(st.Why, "of: "+oneLine(truncate(ev.Summary, 80)))
+		}
+	}
+	for _, ev := range emitted {
+		switch ev.Type {
+		case events.BeliefCreated, events.HypothesisCreated, events.ContradictionDetected, events.PredictionError, events.MemoryConsolidated, events.GoalCreated, events.ResponseGenerated:
+			if len(st.Recently) < 4 {
+				st.Recently = append(st.Recently, oneLine(truncate(ev.Summary, 90)))
+			}
+		}
+	}
+	if c.State.Services.Beliefs != nil {
+		if contested, _ := c.State.Services.Beliefs.Contested(ctx, c.State.Mind.ID, 3); len(contested) > 0 {
+			for _, b := range contested {
+				st.Resolving = append(st.Resolving, "contradiction: "+truncate(b.Proposition, 70))
+			}
+		}
+	}
+	for _, g := range c.State.Goals {
+		if g.Status == goals.StatusActive && len(st.Resolving) < 5 {
+			st.Resolving = append(st.Resolving, "goal: "+truncate(g.Title, 70))
+		}
+	}
+	if c.State.Services.Predictions != nil {
+		if open, _ := c.State.Services.Predictions.Open(ctx, c.State.Mind.ID); len(open) > 0 {
+			for i, p := range open {
+				if i >= 2 {
+					break
+				}
+				st.Next = append(st.Next, fmt.Sprintf("expect (%.2f): %s", p.Confidence, truncate(p.Statement, 70)))
+			}
+		}
+	}
+	old, _ := h.Store.Get(ctx, c.State.Mind.ID)
+	if !narrative.Changed(old.Structured, st) && time.Since(old.UpdatedAt) < 10*time.Minute {
+		return nil
+	}
+	text := narrative.Render(st)
+	if c.State.Mind.Config.NarrativeLLM && c.State.Services.LLM != nil && c.State.Services.Prompts != nil && c.State.Services.LLM.Available(ctx, llm.RoleNarrate) && c.State.AllowLLM() {
+		if pr, err := c.State.Services.Prompts.Get(ctx, "narrate"); err == nil {
+			if req, err := pr.Render(map[string]any{"Workspace": st.Doing, "Recent": st.Recently, "Goals": st.Resolving, "Contradictions": len(st.Resolving)}); err == nil {
+				req.MindID, req.CorrelationID, req.Purpose = c.State.Mind.ID, c.State.CycleID, "narrative"
+				if resp, err := c.State.Services.LLM.Complete(ctx, req); err == nil && strings.TrimSpace(resp.Text) != "" {
+					text = strings.TrimSpace(resp.Text)
+				}
+			}
+		}
+	}
+	ev, err := c.EmitNow(ctx, events.New{Type: events.NarrativeUpdated, Source: "brain.narrative", Summary: truncate(strings.SplitN(text, "\n", 2)[0], 160), Salience: 0.15, Confidence: 0.9,
+		Metadata: map[string]any{"cycle": c.State.Cycle}, Payload: map[string]any{"text": text, "structured": st}})
+	if err != nil {
+		return err
+	}
+	return h.Store.Save(ctx, c.Tx, c.State.Mind.ID, text, st, ev.ID)
+}
+
+// doingLabel phrases a workspace thought as an activity.
+func doingLabel(kind, summary string) string {
+	summary = oneLine(summary)
+	switch kind {
+	case "perceive":
+		if i := strings.Index(summary, "): "); i > 0 && strings.HasPrefix(summary, "understand message (") {
+			return "reading a message: " + summary[i+3:]
+		}
+		return "reading a message"
+	case "attend":
+		return "attending to: " + summary
+	case "retrieve":
+		return "recalling: " + strings.TrimPrefix(summary, "recalled: ")
+	case "hypothesis":
+		return "weighing a " + summary
+	case "question":
+		return "wondering: " + strings.TrimPrefix(summary, "question: ")
+	case "goal":
+		return "working on: " + summary
+	case "metacognition":
+		return "checking myself: " + strings.TrimPrefix(summary, "self-check ")
+	}
+	return summary
+}
+
+// oneLine collapses whitespace so narrative items stay single lines.
+func oneLine(s string) string { return strings.Join(strings.Fields(s), " ") }
@@ -0,0 +1,47 @@
+package cognition
+
+import (
+	"context"
+
+	"github.com/andydixon/noema/internal/brain"
+	"github.com/andydixon/noema/internal/notifications"
+	"github.com/andydixon/noema/pkg/events"
+)
+
+// NotifyHook runs the notification rules over the cycle's events and records
+// what fired or was suppressed, with the reason either way.
+type NotifyHook struct {
+	Store *notifications.Store
+}
+
+// Name implements brain.Hook.
+func (NotifyHook) Name() string { return "notify" }
+
+// AfterCycle implements brain.Hook.
+func (h NotifyHook) AfterCycle(ctx context.Context, c *brain.Cycle, emitted []events.Event) error {
+	if h.Store == nil {
+		return nil
+	}
+	m := c.State.Mind
+	all := append(append([]events.Event{}, c.State.NewEvents...), emitted...)
+	for _, ev := range all {
+		if ev.Type == events.NotificationCreated || ev.Type == events.NotificationSuppressed {
+			continue
+		}
+		for _, cand := range notifications.Rules(ev, m.Config, m.Personality) {
+			n, suppressed, err := h.Store.Deliver(ctx, c.Tx, m.ID, cand, m.Config.NotifyCooldown.D())
+			if err != nil {
+				return err
+			}
+			typ, summary := events.NotificationCreated, "notified ("+cand.Level+"): "+cand.Title
+			if suppressed {
+				typ, summary = events.NotificationSuppressed, "notification aggregated (repeat within cooldown): "+cand.Title
+			}
+			c.Emit(events.New{Type: typ, Source: "brain.notify", Summary: summary, Salience: 0.2, Confidence: 1, CausationID: ev.ID,
+				Evidence: []events.EvidenceRef{{Kind: "event", ID: string(ev.ID), Note: "trigger"}},
+				Metadata: map[string]any{"notification_id": string(n.ID), "rule": cand.Rule, "level": cand.Level, "suppressed": suppressed, "count": n.Count},
+				Payload:  map[string]any{"rule": cand.Rule, "reason": cand.Reason, "title": cand.Title, "aggregate_key": cand.AggregateKey, "count": n.Count}})
+		}
+	}
+	return nil
+}