Skip to main content

Installation

Last Updated: 2025-11-02

Quick Start​

The fastest way to get started with Cortex:

npm create cortex-memories

This interactive wizard will:

  • Set up a complete Cortex project
  • Configure Convex (local or cloud)
  • Install all dependencies
  • Deploy backend functions
  • Create working example code

Time to working agent: < 5 minutes

Installation Methods​

Best for: New projects, first-time users, workshops

# Create new project
npm create cortex-memories@latest my-ai-agent
cd my-ai-agent
npm run dev  # Start Convex
npm start    # Run your agent

What you get:

  • ✅ Cortex SDK installed
  • ✅ Convex backend deployed
  • ✅ Environment configured
  • ✅ Working example code
  • ✅ Optional graph database setup

Method 2: Add to Existing Project​

Best for: Integrating Cortex into existing applications

cd your-existing-project
npm create cortex-memories@latest .

The wizard will add Cortex to your project without disrupting existing code.

Method 3: Manual Installation​

Best for: Advanced users who want full control

# 1. Install packages
npm install @cortexmemory/sdk convex

# 2. Copy backend functions
# The SDK package includes convex-dev/ folder
# Copy it to your project:
cp -r node_modules/@cortexmemory/sdk/convex-dev ./convex

# 3. Create convex.json
echo '{"functions": "convex/"}' > convex.json

# 4. Configure environment
# Create .env.local:
echo 'CONVEX_URL=http://127.0.0.1:3210' > .env.local

# 5. Deploy Convex
npx convex dev

Prerequisites​

Required​

  • Node.js 18+ - Download from nodejs.org
  • npm 9+ - Comes with Node.js

Check your versions:

node --version  # Should be v18.0.0 or higher
npm --version   # Should be 9.0.0 or higher

Optional​

  • 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 local graph database

    • Download from docker.com
    • Only needed if using graph database features
    • Not required for basic Cortex usage

  • OpenAI API Key - For embeddings

    • Get from platform.openai.com
    • Or use any other embedding provider
    • Optional - Cortex works without embeddings

Convex Setup Options​

Cortex works with Convex in three modes:

1. Local Development (Default)​

Best for: Rapid iteration, learning, prototyping

Pros:

  • ✅ No account needed
  • ✅ Instant start
  • ✅ Fully private
  • ✅ Free forever

Cons:

  • ❌ No vector search
  • ❌ Not production-ready
  • ❌ Data stored locally only

Setup:

npm create cortex-memories@latest my-agent
# Select: "Local development"

Best for: Production apps, full features, collaboration

Pros:

  • ✅ Full vector search support
  • ✅ Automatic scaling
  • ✅ Real-time sync
  • ✅ Production-ready
  • ✅ Free tier available

Cons:

  • ❌ Requires Convex account
  • ❌ Internet required
  • ❌ Costs scale with usage

Setup:

npm create cortex-memories@latest my-agent
# Select: "Create new Convex database"
# Follow prompts to login/create account

3. Existing Convex Deployment​

Best for: Adding Cortex to existing Convex projects

Pros:

  • ✅ Reuse existing deployment
  • ✅ Centralized data
  • ✅ Existing auth setup

Setup:

npm create cortex-memories@latest my-agent
# Select: "Use existing Convex database"
# Enter your CONVEX_URL

Verification​

After installation, verify everything works:

1. Check Installation​

# Verify SDK is installed
npm list @cortexmemory/sdk
# Should show: @cortexmemory/sdk@0.8.1

# Verify Convex is installed
npm list convex
# Should show: convex@^1.28.0

# Check backend files exist
ls convex/
# Should list: schema.ts, conversations.ts, memories.ts, etc.

2. Test Connection​

# Start Convex (local mode)
npm run dev
# Should show: "Convex functions ready!"

# In another terminal, run your agent
npm start
# Should connect and create a memory

3. View Dashboard​

Local:

Cloud:

  • Dashboard URL shown in wizard output
  • View your data and functions online

Troubleshooting​

"npm create cortex-memories" fails​

Check:

  • Node.js version >= 18
  • Internet connection (to download packages)
  • npm permissions

Fix:

# Update npm
npm install -g npm@latest

# Clear cache
npm cache clean --force

"Cannot find module @cortexmemory/sdk"​

Cause: Dependencies not installed

Fix:

cd your-project
npm install

"Convex functions not found"​

Cause: Backend not deployed or Convex not running

Fix:

# For local mode
npm run dev

# For cloud mode
npx convex deploy

"WebSocket closed with code 1006"​

Cause: Convex server not running

Fix:

# Make sure Convex is running in another terminal
npm run dev

Next Steps​

After installation:

  1. Five-Minute Quickstart - Build your first memory-enabled agent
  2. Core Concepts - Understand how Cortex works
  3. Configuration - Configure for your needs

Upgrading​

To upgrade to a new version:

# Update SDK
npm install @cortexmemory/sdk@latest

# Update Convex
npm install convex@latest

# Redeploy backend
npx convex deploy

Check [CHANGELOG for breaking changes.

Questions? See [FAQ or ask in Discussions.