Getting Started

Relevant source files

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

• README.md
• src/mcp/server.ts
• CONTRIBUTING.md
• src/index.ts
• src/ingestion/ingest-markdown.ts
• package.json

CORTEX provides a synthetic cognition infrastructure for AI agents, moving beyond simple vector databases to a complete cognitive architecture. It implements hippocampal encoding, dream cycles for memory consolidation, and emotional valence to allow agents to learn and evolve over time. Sources: README.md:1-10, README.md:94-114

You can integrate CORTEX into your workflow as a standalone REST API or as a Model Context Protocol (MCP) server for compatible AI clients like Claude Code, Cursor, or Windsurf. Sources: README.md:52-57, src/mcp/server.ts:1-10

Initial Environment Setup

CORTEX requires specific software dependencies and environment configurations to function. You must ensure your environment meets the following requirements:

• Node.js: Version 22 or higher.
• PostgreSQL: Version 15 or higher with the pgvector extension installed.
• Embedding API: An API key for VoyageAI (recommended) or OpenAI.
• Database URL: A valid PostgreSQL connection string.

Sources: README.md:126-131, package.json:84-86

Installation Steps

1. Clone the repository:

   git clone https://github.com/Rezzyman/cortex.git
   cd cortex
   

2. Install dependencies:

   npm install
   

3. Configure environment:
   Copy the example environment file and edit it with your database credentials and API keys.

   cp .env.example .env
   

4. Initialize the database:
   Run the migrations script to create the necessary schema, including the 16 tables across 6 cognitive layers.

   npx tsx scripts/run-migrations.ts
   

Sources: README.md:133-145, CONTRIBUTING.md:10-18

System Architecture

The following diagram illustrates the ingestion and retrieval flow within the CORTEX architecture.

CORTEX separates similar inputs using Dentate Gyrus (DG) sparse coding and detects novelty via CA1, storing these in a relational graph structure within PostgreSQL. Sources: README.md:94-112, README.md:204-208

Running the Services

You can interact with CORTEX through two primary interfaces.

1. REST API

Start the Express server to expose endpoints for search, recall, ingestion, and dream cycles.

npx tsx src/index.ts

The server defaults to port 3100. Sources: README.md:167-170, src/index.ts:18-20

2. MCP Server

Run the MCP server to provide native tools to AI agents.

npx tsx src/mcp/server.ts

To connect an agent like Claude, add the following to the .mcp.json configuration:

{
  "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:150-165, src/mcp/server.ts:636-640

Core Interface Summary

CORTEX exposes several primary operations for managing agent memory.

Feature	Description	File Reference
Ingestion	Chunks, embeds, and extracts entities from text for long-term storage.	src/ingestion/ingest-markdown.ts
Hybrid Search	Scores results based on semantic similarity, text match, recency, resonance, and priority.	src/mcp/server.ts
Dream Cycle	Runs nightly maintenance: resonance decay, pruning, and cluster consolidation.	src/dream/dream-cycle.ts
Reconsolidation	Updates existing memories within a 1-hour "labile window" after retrieval.	src/mcp/server.ts
Procedural Memory	Stores and retrieves skills and workflows based on practice.	src/mcp/server.ts

Sources: README.md:174-188, src/mcp/server.ts:65-350, src/dream/dream-cycle.ts:38-60

Initial Data Ingestion

To populate your agent's memory, use the bulk ingestion tool. This script processes markdown files, logs, and transcripts into the cognitive graph.

# Ingest the entire V1 corpus
npm run ingest

The ingestion process prioritizes files based on their filename; for example, MEMORY.md and SOUL.md are assigned P0 (Critical) priority. Sources: src/ingestion/ingest-markdown.ts:31-45, package.json:14

Summary

Getting started with CORTEX involves setting up a Node.js environment with PostgreSQL, initializing the cognitive database schema, and selecting an interface (REST or MCP). By ingesting initial data and running regular dream cycles, you establish a dynamic memory system that allows AI agents to maintain consistent identity and improve skills over time. Sources: README.md:16-30, README.md:214-222