Proprioception & Diagnostics
Relevant source files
The following files were used as context for generating this wiki page:
Proprioception is a self-diagnostic system that monitors the cognitive integrity and operational health of the CORTEX agent. It identifies internal issues such as orphaned memories, synaptic collapse, behavioral drift, and environmental connectivity failures.
This system ensures the agent maintains a stable identity and optimal cognitive performance over long durations. It tracks internal states like energy levels and confidence while auditing reasoning traces for behavioral consistency.
Sources: README.md:120-124, src/proprioception/self-check.ts:1-12
System Architecture
The Proprioception module operates by aggregating data from external configuration files, internal memory tables, and cognitive artifacts. The runSelfCheck function orchestrates multiple diagnostic sub-routines to produce a comprehensive health report.
The diagram shows how runSelfCheck queries both the file system for infrastructure health and the database for cognitive health.
Sources: src/proprioception/self-check.ts:254-260
Diagnostic Components
Operational Health
The system validates physical and environment components required for agent operation.
- Skills Integrity: Verifies the existence and Markdown format validity of essential skill files like
cortex-v2. - Cron Job Status: Monitors automated jobs for failures or execution delays exceeding twice their normal interval.
- Channel Connectivity: Checks if communication channels (e.g., Telegram, Google Chat) are enabled and carry valid credentials.
Sources: src/proprioception/self-check.ts:47-118
Cognitive Integrity
This routine detects structural failures within the memory graph that search results might not immediately reveal.
| Check | Description | Alert Threshold |
|---|---|---|
| Orphaned Memories | Active memories with no synapses and no access in 30+ days. | > 100 nodes |
| HC Consistency | Memories with embeddings missing Dentate Gyrus sparse codes. | > 50 nodes |
| Synaptic Health | Average connection strength across the active memory graph. | < 0.15 strength |
| Learning Rate | Time elapsed since the last procedural memory was created. | > 7 days |
Sources: src/proprioception/self-check.ts:168-238
Behavioral Drift Detection
The system analyzes recent cognitive_artifacts to identify patterns that violate standing orders or indicate personality instability. It specifically flags sycophantic language (e.g., "happy to help") and forbidden punctuation like em-dashes.
Sources: src/proprioception/self-check.ts:130-165
Data Models
Self-Diagnostics Schema
Diagnostic results are persisted in the self_diagnostics table to track health trends over time.
| Field | Type | Description |
|---|---|---|
drift_score | real | Normalized score (0-1) where 1 is severe identity drift. |
overall_health | varchar | Status: healthy, degraded, or critical. |
skills_status | jsonb | Map of skill names to their existence and validity. |
alerts | text[] | List of specific strings describing detected issues. |
Sources: src/db/schema.ts:233-252
Agent State Journaling
Agents record subjective internal states to the agent_state_logs table via the cortex_journal tool.
// src/proprioception/journal.ts:10-20
export interface JournalEntry {
energyState: "high" | "normal" | "low" | "depleted";
confidence: number; // 0 to 1
activeThreads: string[];
concerns: string[];
notes?: string;
sessionId?: string;
}
Sources: src/db/schema.ts:255-274, src/proprioception/journal.ts:10-20
Implementation Details
Diagnostic Logic
The system uses the sql helper to perform complex aggregations directly in the database, such as calculating the avg_strength of synapses.
SELECT AVG(ms.connection_strength) AS avg_strength
FROM memory_synapses ms
WHERE ms.memory_a IN (
SELECT id FROM memory_nodes
WHERE agent_id = ${agentId} AND status = 'active'
)
Sources: src/proprioception/self-check.ts:213-217
Tool Integration
The Proprioception system is exposed to MCP clients via standard tools.
cortex_self_check: Executes the full diagnostic suite and returns a formatted report including health emojis.cortex_journal: Allows the agent to log its current energy, confidence, and active work threads.cortex_status: Retrieves high-level memory statistics and the results of the last dream cycle.
Sources: src/mcp/server.ts:468-500, src/mcp/server.ts:413-440
Proprioception provides the necessary feedback loop for self-correction. By monitoring behavioral drift and synaptic health, CORTEX prevents the "identity drift" common in long-running LLM agents and ensures that memory structures remain performant.
Sources: README.md:120-124, src/proprioception/self-check.ts:265-275