Skip to main content

Installation

Get Cortex up and running in minutes.

Quick Start​

The fastest way to get started with Cortex:

1

Install the CLI

Install Cortex globally:

Terminal
$ brew install cortex-memory/tap/cli
2

Verify installation

Check that the CLI is installed correctly:

Terminal
$ cortex --version

Should output: 0.27.4 or higher

3

Create your first project

Initialize a new Cortex project:

Terminal
$ cortex init my-cortex-agent

The interactive wizard will guide you through setup in under 5 minutes.

Prerequisites​

Requirements

Before installing Cortex, ensure you have:

Required:

  • Node.js >= 20 — Download from nodejs.org
  • npm or pnpm — Comes with Node.js

Check your versions:

Terminal
$ node --version && npm --version

Expected output: Node.js v20.0.0+ and npm 9.0.0+

Convex Account — For cloud deployments (free tier available)

  • Sign up at convex.dev
  • Required for vector search features
  • Not needed for local development

Docker Desktop — For graph database features

  • Download from docker.com
  • Only needed for advanced graph queries
  • Not required for basic Cortex usage

OpenAI API Key — For embeddings

  • Get from platform.openai.com
  • Or use any other embedding provider
  • Cortex works without embeddings (keyword search)

Installation Methods​

Install the CLI globally to use it from anywhere:

Terminal
$ brew install cortex-memory/tap/cli

Homebrew handles PATH configuration automatically and makes updates easy with brew upgrade.

Verify installation:

Terminal
$ cortex --version

Now create projects anywhere:

Terminal
$ cortex init my-agent && cortex start

The CLI uses persistent config with absolute paths, so cd is not required.

Method 2: Using npx (No Installation)​

Use the CLI without installing it globally:

Terminal
$ npx @cortexmemory/cli init my-agent
When to use npx
  • One-time project creation
  • Testing before global install
  • CI/CD environments

Trade-off: Slightly slower (downloads each time)

Method 3: Project-Specific Installation​

Install as a dev dependency in your project:

Terminal
$ npm install --save-dev @cortexmemory/cli

Add to package.json:

package.jsonjson
{
"scripts": {
  "cortex": "cortex",
  "dev": "cortex dev",
  "start": "cortex start",
  "stop": "cortex stop"
}
}

Then run:

Terminal
$ npm run cortex init && npm run dev

Verification​

After installation, verify everything works:

1

Check CLI Installation

Terminal
$ cortex --version

Should show: 0.27.4 or higher

Terminal
$ cortex --help

Should display available commands

2

Test CLI Connection

Terminal
$ cortex init test-project

Start services (from any directory):

Terminal
$ cortex start

Check status:

Terminal
$ cortex status
3

Verify Convex Dashboard

For local development: Open http://127.0.0.1:3210

For cloud deployment:

Terminal
$ cortex convex dashboard

Opens your deployment in browser

Troubleshooting​

Cause: CLI not installed or not in PATH

Fix (Recommended):

Terminal
$ brew install cortex-memory/tap/cli

Alternative (npm):

Terminal
$ npm install -g @cortexmemory/cli

If using npm, check global bin path is in your PATH:

Terminal
$ npm config get prefix

Possible causes:

  • Node.js version < 20
  • No internet connection
  • npm permissions

Fix (Recommended):

Update Node.js to v20+, then reinstall via Homebrew:

Terminal
$ brew reinstall cortex-memory/tap/cli

Alternative (npm):

Terminal
$ npm cache clean --force && npm install -g @cortexmemory/cli

Cause: Dependencies not installed in project

Fix:

Terminal
$ cd your-project && npm install

Cause: Convex server not running

Fix:

Terminal
$ cortex start

If issues persist, restart:

Terminal
$ cortex stop && cortex start

Cause: Another Convex instance on same port

Fix: Use interactive dev mode:

Terminal
$ cortex dev

Press k to kill conflicting processes.

Getting More Help
# General help
cortex --help

# Command-specific help
cortex <command> --help

Still stuck?

Upgrading​

To upgrade to the latest version:

Terminal
$ brew upgrade cortex-memory/tap/cli

Verify new version:

Terminal
$ cortex --version

Update SDK and Convex in your projects:

Terminal
$ cortex update
Info

The cortex update command will:

  • Check for newer versions of @cortexmemory/sdk
  • Check for newer versions of convex
  • Offer to update all projects
  • Redeploy backend if needed

Note: The CLI stores project paths in its config, so you can run cortex update from any directory.

Uninstalling​

If you need to uninstall:

Terminal
$ npm uninstall -g @cortexmemory/cli

Remove from a project:

Terminal
$ cd your-project && npm uninstall @cortexmemory/sdk convex

Clean up configuration (optional):

Terminal
$ rm ~/.cortexrc

Next Steps​