Cortex

The ultimate local AI coding agent - context-aware, memory-powered, MCP-enabled

What is Cortex?

Cortex is an autonomous AI coding agent that runs entirely locally on your machine. It combines the best features from Claude Code, OpenCode, PI, and GitHub Copilot while prioritizing token optimization and hardness.

┌──────────────────────────────────────────────────┐
│  $ cortex run "build a todo app"                │
│                                                  │
│  🔍 Analyzing project...                        │
│  📝 Creating plan...                            │
│  ✨ cortex/src/index.ts                          │
│  ✨ cortex/src/agent/engine.ts                   │
│                                                  │
│  Your code stays local. Always.                 │
└──────────────────────────────────────────────────┘

Key Features

• 🔒 Privacy-first — All inference runs locally, no data leaves your machine
• 🧠 Smart Context — Token-optimized context management with auto-compaction
• 💾 Persistent Memory — Project (CORTEX.md) and user memory across sessions
• 🔌 MCP Support — Connect to Model Context Protocol servers
• 🎯 Plan Mode — Supervised autonomy with plan previews
• 🔧 7 Primitives — Minimal tools: Read, Write, Edit, Bash, Glob, Grep, TodoWrite

Getting Started

Prerequisites

| Requirement | Description | | -------------------------------------------------------------------- | ------------------ | | Node.js ≥ 20 | JavaScript runtime | | LM Studio or Ollama | Local model server |

Install

npm install -g @iamharshil/cortex

Initialize

cortex init

This creates:

• .cortex/config.json — Provider configuration
• .cortex/mcp.json — MCP server configuration
• CORTEX.md — Project memory file

Usage

Run a Task

# Simple task
cortex run "create a hello world function"

# With specific provider
cortex run "refactor auth" --provider ollama --model llama3.2

# Plan mode - shows plan before executing
cortex run "migrate to typescript" --plan-mode

Interactive Chat

cortex chat

Check Status

cortex status
cortex models --provider ollama

Configuration

cortex setup --provider ollama --model llama3.2

Configuration

Cortex stores configuration in:

| Platform | Path | | -------- | ------------------- | | macOS | ~/.cortex/ | | Linux | ~/.cortex/ | | Windows | %APPDATA%\cortex\ |

config.json

{
  "provider": "ollama",
  "model": "llama3.2",
  "url": "http://localhost:11434"
}

MCP Configuration

{
  "servers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "./"]
    }
  }
}

Memory System

Project Memory (CORTEX.md)

Create a CORTEX.md file in your project root:

# Cortex Project Memory

## Project Overview

- React-based todo app
- TypeScript, Vite

## Coding Conventions

- Functional components
- CSS modules for styling

## Testing

- Vitest for unit tests

User Memory (~/.cortex/memory.md)

Global preferences and context loaded for all projects.

Token Optimization

Cortex is designed for minimum token usage:

| Component | Target | | ------------------ | ----------------- | | System Prompt | ~3K tokens | | Tool Definitions | ~5K tokens (lazy) | | Project Memory | ~5K tokens | | Available for Work | 180K+ tokens |

Auto-Compaction

When context reaches 95%, Cortex automatically:

1. Summarizes conversation history
2. Preserves key information (file paths, conclusions)
3. Clears old tool outputs

Manual Control

# Check token usage
/context

# Manual compaction
/compact preserve file paths and current task

Providers

Local (Default)

| Provider | Default Port | URL | | --------- | ------------ | -------------------------- | | Ollama | 11434 | http://localhost:11434 | | LM Studio | 1234 | http://localhost:1234/v1 |

Cloud (Future)

• OpenRouter (Coming soon)
• Anthropic (Coming soon)
• OpenAI (Coming soon)
• Gemini (Coming soon)

Development

# Clone and setup
git clone https://github.com/iamharshil/cortex.git
cd cortex
npm install

# Development
npm run dev

# Build
npm run build

# Test
npm test
npm run lint
npm run typecheck

Architecture

Cortex follows the "Less Scaffolding, More Model" philosophy (inspired by PI):

1. Minimal Primitives — Only 7 core tools, trust the model to orchestrate
2. Token Efficiency — Lazy loading, smart truncation, auto-compaction
3. Local First — Privacy, no cloud dependencies
4. MCP Extensible — Connect to any external service

License

MIT © Harshil