Background Cognition Threads

Relevant source files

The following files were used as context for generating this wiki page:

• src/cognition/background-threads.ts
• src/mcp/server.ts
• src/db/schema.ts
• README.md
• paper/drafts/cortex-v2-4-technical-note.md
• src/dream/dream-cycle.ts

Background Cognition Threads provide autonomous reasoning within the CORTEX architecture. These threads query the memory graph independently to surface strategic, operational, and relational insights without direct user intervention. The system uses these threads to ensure the agent thinks about its goals and environment even when it is not actively communicating.

Sources: README.md:129-131, src/cognition/background-threads.ts:1-8

Core Thread Types

CORTEX implements three distinct reasoning threads. Each thread focuses on a specific functional domain of the agent's cognition.

Strategic Thread

The strategic thread identifies gaps in knowledge and monitors alignment with core goals. It performs the following actions:

• Queries recent P0 (critical) and P1 (high) priority memories.
• Analyzes decision artifacts stored in the cognitive_artifacts table.
• Identifies stalled projects by finding critical memories older than 7 days that lack recent synaptic activity.
• Monitors entity coverage to detect when known critical entities have not been mentioned recently.

Sources: src/cognition/background-threads.ts:25-88, src/db/schema.ts:204-220

Operational Thread

The operational thread monitors system health and background task integrity. It performs the following checks:

• Inspects recent self_diagnostics records for degraded or critical health alerts.
• Validates the status of cron jobs by reading from the agent's local configuration.
• Analyzes memory system health, specifically checking if average resonance scores fall below a threshold (default 3.0).

Sources: src/cognition/background-threads.ts:90-143, src/db/schema.ts:241-260

Relational Thread

The relational thread manages the social graph and contact maintenance. It performs these functions:

• Scans the relationship_graph for overdue contacts based on defined frequencies (daily, weekly, monthly, etc.).
• Identifies pending "open items" associated with specific individuals in the relationship graph.
• Analyzes entity frequency trends to identify top active contacts based on recent memory mentions.

Sources: src/cognition/background-threads.ts:145-212, src/db/schema.ts:316-340

Architecture and Data Flow

The background cognition system operates as a set of deterministic reasoning functions. Results from these threads are stored as structured artifacts to influence future recall and agent behavior.

The diagram shows the parallel execution of the three cognition threads and their interaction with different data sources before persisting results.
Sources: src/cognition/background-threads.ts:240-272, src/db/schema.ts:300-314

Execution and Persistence

CORTEX manages thread execution using the runAllThreads function. This function executes all three threads with individual 30-second timeouts using Promise.allSettled to prevent a single hanging thread from blocking the entire system.

Each thread produces a ThreadResult object containing:

• Insights: Observations about the current state.
• Actions: Specific recommended steps for the agent.
• Questions: Open items for the agent to consider or ask.

These findings are persisted in two ways:

1. Status Update: The background_threads table tracks the lastRun, status, and nextAction for each thread type.
2. Artifact Creation: Findings are saved as cognitive_artifacts with a resonanceScore of 5.0, making them available for future hybrid searches.

Sources: src/cognition/background-threads.ts:10-23, src/cognition/background-threads.ts:214-237, src/cognition/background-threads.ts:245-272

API and Tool Integration

CORTEX exposes background cognition capabilities through the Model Context Protocol (MCP) server. This allows external agents to trigger or query reasoning threads.

Tool	Purpose	Source File
cortex_bg_thread	Manually runs a specific reasoning thread (strategic, operational, or relational).	src/mcp/server.ts:468-477
cortex_synthesize	Analyzes recent novel synapses to discover unexpected connections.	src/mcp/server.ts:479-493
cortex_artifact	Stores custom insights or learnings as cognitive artifacts.	src/mcp/server.ts:413-441

The Synthesis Phase

While the background threads focus on specific domains, the phaseSynthesis operation (often triggered alongside REM dream cycles) focuses on synaptic connections. It examines "weak" synapses (strength between 0.2 and 0.4) formed during free association to discover actionable implications between disparate memory sources.

Sources: src/dream/dream-cycle.ts:348-406, src/mcp/server.ts:479-493

Data Models

The following table summarizes the database fields relevant to background cognition tracking.

Table	Field	Description
background_threads	thread_type	Identifies the thread as strategic, operational, or relational.
background_threads	findings	JSONB field storing insights, actions, and questions.
background_threads	status	Current state of the thread (idle, running, completed, error).
cognitive_artifacts	artifact_type	Categorizes the insight (decision, learning, insight, etc.).
cognitive_artifacts	content	JSONB field storing the structured output of the reasoning thread.

Sources: src/db/schema.ts:204-220, src/db/schema.ts:300-314

Summary

Background Cognition Threads transform CORTEX from a passive memory store into an active cognitive agent. By autonomously monitoring critical priorities, system health, and social relationships, these threads ensure the agent remains contextually aware and goal-oriented. All findings are integrated back into the memory graph as high-resonance artifacts, ensuring that autonomous insights are prioritized in subsequent interactions.

Sources: README.md:129-131, paper/drafts/cortex-v2-4-technical-note.md:25-30