Deployment Guide

Relevant source files

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

• README.md
• package.json
• src/index.ts
• src/mcp/server.ts
• paper/drafts/cortex-v2-4-technical-note.md
• src/ingestion/ingest-markdown.ts

CORTEX provides a production-ready cognitive architecture for AI agents. This guide details the steps to deploy the system using Docker, local installation, or as a Model Context Protocol (MCP) server. CORTEX requires Node.js 22+ and a PostgreSQL 15+ database equipped with the pgvector extension.
Sources: README.md:1-50, package.json:96-98

System Architecture

The deployment architecture consists of a TypeScript application layer, a PostgreSQL database with vector capabilities, and external embedding providers.

The diagram shows the flow from user requests through the ingestion and encoding pipelines to the database, including external API dependencies.
Sources: README.md:70-95, paper/drafts/cortex-v2-4-technical-note.md:40-65

Prerequisites

Before deployment, ensure you have the following components:

• Node.js: Version 22.0.0 or higher.
• Database: PostgreSQL 15+ with the pgvector extension.
• API Keys: An embedding API key (VoyageAI is recommended) and an Anthropic API key for synthesis and summaries.
  Sources: README.md:144-148, package.json:96-98, paper/drafts/cortex-v2-4-technical-note.md:180-185

Local Installation

To install CORTEX locally, follow these steps:

1. Clone the repository: `git clone https://github.com/Rezzyman/cortex.git%60.
2. Install dependencies: npm install.
3. Configure environment: Copy .env.example to .env and provide your DATABASE_URL and API keys.
4. Run database migrations: npx tsx scripts/run-migrations.ts.
5. Start the REST API: npx tsx src/index.ts.
   Sources: README.md:150-163, package.json:8-25

Environment Configuration

The following environment variables are required for a successful deployment:

Variable	Description	Source
DATABASE_URL	PostgreSQL connection string	src/index.ts
PORT	Port for the REST API (default: 3100)	src/index.ts
VOYAGE_API_KEY	Key for VoyageAI embeddings	src/mcp/server.ts
ANTHROPIC_API_KEY	Key for Anthropic LLM	README.md
CORTEX_WORKSPACE	Root path for file ingestion	src/ingestion/ingest-markdown.ts

Sources: src/index.ts:13-14, src/mcp/server.ts:186-193, src/ingestion/ingest-markdown.ts:145-146

Docker Deployment

Docker Compose facilitates the deployment of the CORTEX stack, including the PostgreSQL database.

1. Prepare your .env file with necessary API keys.
2. Launch the stack: docker compose up.
   Sources: README.md:165-168

MCP Server Deployment

CORTEX can run as an MCP server, allowing agents like Claude Code or Cursor to use it as a toolset.

Running the MCP Server

Start the server using:

npx tsx src/mcp/server.ts

Client Configuration

Add the server to your agent's .mcp.json configuration file:

{
  "mcpServers": {
    "cortex": {
      "command": "npx",
      "args": ["tsx", "/path/to/cortex/src/mcp/server.ts"],
      "env": {
        "DATABASE_URL": "your-connection-string",
        "VOYAGE_API_KEY": "your-key"
      }
    }
  }
}

Sources: README.md:175-193, src/mcp/server.ts:1-15

Data Ingestion

Once deployed, you must ingest data to populate the agent's memory. CORTEX supports manual ingestion via API/Tools or bulk ingestion of a markdown corpus.

Corpus Ingestion

To ingest an existing folder of markdown files:

1. Set the CORTEX_WORKSPACE environment variable to your data directory.
2. Run the ingestion script: npm run ingest.
   Sources: package.json:17, src/ingestion/ingest-markdown.ts:144-180

Ingestion Priority

The system automatically infers priority based on filenames during ingestion:

Priority	Level	Files/Paths
P0	Critical	MEMORY.md, SOUL.md, STANDING-ORDERS.md
P1	High	Daily journals (e.g., 2024-01-01.md), USER.md
P2	Normal	Logs, general markdown files
P3	Low	/telegram/, /limitless/

Sources: src/ingestion/ingest-markdown.ts:25-50

Maintenance and Dream Cycles

Deployment includes setting up a cadence for the "Dream Cycle," which performs memory consolidation and pruning. You can trigger this via the REST API or the cortex_dream tool.

The sequence shows the two-phase (SWS and REM) process triggered for memory maintenance.
Sources: src/dream/dream-cycle.ts:35-90, README.md:231-245

Summary

Deploying CORTEX involves setting up a TypeScript environment and a PostgreSQL database with vector support. The system is accessible via a REST API on port 3100 or through the Model Context Protocol. Following deployment, initial memory population is achieved through the ingestion pipeline, and system health is maintained via scheduled dream cycles.
Sources: README.md:144-193, src/index.ts:1-60