# Cortex

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

[![npm version](https://img.shields.io/npm/v/@iamharshil/cortex.svg?style=flat-square&color=cb3837)](https://www.npmjs.com/package/@iamharshil/cortex)
[![License](https://img.shields.io/badge/license-MIT-green?style=flat-square)](LICENSE)
[![Node](https://img.shields.io/badge/node-%E2%89%A520-417e38?style=flat-square)](https://nodejs.org/)

---

## 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](https://nodejs.org/) ≥ 20                                  | JavaScript runtime |
| [LM Studio](https://lmstudio.ai) **or** [Ollama](https://ollama.com) | Local model server |

### Install

```bash
npm install -g @iamharshil/cortex
```

### Initialize

```bash
cortex init
```

This creates:

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

---

## Usage

### Run a Task

```bash
# 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

```bash
cortex chat
```

### Check Status

```bash
cortex status
cortex models --provider ollama
```

### Configuration

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

---

## Configuration

Cortex stores configuration in:

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

### config.json

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

### MCP Configuration

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

---

## Memory System

### Project Memory (CORTEX.md)

Create a `CORTEX.md` file in your project root:

```markdown
# 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

```bash
# 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

```bash
# 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](LICENSE) © [Harshil](https://github.com/iamharshil)

---

<div align="center">
<sub>Built for developers who care about privacy and efficiency.</sub>
</div>