cortexdb-mcp 0.2.0

MCP Server for CortexDB — expose memory operations to AI agents

CortexDB MCP Server

MCP (Model Context Protocol) server that gives AI tools persistent long-term memory via CortexDB. Works with Claude Desktop, Cursor, Windsurf, VS Code Copilot, and any MCP-compatible client.

Quick Start

# Install
pip install -e .

# Or with uvx (no install needed)
uvx --from . cortexdb-mcp

Set your environment variables:

export CORTEXDB_URL="https://api.cortexdb.ai"   # or http://localhost:3141
export CORTEXDB_API_KEY="cx_live_your_key_here"

Run:

cortexdb-mcp

IDE Setup

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "cortexdb": {
      "command": "cortexdb-mcp",
      "env": {
        "CORTEXDB_URL": "https://api.cortexdb.ai",
        "CORTEXDB_API_KEY": "cx_live_your_key_here"
      }
    }
  }
}

Claude Code (CLI)

Edit ~/.claude/mcp.json:

{
  "mcpServers": {
    "cortexdb": {
      "command": "cortexdb-mcp",
      "env": {
        "CORTEXDB_URL": "https://api.cortexdb.ai",
        "CORTEXDB_API_KEY": "cx_live_your_key_here"
      }
    }
  }
}

Cursor

Edit ~/.cursor/mcp.json:

{
  "mcpServers": {
    "cortexdb": {
      "command": "cortexdb-mcp",
      "env": {
        "CORTEXDB_URL": "https://api.cortexdb.ai",
        "CORTEXDB_API_KEY": "cx_live_your_key_here"
      }
    }
  }
}

Or in Cursor Settings > MCP Servers > Add Server.

Windsurf

Edit ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "cortexdb": {
      "command": "cortexdb-mcp",
      "env": {
        "CORTEXDB_URL": "https://api.cortexdb.ai",
        "CORTEXDB_API_KEY": "cx_live_your_key_here"
      }
    }
  }
}

VS Code (GitHub Copilot)

Add to .vscode/mcp.json in your project or ~/.vscode/mcp.json globally:

{
  "servers": {
    "cortexdb": {
      "command": "cortexdb-mcp",
      "env": {
        "CORTEXDB_URL": "https://api.cortexdb.ai",
        "CORTEXDB_API_KEY": "cx_live_your_key_here"
      }
    }
  }
}

Docker

docker build -t cortexdb-mcp .
docker run -e CORTEXDB_URL=https://api.cortexdb.ai -e CORTEXDB_API_KEY=cx_live_... cortexdb-mcp

Tools

Memory Operations

Tool	Description
memory_store	Store a new memory with optional source, type, tags, TTL
memory_search	Search memories using natural language (hybrid retrieval)
memory_forget	Delete memories with audit trail (GDPR-compliant)
get_context	Deep contextual retrieval combining search + graph
advanced_search	Search with structured filters (source, type, time range)

Episode Management

Tool	Description
memory_list	List episodes with pagination and type filter
memory_get	Get a specific episode by ID
memory_update	Update episode content or metadata
memory_delete	Delete a specific episode by ID
memory_bulk_delete	Bulk delete with query matching and dry-run support

Knowledge Graph

Tool	Description
entity_list	List entities (people, services, projects, concepts)
entity_get	Get entity details including relationships and recent episodes
entity_edges	Get all relationships for an entity
entity_link	Create a relationship between two entities

Admin & Observability

Tool	Description
health_check	Check CortexDB server health
get_usage	View usage stats and tier limits
get_insights	Generate proactive insights (incident spikes, gaps, risks)
get_ontology	View entity types and relationship types
export_data	Export memories as JSON
import_data	Import memories from JSON

Resources

Resources provide read-only data that AI tools can access:

Resource URI	Description
cortexdb://health	Server health status
cortexdb://metrics	Request metrics (total, active, errors, rate-limited)
cortexdb://usage	Usage statistics and tier limits
cortexdb://episodes	Recent 50 episodes
cortexdb://entities	Top 100 knowledge graph entities
cortexdb://insights	Proactive insights
cortexdb://ontology	Entity and relationship type schema

Prompts

Pre-built prompt templates:

Prompt	Description
investigate_incident	Investigate an incident using stored memories
summarize_knowledge	Summarize everything known about a topic
deployment_review	Pre-deployment safety review
onboard_to_codebase	Onboard to a codebase using stored knowledge
weekly_digest	Generate a weekly activity summary

Configuration

Environment Variable	Default	Description
CORTEXDB_URL	http://localhost:3141	CortexDB server URL
CORTEXDB_API_KEY	(none)	API key for authentication
CORTEXDB_TIMEOUT	30.0	HTTP request timeout (seconds)

Examples

Store a memory from Cursor

Ask your AI assistant:

"Remember that the payments service was migrated to Stripe v3 on March 15th"

The assistant will call memory_store with the content.

Search memories

"What do we know about the payments service?"

The assistant calls memory_search and gets relevant context from CortexDB.

Explore the knowledge graph

"Show me all entities related to the auth service"

The assistant calls entity_get or entity_edges to traverse relationships.

Pre-deployment review

"Run a deployment review for the user-service"

Uses the deployment_review prompt to check for recent incidents, dependencies, and risks.

Development

# Install in dev mode
pip install -e ".[dev]"

# Run tests
pytest

# Run the server locally
CORTEXDB_URL=http://localhost:3141 CORTEXDB_API_KEY=test cortexdb-mcp

Architecture

┌─────────────┐     stdio/SSE     ┌──────────────┐     HTTP     ┌──────────┐
│  AI Client  │ ◄──────────────► │  MCP Server  │ ◄──────────► │ CortexDB │
│  (Cursor,   │     MCP JSON-RPC  │  (this pkg)  │   REST API   │  Server  │
│   Claude,   │                   │              │              │          │
│   VS Code)  │                   └──────────────┘              └──────────┘
└─────────────┘

The MCP server is a thin translation layer:

1. Receives MCP tool calls from the AI client
2. Translates them to CortexDB REST API calls
3. Formats responses for the AI to consume

License

MIT