cortex-mem-mcp

Cortex Memory MCP Skill

This skill enables persistent memory capabilities for AI agents, allowing them to store, search, and recall information across sessions using semantic retrieval.

Prerequisites Check

Before configuring this skill, verify if cortex-mem-mcp is available in your system:

# Check if cortex-mem-mcp is in PATH
which cortex-mem-mcp || where cortex-mem-mcp  # Linux/macOS || Windows

If the command returns a path, the binary is already installed. If not, proceed to the installation section below.

Installation

Option 1: Install from crates.io (Recommended)

cargo install cortex-mem-mcp

After installation, verify:

cortex-mem-mcp --version

Option 2: Build from Source

# Clone the repository
git clone https://github.com/sopaco/cortex-mem.git
cd cortex-mem

# Build the release binary
cargo build --release --bin cortex-mem-mcp

# The binary will be at:
# ./target/release/cortex-mem-mcp (Linux/macOS)
# .\target\release\cortex-mem-mcp.exe (Windows)

Option 3: Download Pre-built Binary

Download the latest release from GitHub:

• GitHub Releases: https://github.com/sopaco/cortex-mem/releases

Choose the appropriate binary for your platform:

• cortex-mem-mcp-linux-x86_64 (Linux x64)
• cortex-mem-mcp-darwin-arm64 (macOS Apple Silicon)
• cortex-mem-mcp-darwin-x86_64 (macOS Intel)
• cortex-mem-mcp-windows-x86_64.exe (Windows x64)

Configuration

Step 1: Create Configuration File

Create a config.toml file (e.g., ~/.config/cortex-mem/config.toml):

[cortex]
# Data directory for storing memories
data_dir = "~/.cortex-data"

[llm]
# LLM API configuration
api_base_url = "https://api.openai.com/v1"
api_key = "your-api-key"
model_efficient = "gpt-4o-mini"
temperature = 0.1
max_tokens = 65536

[embedding]
# Embedding configuration
api_base_url = "https://api.openai.com/v1"
api_key = "your-embedding-api-key"
model_name = "text-embedding-3-small"
batch_size = 10
timeout_secs = 30

[qdrant]
# Vector database configuration
url = "http://localhost:6333"
collection_name = "cortex_memories"
embedding_dim = 1536
timeout_secs = 30

Step 2: Start Qdrant (Vector Database)

# Using Docker
docker run -d -p 6333:6333 qdrant/qdrant

# Verify Qdrant is running
curl http://localhost:6333

Step 3: Configure MCP Client

Configure your MCP client (e.g., Claude Desktop, Cursor, etc.) to use cortex-mem-mcp.

Claude Desktop

Edit the configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Add the following configuration:

{
  "mcpServers": {
    "cortex-memory": {
      "command": "cortex-mem-mcp",
      "args": [
        "--config", "/path/to/config.toml",
        "--tenant", "default"
      ],
      "env": {
        "RUST_LOG": "info"
      }
    }
  }
}

If you built from source, use the full path to the binary:

{
  "mcpServers": {
    "cortex-memory": {
      "command": "/path/to/cortex-mem/target/release/cortex-mem-mcp",
      "args": [
        "--config", "/path/to/config.toml",
        "--tenant", "default"
      ]
    }
  }
}

Cursor IDE

Add to your Cursor MCP settings:

{
  "mcpServers": {
    "cortex-memory": {
      "command": "cortex-mem-mcp",
      "args": ["--config", "/path/to/config.toml"]
    }
  }
}

Step 4: Restart Your MCP Client

After configuration, restart Claude Desktop or your MCP client to load the new server.

Step 5: Verify Installation

Test the MCP server manually:

# Run with debug logging
RUST_LOG=debug cortex-mem-mcp --config /path/to/config.toml --tenant default

Command-line Arguments

Environment Variables

When to Use This Skill

Use this skill when you need to:

• Remember user preferences - Store and recall user-specific settings, preferences, and context
• Persist conversation context - Keep important information from past conversations accessible
• Build project knowledge - Accumulate and retrieve project-specific information over time
• Track user-agent interactions - Maintain a history of interactions for better personalization
• Search memories semantically - Find relevant information using natural language queries

Available Tools

Storage Tools

store

Add a message to memory for a specific session.

{
  "content": "The user prefers dark mode in all applications",
  "thread_id": "project-alpha",
  "role": "user"
}

• content: The message content to store
• thread_id: Optional session/thread identifier (defaults to "default")
• role: Message role - "user", "assistant", or "system"

commit

Commit accumulated conversation content and trigger memory extraction.

{
  "thread_id": "project-alpha"
}

This triggers:

• Memory extraction (session → user/agent memories)
• L0/L1 layer generation
• Vector indexing

Search Tools

search

Layered semantic search across memory using L0/L1/L2 tiered retrieval.

{
  "query": "user preferences for UI",
  "scope": "project-alpha",
  "limit": 10,
  "min_score": 0.5,
  "return_layers": ["L0", "L1"]
}

recall

Recall memories with full context (L0 snippet + L2 content).

{
  "query": "what did we discuss about authentication",
  "scope": "project-alpha",
  "limit": 5
}

Navigation Tools

ls

List directory contents to browse the memory space.

{
  "uri": "cortex://session",
  "recursive": true,
  "include_abstracts": true
}

Common URIs:

• cortex://session - List all sessions
• cortex://user - List user-level memories
• cortex://user/preferences - User preference memories

explore

Smart exploration of memory space, combining search and browsing.

{
  "query": "authentication implementation details",
  "start_uri": "cortex://session",
  "return_layers": ["L0"]
}

Tiered Access Tools

Memory is organized in layers for efficient context management:

abstract

Get L0 abstract layer for quick relevance checking.

{
  "uri": "cortex://session/project-alpha/conversation.md"
}

overview

Get L1 overview layer for understanding core information.

{
  "uri": "cortex://session/project-alpha/conversation.md"
}

content

Get L2 full content layer - the complete original content.

{
  "uri": "cortex://session/project-alpha/conversation.md"
}

Management Tools

delete

Delete a memory by its URI.

{
  "uri": "cortex://session/old-project/conversation.md"
}

layers

Generate L0/L1 layer files for memories.

{
  "thread_id": "project-alpha"
}

index

Index memory files for vector search.

{
  "thread_id": "project-alpha"
}

Memory URI Structure

Memories are organized using a URI scheme:

cortex://session/{thread_id}/conversation.md
cortex://user/{user_id}/preferences/{topic}.md
cortex://user/{user_id}/memories/{memory_id}.md

Best Practices

1. Use meaningful thread IDs - Use descriptive names like project-alpha or user-123-support instead of generic IDs

2. Commit periodically - Call commit after significant conversation milestones to ensure memory extraction

3. Start with search - Before storing new information, search to avoid duplication

4. Use tiered access - Start with abstract or search to find relevant memories, then use overview or content for details

5. Scope your searches - Use the scope parameter to limit searches to relevant sessions

Example Workflow

Storing a User Preference

1. Store the preference:
   store(content="User prefers TypeScript over JavaScript for all new projects", role="user")

2. Commit to persist:
   commit()

Recalling Past Context

1. Search for relevant memories:
   search(query="TypeScript preferences", limit=5)

2. Get overview of most relevant result:
   overview(uri="cortex://user/default/preferences/typescript.md")

Building Project Knowledge

1. Store project decisions:
   store(content="Decided to use PostgreSQL for the main database", thread_id="project-x", role="assistant")

2. Later, recall project decisions:
   recall(query="database decisions", scope="project-x")

Auto-Trigger Feature

The MCP server supports automatic memory processing:

• Triggers after configurable message count threshold (default: 10)
• Triggers after inactivity timeout (default: 2 minutes)
• Can be disabled with --no-auto-trigger flag

Configuration

The MCP server requires a config.toml with:

[cortex]
data_dir = "./cortex-data"

[llm]
api_base_url = "https://api.openai.com/v1"
api_key = "your-api-key"
model_efficient = "gpt-4o-mini"

[embedding]
api_base_url = "https://api.openai.com/v1"
api_key = "your-api-key"
model_name = "text-embedding-3-small"

[qdrant]
url = "http://localhost:6333"
collection_name = "cortex_mem"
embedding_dim = 1536