Cortex Mem MCP

What it does

When your agent uses it

• You need to remember user preferences
• Past conversations
• Project context
• Any information that should persist beyond the current session

Example prompts

• “/cortex-mem-mcp”

Requirements

• Docker
• Compatibility (from SKILL.md): Requires cortex-mem-mcp MCP server running with configured LLM and vector database (Qdrant). Needs API keys for LLM and embedding services.
• Pre-approved tools (allowed-tools): store, search, recall, ls, explore, abstract, overview, content, commit, delete, layers, index

Workflow steps

5 steps, taken from the step headings in SKILL.md.

1. 1Create Configuration File
2. 2Start Qdrant (Vector Database)
3. 3Configure MCP Client
4. 4Restart Your MCP Client
5. 5Verify Installation

What it can do on your machine

Read from SKILL.md and the folder at commit 82a1c83. It shows what the files ask for, not the result of running them.

• Tool permissions

  Pre-approves these tools, so the agent can use them without asking each time:

  • store
  • search
  • recall
  • ls
  • explore
  • abstract
  • overview
  • content
  • commit
  • delete

  …and 2 more on the same allowed-tools line.

  From allowed-tools in the SKILL.md frontmatter.

• Runs code

  Shell commands in SKILL.md call:

  • cargo
  • git
  • docker
  • curl

  From the folder's file list and the shell code blocks in SKILL.md.

• Network

  Hosts in commands or code, which the agent is likely to contact:

  • api.openai.com

  From URLs in SKILL.md, links to its own repository left out.

• Credentials

  Names no API keys, tokens, secrets or passwords.

  From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

• Compatibility

  Requires cortex-mem-mcp MCP server running with configured LLM and vector database (Qdrant). Needs API keys for LLM and embedding services.

  From compatibility in the SKILL.md frontmatter.

Context cost

Cortex Mem MCP loads about 2.8k tokens when it runs. Until then it costs about 101 tokens; SKILL.md has 689 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it

~101

When it runs · the whole SKILL.md, loaded when a task matches

~2.8k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from sopaco/cortex-mem at commit 82a1c83, republished under its MIT licence (© sopaco). 689 words, ~2,814 tokens.

name

cortex-mem-mcp

description

Persistent memory enhancement for AI agents. Store conversations, search memories with semantic retrieval, and recall context across sessions. Use this skill when you need to remember user preferences, past conversations, project context, or any information that should persist beyond the current session. Provides tiered access (abstract/overview/content) for efficient context management.

allowed-tools

store, search, recall, ls, explore, abstract, overview, content, commit, delete, layers, index

compatibility

Requires cortex-mem-mcp MCP server running with configured LLM and vector database (Qdrant). Needs API keys for LLM and embedding services.

license

MIT

metadata.author

Sopaco

metadata.version

2.7.0

metadata.homepage

https://github.com/sopaco/cortex-mem

metadata.category

memory

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

cargo install cortex-mem-mcp

cortex-mem-mcp --version

# 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)

[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-5-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:6334"
collection_name = "cortex_memories"
embedding_dim = 1536
timeout_secs = 30

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

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

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

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

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

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

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

{
  "thread_id": "project-alpha"
}

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

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

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

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

{
  "uri": "cortex://session/project-alpha/timeline/2024-03/15/10_30_45_abc123.md"
}

{
  "uri": "cortex://session/project-alpha/timeline/2024-03/15/10_30_45_abc123.md"
}

{
  "uri": "cortex://session/project-alpha/timeline/2024-03/15/10_30_45_abc123.md"
}

{
  "uri": "cortex://session/old-project/timeline/2024-03/15/10_30_45_xyz.md"
}

{
  "thread_id": "project-alpha"
}

{
  "thread_id": "project-alpha"
}

cortex://session/{thread_id}/timeline/{YYYY-MM}/{DD}/{HH_MM_SS}_{id}.md
cortex://user/{user_id}/preferences/{topic}.md
cortex://user/{user_id}/entities/{name}.md
cortex://user/{user_id}/events/{name}.md
cortex://agent/{agent_id}/cases/{name}.md
cortex://agent/{agent_id}/skills/{name}.md

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

2. Commit to persist:
   commit()

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")

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")

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

[llm]
api_base_url = "https://api.openai.com/v1"
api_key = "your-api-key"
model_efficient = "gpt-5-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

© sopaco, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in cortex-mem-mcp/skill of sopaco/cortex-mem.

Open the folder on GitHubat commit 82a1c83