Meta-cognition

Shipped in v3-alpha (Beta). Second of the four zero-LLM features — pure computed views over the existing fact corpus. Interfaces may still change before 3.0 stable.

Why it matters

An agent that knows what it knows (and what it doesn’t) makes better decisions about when to recall, when to ask, and when to act with confidence. Zero LLM cost — just SQL views.

The confidence map

-- Materialized view, refreshed daily by mnemo.metacognition.refresh
CREATE MATERIALIZED VIEW mv_confidence_map AS
SELECT
  e.id AS entity_id,
  e.canonical_name,
  e.kind,
  COUNT(f.id)     AS fact_count,
  AVG(f.worth)    AS avg_worth,
  AVG(f.confidence) AS avg_confidence,
  MAX(f.created_at) AS newest_fact,
  MIN(f.created_at) AS oldest_fact,
 
  -- Coverage: how well do we know this entity?
  CASE
    WHEN COUNT(f.id) >= 10 AND AVG(f.worth) > 0.7 THEN 'expert'
    WHEN COUNT(f.id) >= 5  AND AVG(f.worth) > 0.5 THEN 'familiar'
    WHEN COUNT(f.id) >= 2 THEN 'aware'
    WHEN COUNT(f.id) >= 1 THEN 'minimal'
    ELSE 'blind'
  END AS coverage_level,
 
  -- Freshness: how current?
  CASE
    WHEN MAX(f.created_at) > NOW() - INTERVAL '7 days'  THEN 'current'
    WHEN MAX(f.created_at) > NOW() - INTERVAL '30 days' THEN 'recent'
    WHEN MAX(f.created_at) > NOW() - INTERVAL '90 days' THEN 'aging'
    ELSE 'stale'
  END AS freshness
FROM mnemo_entity e
LEFT JOIN mnemo_fact f ON f.entity_id = e.id AND f.valid_to IS NULL
GROUP BY e.id, e.canonical_name, e.kind;

Self-diagnostic signal

interface SelfModel {
  confidenceMap: Array<{
    entity: string;
    coverage: "expert" | "familiar" | "aware" | "minimal" | "blind";
    freshness: "current" | "recent" | "aging" | "stale";
    factCount: number;
    avgWorth: number;
  }>;
 
  // 7-day trends
  trends: {
    recallHitRate:           { current; previous; delta };
    avgRecallLatency:        { current; previous; delta };
    sessionCollapseQuality:  { current; previous; delta };
    strategySuccessRate:     { current; previous; delta };
  };
 
  // Gaps: high recall attempts, low hit rate
  knowledgeGaps: Array<{
    topic: string;
    recallAttempts: number;
    hitRate: number;
    suggestedAction: "ask_user" | "search_codebase" | "wait_for_data";
  }>;
 
  // Strengths: consistently high worth + high recall
  strengths: Array<{ topic; avgWorth; factCount }>;
}

ROI

Without meta-cognition:
  Agent: "What's the deploy process?"
  → recalls 5 facts → low confidence → asks user to confirm
  → user explains → store → next time same uncertainty

With meta-cognition:
  Agent checks: coverage("deploy") = "expert", freshness = "current"
  → trusts recall, skips confirmation → saves 1 user round-trip
  OR
  coverage("infrastructure") = "blind"
  → asks user immediately, skips empty recall

Savings: ~200 tokens per avoided confirmation loop

Agent-facing tool

Exposed via memory_introspect.