CLI Scripts & Background Tasks
Relevant source files
The following files were used as context for generating this wiki page:
CLI scripts and background tasks manage the lifecycle, maintenance, and autonomous cognition of the CORTEX system. These components handle initial database setup, data ingestion, nightly memory maintenance via "dream cycles," and independent reasoning threads that analyze system state without direct user interaction.
Core CLI Operations
CORTEX provides several entry points via package.json scripts to manage the environment and data.
Database & Environment Setup
The system uses Drizzle ORM for schema management. Basic setup involves running migrations and backfilling data for new cognitive layers.
npm run migrate: Runs database migrations to set up or update the PostgreSQL schema.npm run backfill:hippocampal: Populates hippocampal codes for existing memories.npm run mcp: Starts the Model Context Protocol server, exposing CORTEX tools to external agents like Claude Code.
Sources: package.json:11-20, src/mcp/server.ts:1-20
Data Ingestion
The ingest-markdown.ts script handles the bulk ingestion of episodic data from various sources. It recursively scans directories for Markdown files, Telegram logs, and Limitless logs.
The ingestion process determines priority based on file names. For example, SOUL.md or MEMORY.md receive P0 (critical) priority, while Telegram logs default to P3 (low).
Sources: src/ingestion/ingest-markdown.ts:25-50, src/ingestion/ingest-markdown.ts:200-240
The Dream Cycle
The Dream Cycle is a multi-phase background task that performs memory maintenance. It is modeled after biological sleep stages to prevent information overload and strengthen useful connections.
SWS (Slow-Wave Sleep)
Slow-Wave Sleep focuses on stability and pruning.
- Resonance Analysis: Updates the
resonance_scoreof memories using an Ebbinghaus stability-adjusted decay curve. - Adaptive Pruning: Deletes or archives memories that fall below adaptive percentile thresholds (P5 for deletion, P15 for archiving).
- Consolidation: Clusters high-resonance memories and uses LLM-generated summaries to create abstractive insights.
REM (Rapid Eye Movement)
REM focuses on creativity and synthesis.
- Free Association: Randomly activates memory nodes to find novel semantic or sparse-space connections.
- Synthesis: Generates new cognitive artifacts ("insights") from recently formed synapses.
Sources: src/dream/dream-cycle.ts:36-70, src/dream/dream-cycle.ts:140-165
Autonomous Cognition Threads
Background threads run deterministic reasoning tasks to monitor system health and relational status. These are triggered via the cortex_bg_thread tool or internal schedulers.
| Thread Type | Focus Area | Key Actions |
|---|---|---|
| Strategic | Alignment & Gaps | Detects stalled projects (P0/P1 memories with no recent activity) and missing entity mentions. |
| Operational | System Health | Monitors cron job status, diagnostic trends, and average resonance levels. |
| Relational | Social Freshness | Identifies overdue contacts based on importance scores and contact frequency. |
Sources: src/cognition/background-threads.ts:35-50, src/cognition/background-threads.ts:120-140, src/cognition/background-threads.ts:200-220
Proprioception & Diagnostics
The self-check.ts module provides a diagnostic framework for "Self-Awareness." It evaluates the operational integrity of the agent.
The Drift Score is a specific metric (0.0 to 1.0) calculated by analyzing recent cognitive artifacts for unauthorized actions or stylistic violations, such as using forbidden em-dashes.
Sources: src/proprioception/self-check.ts:50-80, src/proprioception/self-check.ts:135-160
Benchmarking & Evaluation
The benchmarks/cogbench/run.ts script executes the CogBench suite. It evaluates CORTEX against specific cognitive tasks including:
- Novelty Detection: Testing hippocampal CA1's ability to distinguish redundant paraphrases from new information.
- Reconsolidation: Verifying that memories enter a labile window and can be updated with new evidence.
- Procedural Learning: Tracking skill proficiency improvements through repeated execution.
Sources: benchmarks/cogbench/run.ts:38-60, benchmarks/cogbench/tasks/novelty-detection.ts:15-30
CLI scripts and background tasks ensure that CORTEX remains a "living" system. By offloading maintenance to the Dream Cycle and monitoring to background threads, the architecture maintains high-density synaptic connections without manual intervention.