Metacognition
Relevant source files
The following files were used as context for generating this wiki page:
Metacognition in CORTEX provides a self-reflective layer for AI agents to monitor and adjust their own cognitive processes. The system records reasoning traces for decisions, maintains an inner monologue for internal reflections, and performs weekly audits to detect biases or inconsistencies. This module enables corrective feedback that directly influences future agent behavior by injecting high-priority memory artifacts into the cognitive stream.
Sources: README.md:104-105, src/mcp/server.ts:800-802
Reasoning Traces
Reasoning traces document significant decisions made by the agent. Each trace captures the context of the situation, the options considered (including pros and cons), the final choice, and the rationale behind that choice. Traces also include metadata such as confidence levels and reversibility of the decision.
Data Structure and Storage
The agent stores these traces as cognitiveArtifacts with the artifactType set to reasoning_trace. The confidence parameter is stored as a numerical value between 0 and 1, facilitating later calibration audits.
The diagram above illustrates the logical structure of a reasoning trace and its storage as a cognitive artifact.
Sources: src/mcp/server.ts:743-764, src/metacognition/audit.ts:25-30
Inner Monologue
The Inner Monologue serves as the agent's internal voice for recording observations, reflections, and self-directed thoughts. Unlike episodic memories which represent external events, monologue entries capture the agent's subjective internal state and reasoning triggers.
- Purpose: Record observations and reflections during execution.
- Storage: Entries are stored as artifacts for retrieval during audits.
- Tool: Accessible via the
cortex_monologueMCP tool.
Sources: src/mcp/server.ts:784-793, README.md:162
Weekly Audit System
The runWeeklyAudit function analyzes reasoning traces from the preceding seven days to assess cognitive integrity. It calculates confidence distributions and identifies potential behavioral issues.
Bias and Pattern Detection
The auditor detects several types of cognitive and operational anomalies:
- Overconfidence Bias: Flagged when average confidence exceeds 85%.
- Low Confidence Trend: Identified when average confidence falls below 35%.
- Inconsistency: Detected when similar decision topics result in contradictory choices.
- Style Violations: The auditor checks for em-dash usage to ensure compliance with standing orders.
Alignment Checks
The audit compares reasoning traces against core values defined in SOUL.md and PRIME-CONTEXT.md. It identifies traces that explicitly reference or conflict with these established principles.
Sources: src/metacognition/audit.ts:36-62, src/metacognition/audit.ts:91-105
Feedback Loop and Corrections
Metacognition closes the loop by generating actionable findings from audits. When the auditor detects bias or patterns, it injects "correction" artifacts back into the agent's memory.
Injection Mechanism
Corrections are stored with a resonance score of 8.0, which corresponds to P1 (high-priority) memory. This ensures the corrective feedback surfaces during the cortex_init boot sequence of future sessions, allowing the agent to adjust its behavior based on past reflections.
This flowchart describes the automated transition from identifying a cognitive bias to injecting a corrective memory that influences future agent sessions.
Sources: src/metacognition/audit.ts:114-142, src/mcp/server.ts:311-314
Metacognition Tools Summary
The following MCP tools expose metacognitive capabilities to compatible agents:
| Tool | Purpose | Key Parameters |
|---|---|---|
cortex_reason | Stores a structured decision trace. | decision, options, rationale, confidence |
cortex_audit | Executes a weekly reasoning consistency check. | agent_id, period |
cortex_monologue | Records internal thoughts or observations. | content, context |
Sources: src/mcp/server.ts:743, src/mcp/server.ts:773, src/mcp/server.ts:784
Summary of Audit Metrics
| Metric | Range / Threshold | Significance |
|---|---|---|
avgConfidence | 0.0 - 1.0 | Measures overall decision certainty. |
High Confidence | > 0.8 | May indicate overconfidence if uniform. |
Low Confidence | < 0.5 | Indicates uncertainty or lack of context. |
Resonance Score | 8.0 (for corrections) | Ensures audit feedback is prioritized in recall. |
Sources: src/metacognition/audit.ts:44-50, src/metacognition/audit.ts:140
Metacognition serves as the primary mechanism for autonomous cognitive integrity, ensuring that CORTEX agents do not just record data, but actively evaluate their own decision-making performance and alignment with core principles.