Configuration

Cortex uses a hierarchical configuration system managed by the CLI. Configuration is minimal by default but offers extensive customization when needed.

Cortex Cloud Coming Soon

This guide covers self-hosted configuration. Cortex Cloud will offer zero-config managed deployments—coming soon.

---

Configuration Hierarchy

The CLI uses a hierarchical configuration system (highest priority first):

Configuration Priority

CLI Flags

--url, --key, --deployment (highest priority)

Environment Variables

CONVEX_URL, CONVEX_DEPLOY_KEY

Project Config

./cortex.config.json (optional)

User Config

~/.cortexrc (managed by CLI, lowest priority)

Higher priority sources override lower ones

Example: How Priority Works

# User config (~/.cortexrc) says: local deployment
# Environment variable says: CONVEX_URL=http://127.0.0.1:3210
# CLI flag overrides everything:
cortex db stats --url https://prod.convex.cloud

# Result: Uses production URL from flag

---

User Configuration (~/.cortexrc)

The CLI automatically manages ~/.cortexrc for deployment settings.

Viewing Configuration

Terminal

$ cortex config show

Terminal

$ cortex config list

Terminal

$ cortex config path

Configuration File Format

The ~/.cortexrc file is JSON:

{
  "deployments": {
    "local": {
      "url": "http://127.0.0.1:3210",
      "deployment": "anonymous:anonymous-cortex-sdk-local",
      "projectPath": "/Users/you/projects/my-agent",
      "enabled": true
    },
    "staging": {
      "url": "https://staging.convex.cloud",
      "key": "dev:staging|key",
      "projectPath": "/Users/you/projects/my-agent",
      "enabled": false
    },
    "production": {
      "url": "https://prod.convex.cloud",
      "key": "prod:prod|key",
      "projectPath": "/Users/you/projects/my-agent",
      "enabled": false
    }
  },
  "apps": {
    "quickstart": {
      "type": "nextjs",
      "projectPath": "/Users/you/projects/my-agent",
      "path": "quickstart",
      "port": 3000,
      "startCommand": "npm run dev",
      "enabled": true
    }
  },
  "default": "local",
  "format": "table",
  "confirmDangerous": true
}

Configuration Fields

Parameter	Type	Required	Default	Description
deployments	object	Yes	—	Named deployment configurations
deployments[name].url	string	Yes	—	Convex deployment URL
deployments[name].key	string	No	—	Deploy key (optional for local)
deployments[name].deployment	string	No	—	Convex deployment name
deployments[name].projectPath	string	No	—	Path to project directory
deployments[name].enabled	boolean	No	false	Auto-start with cortex start
apps	object	No	—	Named app configurations
apps[name].type	string	No	—	App type (e.g., 'nextjs')
apps[name].port	number	No	—	Port number
apps[name].startCommand	string	No	—	Command to start app
default	string	No	—	Default deployment name
format	string	No	table	Default output format
confirmDangerous	boolean	No	true	Require confirmation for dangerous operations

---

Managing Deployments

Adding Deployments

1

Interactive mode (recommended)

Terminal

$ cortex config add-deployment

2

With options

Terminal

$ cortex config add-deployment cloud --url https://your-app.convex.cloud --key "prod|..."

3

Set as default

Terminal

$ cortex config add-deployment production --url https://prod.convex.cloud --default

Removing Deployments

Terminal

$ cortex config remove-deployment

Terminal

$ cortex config remove-deployment staging

Note

Cannot remove the default deployment. Set a different default first.

Updating Deployment Settings

Terminal

$ cortex config set-url production --url https://new-prod.convex.cloud

Terminal

$ cortex config set-key production --key "prod|new-key"

Terminal

$ cortex config set-path production /path/to/project

Enabling/Disabling Deployments

Control which deployments start with cortex start:

Terminal

$ cortex config enable staging

Terminal

$ cortex config disable production

Terminal

$ cortex config list

Switching Deployments

Terminal

$ cortex use

Terminal

$ cortex use production

Terminal

$ cortex use --clear

Testing Configuration

You can verify your configuration by checking the connection:

Terminal

$ cortex config show

Terminal

$ cortex db stats

---

Environment Variables

Convex Configuration

Parameter	Type	Required	Default	Description
CONVEX_URL	string	Yes	—	Convex deployment URL
CONVEX_DEPLOY_KEY	string	No	—	Convex deploy key
CONVEX_DEPLOYMENT	string	No	—	Convex deployment name
LOCAL_CONVEX_URL	string	No	http://127.0.0.1:3210	Local Convex URL
CLOUD_CONVEX_URL	string	No	—	Cloud Convex URL
CLOUD_CONVEX_DEPLOY_KEY	string	No	—	Cloud deploy key

Graph Database Configuration

Parameter	Type	Required	Default	Description
NEO4J_URI	string	No	—	Neo4j connection URI
NEO4J_USERNAME	string	No	—	Neo4j username
NEO4J_PASSWORD	string	No	—	Neo4j password
MEMGRAPH_URI	string	No	—	Memgraph connection URI
MEMGRAPH_USERNAME	string	No	—	Memgraph username
MEMGRAPH_PASSWORD	string	No	—	Memgraph password
CORTEX_GRAPH_SYNC	string	No	—	Enable automatic graph sync for all operations ('true'/'false'). When true, all facts, entities, and relationships are automatically synced to the graph database (v0.29.0+)

Other Configuration

Parameter	Type	Required	Default	Description
OPENAI_API_KEY	string	No	—	OpenAI API key for embeddings
CORTEX_SDK_DEV_PATH	string	No	—	Path to local SDK for dev mode
DEBUG	string	No	—	Enable debug output

Example .env.local

# Convex Configuration
CONVEX_URL=http://127.0.0.1:3210

# Optional: Graph Database
NEO4J_URI=bolt://localhost:7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=password

# Optional: Embeddings
OPENAI_API_KEY=sk-your-key-here

Tip

Use cortex dev for hot-reload development.

# Convex Configuration
CONVEX_URL=https://your-staging-app.convex.cloud
CONVEX_DEPLOY_KEY=dev:your-staging-app|key

# Optional: Graph Database
NEO4J_URI=bolt://staging-neo4j:7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=staging-password

# Optional: Embeddings
OPENAI_API_KEY=sk-your-key-here

# Convex Configuration
CONVEX_URL=https://your-prod-app.convex.cloud
CONVEX_DEPLOY_KEY=prod:your-prod-app|key

# Optional: Graph Database
NEO4J_URI=bolt://prod-neo4j:7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=secure-production-password

# Optional: Embeddings
OPENAI_API_KEY=sk-your-key-here

Warning

Never commit production credentials to version control!

---

Multi-Environment Setup

Example: Local + Staging + Production

1

Add local development

Terminal

$ cortex config add-deployment local --url http://127.0.0.1:3210

Terminal

$ cortex config set-path local ~/projects/my-agent

2

Add staging

Terminal

$ cortex config add-deployment staging --url https://staging.convex.cloud

Terminal

$ cortex config set-key staging

3

Add production

Terminal

$ cortex config add-deployment production --url https://prod.convex.cloud

Terminal

$ cortex config set-key production

4

Enable only local for auto-start

Terminal

$ cortex config enable local

Terminal

$ cortex config disable staging

Terminal

$ cortex config disable production

Tip

Now cortex start starts only local. Use cortex start -d staging or cortex start -d production for other environments.

Switching Between Environments

Terminal

$ cortex use local

Terminal

$ cortex use production

Terminal

$ cortex db stats -d staging

---

Project Configuration (Optional)

cortex.config.json

You can optionally create a cortex.config.json in your project root:

{
  "defaultMemorySpace": "my-agent",
  "defaultImportance": 50,
  "memoryRetention": {
    "maxVersions": 10,
    "retentionDays": 365
  },
  "graph": {
    "enabled": true,
    "uri": "bolt://localhost:7687"
  }
}

Note

This is optional. Most configuration is managed via CLI in ~/.cortexrc.

---

SDK Configuration

When using the SDK programmatically, configuration is minimal:

import { Cortex } from "@cortexmemory/sdk";

// Minimal configuration
const cortex = new Cortex({
  convexUrl: process.env.CONVEX_URL!, // Set by CLI or .env.local
});

With Graph Database

import {
  CypherGraphAdapter,
  initializeGraphSchema,
} from "@cortexmemory/sdk/graph";

const graphAdapter = new CypherGraphAdapter();
await graphAdapter.connect({
  uri: process.env.NEO4J_URI!,
  username: process.env.NEO4J_USERNAME!,
  password: process.env.NEO4J_PASSWORD!,
});

await initializeGraphSchema(graphAdapter);

const cortex = new Cortex({
  convexUrl: process.env.CONVEX_URL!,
  graph: {
    adapter: graphAdapter,
    orphanCleanup: true,
  },
});

See:

• API Reference - Memory Operations
• Graph Database Integration

---

Security Configuration

Data Isolation

Ensure proper memory space boundaries:

Terminal

$ cortex memory list --space user-alice

Terminal

$ cortex memory list --space user-bob

Sensitive Data

PII Handling

Be careful with personally identifiable information (PII).

Terminal

$ cortex memory search "password" --space user-123

Terminal

$ cortex memory export --space user-123 --output review.json

Terminal

$ cortex memory delete [memoryId] --space user-123

---

Advanced Configuration

Debug Mode

Enable verbose logging:

Terminal

$ cortex db stats --debug

Terminal

$ DEBUG=1 cortex db stats

Custom Output Formats

Terminal

$ cortex db stats

Terminal

$ cortex db stats --format json

Terminal

$ cortex memory list --space user-123 --format csv

Configuration Reset

Destructive Action

This removes all deployments and apps but keeps project .env.local files and deployed Convex data.

Terminal

$ cortex config reset

---

Best Practices

1. Use environment variables - Never hardcode URLs or keys
2. Separate environments - Use cortex use local|staging|production
3. Secure credentials - Use cortex config set-key (prompts securely), add .env.local to .gitignore
4. Test before production - Always verify on staging first
5. Regular backups - Run cortex db backup before major changes

---

Troubleshooting

Terminal

$ cortex init

Terminal

$ cortex config add-deployment

Terminal

$ cortex use

Terminal

$ cortex use local

Terminal

$ cortex use --clear

Terminal

$ cortex config show

Terminal

$ cortex db stats

Terminal

$ cortex status && cortex start

Terminal

$ cortex config show --debug

Priority: CLI flags > Environment variables > ~/.cortexrc

---

Next Steps