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:

CODEBLOCK0

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)

CODEBLOCK1

After installation, verify:

CODEBLOCK2

Option 2: Build from Source

CODEBLOCK3

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)
INLINECODE2 (macOS Apple Silicon)
INLINECODE3 (macOS Intel)
INLINECODE4 (Windows x64)

Configuration

Step 1: Create Configuration File

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

CODEBLOCK4

Step 2: Start Qdrant (Vector Database)

CODEBLOCK5

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: INLINECODE7
Windows: INLINECODE8
Linux: INLINECODE9

Add the following configuration:

CODEBLOCK6

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

CODEBLOCK7

Cursor IDE

Add to your Cursor MCP settings:

CODEBLOCK8

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:

CODEBLOCK9

Command-line Arguments

Argument	Default	Description
INLINECODE10 / INLINECODE11	INLINECODE12	Path to configuration file
INLINECODE13

Environment Variables

Variable	Description
INLINECODE23	Override data directory path
INLINECODE24

Logging level (debug, info, warn, error) |

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.

CODEBLOCK10

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

`commit`

Commit accumulated conversation content and trigger memory extraction.

CODEBLOCK11

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.

CODEBLOCK12

`recall`

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

CODEBLOCK13

Navigation Tools

`ls`

List directory contents to browse the memory space.

CODEBLOCK14

Common URIs:

- cortex://session - List all sessions
INLINECODE34 - List user-level memories
INLINECODE35 - User preference memories

`explore`

Smart exploration of memory space, combining search and browsing.

CODEBLOCK15

Tiered Access Tools

Memory is organized in layers for efficient context management:

Layer	Size	Purpose
L0	~100 tokens	Quick relevance checking (abstract)
L1

`abstract`

Get L0 abstract layer for quick relevance checking.

CODEBLOCK16

`overview`

Get L1 overview layer for understanding core information.

CODEBLOCK17

`content`

Get L2 full content layer - the complete original content.

CODEBLOCK18

Management Tools

`delete`

Delete a memory by its URI.

CODEBLOCK19

`layers`

Generate L0/L1 layer files for memories.

CODEBLOCK20

`index`

Index memory files for vector search.

CODEBLOCK21

Memory URI Structure

Memories are organized using a URI scheme:

CODEBLOCK22

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

CODEBLOCK23

Recalling Past Context

CODEBLOCK24

Building Project Knowledge

CODEBLOCK25

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:

CODEBLOCK26

Cortex Memory MCP 技能

本技能为AI代理提供持久化记忆能力，使其能够跨会话存储、搜索和召回信息，并支持语义检索。

前置条件检查

在配置此技能前，请确认系统中是否已安装 cortex-mem-mcp：

bash

检查 cortex-mem-mcp 是否在 PATH 中

which cortex-mem-mcp || where cortex-mem-mcp # Linux/macOS || Windows

如果命令返回路径，说明二进制文件已安装。若未安装，请继续查看下方安装章节。

安装

方式一：从 crates.io 安装（推荐）

bash
cargo install cortex-mem-mcp

安装完成后，验证安装：

bash
cortex-mem-mcp --version

方式二：从源码构建

bash

克隆仓库

git clone https://github.com/sopaco/cortex-mem.git
cd cortex-mem

构建发布版二进制文件

cargo build --release --bin cortex-mem-mcp

二进制文件位于：

./target/release/cortex-mem-mcp (Linux/macOS)

.\target\release\cortex-mem-mcp.exe (Windows)

方式三：下载预构建二进制文件

从 GitHub 下载最新版本：

- GitHub 发布页：https://github.com/sopaco/cortex-mem/releases

选择适合您平台的二进制文件：

- cortex-mem-mcp-linux-x8664（Linux x64）
cortex-mem-mcp-darwin-arm64（macOS Apple Silicon）
cortex-mem-mcp-darwin-x8664（macOS Intel）
cortex-mem-mcp-windows-x86_64.exe（Windows x64）

配置

步骤一：创建配置文件

创建 config.toml 文件（例如 ~/.config/cortex-mem/config.toml）：

toml
[cortex]

存储记忆的数据目录

data_dir = ~/.cortex-data

[llm]

LLM API 配置

apibaseurl = https://api.openai.com/v1
api_key = your-api-key
model_efficient = gpt-4o-mini
temperature = 0.1
max_tokens = 65536

[embedding]

嵌入配置

apibaseurl = https://api.openai.com/v1
api_key = your-embedding-api-key
model_name = text-embedding-3-small
batch_size = 10
timeout_secs = 30

[qdrant]

向量数据库配置

url = http://localhost:6333
collectionname = cortexmemories
embedding_dim = 1536
timeout_secs = 30

步骤二：启动 Qdrant（向量数据库）

bash

使用 Docker

docker run -d -p 6333:6333 qdrant/qdrant

验证 Qdrant 是否运行

curl http://localhost:6333

步骤三：配置 MCP 客户端

配置您的 MCP 客户端（例如 Claude Desktop、Cursor 等）以使用 cortex-mem-mcp。

Claude Desktop

编辑配置文件：

- macOS：~/Library/Application Support/Claude/claudedesktopconfig.json
Windows：%APPDATA%\Claude\claudedesktopconfig.json
Linux：~/.config/Claude/claudedesktopconfig.json

添加以下配置：

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

如果从源码构建，请使用二进制文件的完整路径：

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

Cursor IDE

添加到您的 Cursor MCP 设置中：

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

步骤四：重启 MCP 客户端

配置完成后，重启 Claude Desktop 或您的 MCP 客户端以加载新服务器。

步骤五：验证安装

手动测试 MCP 服务器：

bash

使用调试日志运行

RUST_LOG=debug cortex-mem-mcp --config /path/to/config.toml --tenant default

命令行参数

参数	默认值	描述
--config / -c	config.toml	配置文件路径
--tenant

环境变量

变量	描述
CORTEXDATADIR	覆盖数据目录路径
RUST_LOG

日志级别（debug、info、warn、error） |

何时使用此技能

在以下场景中使用此技能：

- 记住用户偏好 - 存储和召回用户特定的设置、偏好和上下文
持久化对话上下文 - 保留过去对话中的重要信息以便访问
构建项目知识 - 随时间积累和检索项目特定信息
追踪用户与代理的交互 - 维护交互历史以实现更好的个性化
语义搜索记忆 - 使用自然语言查询查找相关信息

可用工具

存储工具

store

将消息添加到特定会话的记忆中。

json
{
content: 用户在所有应用中偏好深色模式,
thread_id: project-alpha,
role: user
}

- content：要存储的消息内容
thread_id：可选的会话/线程标识符（默认为 default）
role：消息角色 - user、assistant 或 system

commit

提交累积的对话内容并触发记忆提取。

json
{
thread_id: project-alpha
}

这将触发：

- 记忆提取（会话 → 用户/代理记忆）
L0/L1 层生成
向量索引

搜索工具

search

使用 L0/L1/L2 分层检索进行分层语义搜索。

json
{
query: 用户对 UI 的偏好,
scope: project-alpha,
limit: 10,
min_score: 0.5,
return_layers: [L0, L1]
}

recall

召回带有完整上下文的记忆（L0 片段 + L2 内容）。

json
{
query: 我们讨论了关于认证的什么内容,
scope: project-alpha,
limit: 5
}

导航工具

ls

列出目录内容以浏览记忆空间。

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

常用 URI：

- cortex://session - 列出所有会话
cortex://user - 列出用户级记忆
cortex://user/preferences - 用户偏好记忆

explore

智能探索记忆空间，结合搜索和浏览功能。

json
{
query: 认证实现细节,
start_uri: cortex://session,
return_layers: [L0]
}

分层访问工具

记忆按层级组织以实现高效的上下文管理：

层级	大小	用途
L0	~100 tokens	快速相关性检查（摘要）
L1

abstract

获取 L0 摘要层以进行快速相关性检查。

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

overview

获取

持久记忆增强

持久记忆增强

Cortex Memory MCP Skill

Prerequisites Check

Installation

Option 1: Install from crates.io (Recommended)

Option 2: Build from Source

Option 3: Download Pre-built Binary

Configuration

Step 1: Create Configuration File

Step 2: Start Qdrant (Vector Database)

Step 3: Configure MCP Client

Claude Desktop

Cursor IDE

Step 4: Restart Your MCP Client

Step 5: Verify Installation

Command-line Arguments

Environment Variables

When to Use This Skill

Available Tools

Storage Tools

store

commit

Search Tools

search

recall

Navigation Tools

ls

explore

Tiered Access Tools

abstract

overview

content

Management Tools

delete

layers

index

Memory URI Structure

Best Practices

Example Workflow

Storing a User Preference

Recalling Past Context

Building Project Knowledge

Auto-Trigger Feature

Configuration

Cortex Memory MCP 技能

前置条件检查

检查 cortex-mem-mcp 是否在 PATH 中

安装

方式一：从 crates.io 安装（推荐）

方式二：从源码构建

克隆仓库

构建发布版二进制文件

二进制文件位于：

./target/release/cortex-mem-mcp (Linux/macOS)

.\target\release\cortex-mem-mcp.exe (Windows)

方式三：下载预构建二进制文件

配置

步骤一：创建配置文件

存储记忆的数据目录

LLM API 配置

嵌入配置

向量数据库配置

步骤二：启动 Qdrant（向量数据库）

使用 Docker

验证 Qdrant 是否运行

步骤三：配置 MCP 客户端

Claude Desktop

Cursor IDE

步骤四：重启 MCP 客户端

步骤五：验证安装

使用调试日志运行

命令行参数

环境变量

何时使用此技能

可用工具

存储工具

store

commit

搜索工具

`store`

`commit`

`search`

`recall`

`ls`

`explore`

`abstract`

`overview`

`content`

`delete`

`layers`

`index`