Skip to content
Back to search

mem0-mcp

A memory system using mem0 for AI applications. Enables long-term memory for AI agents as a drop-in MCP server.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/pinkpixel-dev/mem0-mcp with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/pinkpixel-dev/mem0-mcp'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/pinkpixel-dev--mem0-mcp/badge.svg)](/listings/pinkpixel-dev--mem0-mcp)

HTML

<a href="/listings/pinkpixel-dev--mem0-mcp"><img src="/api/listings/pinkpixel-dev--mem0-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

You can run this server in three main ways:

Installing via Smithery

To install Mem0 Memory Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@pinkpixel-dev/mem0-mcp-server):

npx -y @smithery/cli install @pinkpixel-dev/mem0-mcp-server --client claude

1. Global Installation (Recommended for frequent use)

Install the package globally and use the `mem0-mcp` command:

npm install -g @pinkpixel/mem0-mcp

After global installation, you can run the server directly:

mem0-mcp

Configure your MCP client to use the global command:

Cloud Storage Configuration (Global Install)

{
  "mcpServers": {
    "mem0-mcp": {
      "command": "mem0-mcp",
      "args": [],
      "env": {
        "MEM0_API_KEY": "YOUR_MEM0_API_KEY_HERE",
        "DEFAULT_USER_ID": "user123",
        "DEFAULT_AGENT_ID": "your-agent-id",
        "DEFAULT_APP_ID": "your-app-id"
      }
    }
  }
}

Supabase Storage Configuration (Global Install)

{
  "mcpServers": {
    "mem0-mcp": {
      "command": "mem0-mcp",
      "args": [],
      "env": {
        "SUPABASE_URL": "YOUR_SUPABASE_PROJECT_URL",
        "SUPABASE_KEY": "YOUR_SUPABASE_ANON_KEY",
        "OPENAI_API_KEY": "YOUR_OPENAI_API_KEY_HERE",
        "DEFAULT_USER_ID": "user123",
        "DEFAULT_AGENT_ID": "your-agent-id",
        "DEFAULT_APP_ID": "your-app-id"
      }
    }
  }
}

Local Storage Configuration (Global Install)

{
  "mcpServers": {
    "mem0-mcp": {
      "command": "mem0-mcp",
      "args": [],
      "env": {
        "OPENAI_API_KEY": "YOUR_OPENAI_API_KEY_HERE",
        "DEFAULT_USER_ID": "user123"
      }
    }
  }
}

2. Using `npx` (Recommended for occasional use)

Configure your MCP client (e.g., Claude Desktop, Cursor, Cline, Roo Code, etc.) to run the server using `npx`:

Cloud Storage Configuration (npx)

{
  "mcpServers": {
    "mem0-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@pinkpixel/mem0-mcp"
      ],
      "env": {
        "MEM0_API_KEY": "YOUR_MEM0_API_KEY_HERE",
        "DEFAULT_USER_ID": "user123",
        "DEFAULT_AGENT_ID": "your-agent-id",
        "DEFAULT_APP_ID": "your-app-id"
      }
    }
  }
}

Supabase Storage Configuration (npx)

{
  "mcpServers": {
    "mem0-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@pinkpixel/mem0-mcp"
      ],
      "env": {
        "SUPABASE_URL": "YOUR_SUPABASE_PROJECT_URL",
        "SUPABASE_KEY": "YOUR_SUPABASE_ANON_KEY",
        "OPENAI_API_KEY": "YOUR_OPENAI_API_KEY_HERE",
        "DEFAULT_USER_ID": "user123",
        "DEFAULT_AGENT_ID": "your-agent-id",
        "DEFAULT_APP_ID": "your-app-id"
      }
    }
  }
}

Local Storage Configuration (npx)

{
  "mcpServers": {
    "mem0-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@pinkpixel/mem0-mcp"
      ],
      "env": {
        "OPENAI_API_KEY": "YOUR_OPENAI_API_KEY_HERE",
        "DEFAULT_USER_ID": "user123"
      }
    }
  }
}

3. Running from Cloned Repository

**Note: This method requires you to git clone the repository first.**

Clone the repository, install dependencies, and build the server:

git clone https://github.com/pinkpixel-dev/mem0-mcp
cd mem0-mcp
npm install
npm run build

Then, configure your MCP client to run the built script directly using `node`:

Cloud Storage Configuration (Cloned Repository)

{
  "mcpServers": {
    "mem0-mcp": {
      "command": "node",
      "args": [
        "/absolute/path/to/mem0-mcp/build/index.js"
      ],
      "env": {
        "MEM0_API_KEY": "YOUR_MEM0_API_KEY_HERE",
        "DEFAULT_USER_ID": "user123",
        "DEFAULT_AGENT_ID": "your-agent-id",
        "DEFAULT_APP_ID": "your-app-id"
      }
    }
  }
}

Supabase Storage Configuration (Cloned Repository)

{
  "mcpServers": {
    "mem0-mcp": {
      "command": "node",
      "args": [

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 617 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ![Mem0 MCP Logo](logo.png)
  2. [![npm version](https://badge.fury.io/js/@pinkpixel%2Fmem0-mcp.svg)](https://badge.fury.io/js/@pinkpixel%2Fmem0-mcp)
  3. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  4. [![Node.js](https://img.shields.io/badge/Node.js-18%2B-green.svg)](https://nodejs.org/)
  5. [![TypeScript](https://img.shields.io/badge/TypeScript-5.3%2B-blue.svg)](https://www.typescriptlang.org/)
  6. [![MCP](https://img.shields.io/badge/MCP-0.6.0-purple.svg)](https://modelcontextprotocol.io/)
  7. [![Mem0](https://img.shields.io/badge/Mem0-2.1%2B-orange.svg)](https://mem0.ai)
  8. [![Downloads](https://img.shields.io/npm/dm/@pinkpixel/mem0-mcp.svg)](https://www.npmjs.com/package/@pinkpixel/mem0-mcp)
  9. [![GitHub Stars](https://img.shields.io/github/stars/pinkpixel-dev/mem0-mcp.svg)](https://github.com/pinkpixel-dev/mem0-mcp)
  10. [![smithery badge](https://smithery.ai/badge/@pinkpixel-dev/mem0-mcp-server)](https://smithery.ai/server/@pinkpixel-dev/mem0-mcp-server)
  11. # @pinkpixel/mem0-mcp MCP Server ✨
  12. A Model Context Protocol (MCP) server that integrates with [Mem0.ai](https://mem0.ai/) to provide persistent memory capabilities for LLMs. It allows AI agents to store and retrieve information across sessions.
  13. This server uses the `mem0ai` Node.js SDK for its core functionality.
  14. ## Features 🧠
  15. ### Modernized & Advanced Tools (v0.8.0)
  16. * **`add_memory`**: Stores a memory from text content or structured message arrays.
  17. * **Inputs:** `content` (string) or `messages` (array of role/content objects), `userId` (string), `runId` / `sessionId` (string), `agentId` (string), `appId` (string), `metadata` (object), `infer` (boolean), `customInstructions` (string), `waitForCompletion` (boolean, default: true), `timeoutMs` (number, default: 15000)
  18. * **Behavior:** Cloud V3 additions are asynchronous. By default, this tool polls the background queue until completed. Pass `waitForCompletion: false` to get the `eventId` immediately.
  19. * **`search_memories`**: Searches memories using semantic and BM25 hybrid filters.
  20. * **Inputs:** `query` (string), `userId` (string), `runId` / `sessionId` (string), `agentId` (string), `appId` (string), `filters` (object), `threshold` (number), `topK` (number), `rerank` (boolean), `referenceDate` (string)
  21. * **Behavior:** Automatically nests scope variables inside the V3 `filters` block to prevent API validation errors.
  22. * **`search_memory`**: Backward-compatible alias for `search_memories`.
  23. * **`list_memories`**: Paginated listing of memory records scoped by identifiers.
  24. * **Inputs:** `userId` (string), `runId` / `sessionId` (string), `agentId` (string), `appId` (string), `filters` (object), `page` (number), `pageSize` (number)
  25. * **`get_memory`**: Retrieves a single memory record by its ID.
  26. * **Inputs:** `memoryId` (string)
  27. * **`update_memory`**: Modifies the text or metadata of an existing memory.
  28. * **Inputs:** `memoryId` (string), `text` (string), `metadata` (object)
  29. * **`delete_memory`**: Deletes a specific memory record by ID.
  30. * **Inputs:** `memoryId` (string)
  31. * **`get_memory_history`**: Retrieves the audit trail of memory revisions (cloud only).
  32. * **Inputs:** `memoryId` (string)
  33. * **`get_memory_capabilities`**: Exposes the feature matrix and support flags of the active backend storage mode.
  34. * **Inputs:** None
  35. * **`batch_update_memories`**: Performs bulk updates of text contents for multiple memories (cloud only).
  36. * **Inputs:** `updates` (array of `{ memoryId: string, text: string }` objects)
  37. * **`batch_delete_memories`**: Performs bulk deletions of multiple memories.
  38. * **Inputs:** `memoryIds` (array of strings), `confirm` (boolean, must be `true` to execute)
  39. * **`rate_memory`**: Submits quality feedback evaluation for a memory record (cloud only).
  40. * **Inputs:** `memoryId` (string), `feedback` (string: `positive`, `negative`, `very_negative`), `reason` (string, optional)
  41. * **`get_memory_event`**: Manually retrieves details of a specific background event job (cloud only).
  42. * **Inputs:** `eventId` (string)
  43. * **`list_memory_events`**: Lists history logs of background memory processing events (cloud only).
  44. * **Inputs:** `page` (number), `pageSize` (number)
  45. * **`create_memory_export`**: Initiates an asynchronous memory export query job (cloud only).
  46. * **Inputs:** `schema` (object), `filters` (object, optional), `exportInstructions` (string, optional)
  47. * **`get_memory_export`**: Retrieves status and download metadata of a memory export job (cloud only).
  48. * **Inputs:** `exportId` (string)
  49. ## Prerequisites 🔑
  50. This server supports three storage modes:
  51. 1. **Cloud Storage Mode** ☁️ (Recommended for production)
  52. * Requires a **Mem0 API key** (provided as `MEM0_API_KEY` environment variable)
  53. * Memories are persistently stored on Mem0's cloud servers
  54. * No local database needed
  55. * Full feature support with advanced filtering and search
  56. 2. **Supabase Storage Mode** 🗄️ (Recommended for self-hosting)
  57. * Requires **Supabase credentials** (`SUPABASE_URL` and `SUPABASE_KEY` environment variables)
  58. * Requires **OpenAI API key** (`OPENAI_API_KEY` environment variable) for embeddings
  59. * Memories are persistently stored in your Supabase database
  60. * Free tier available, self-hostable option
  61. * Requires initial database setup (SQL migrations provided below)
  62. 3. **Local Storage Mode** 💾 (Development/testing only)
  63. * Requires an **OpenAI API key** (provided as `OPENAI_API_KEY` environment variable)
  64. * Memories are stored in an in-memory vector database (non-persistent by default)
  65. * Data is lost when the server restarts unless configured for persistent storage
  66. ## Installation & Configuration ⚙️
  67. You can run this server in three main ways:
  68. ### Installing via Smithery
  69. To install Mem0 Memory Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@pinkpixel-dev/mem0-mcp-server):
  70. ```bash
  71. npx -y @smithery/cli install @pinkpixel-dev/mem0-mcp-server --client claude
  72. ```
  73. ### 1. Global Installation (Recommended for frequent use)
  74. Install the package globally and use the `mem0-mcp` command:
  75. ```bash
  76. npm install -g @pinkpixel/mem0-mcp
  77. ```
  78. After global installation, you can run the server directly:
  79. ```bash
  80. mem0-mcp
  81. ```
  82. Configure your MCP client to use the global command:
  83. #### Cloud Storage Configuration (Global Install)
  84. ```json
  85. {
  86. "mcpServers": {
  87. "mem0-mcp": {
  88. "command": "mem0-mcp",
  89. "args": [],
  90. "env": {
  91. "MEM0_API_KEY": "YOUR_MEM0_API_KEY_HERE",
  92. "DEFAULT_USER_ID": "user123",
  93. "DEFAULT_AGENT_ID": "your-agent-id",
  94. "DEFAULT_APP_ID": "your-app-id"
  95. }
  96. }
  97. }
  98. }
  99. ```
  100. #### Supabase Storage Configuration (Global Install)
  101. ```json
  102. {
  103. "mcpServers": {
  104. "mem0-mcp": {
  105. "command": "mem0-mcp",
  106. "args": [],
  107. "env": {
  108. "SUPABASE_URL": "YOUR_SUPABASE_PROJECT_URL",
  109. "SUPABASE_KEY": "YOUR_SUPABASE_ANON_KEY",
  110. "OPENAI_API_KEY": "YOUR_OPENAI_API_KEY_HERE",
  111. "DEFAULT_USER_ID": "user123",
  112. "DEFAULT_AGENT_ID": "your-agent-id",
  113. "DEFAULT_APP_ID": "your-app-id"
  114. }
  115. }
  116. }
  117. }
  118. ```
  119. #### Local Storage Configuration (Global Install)
  120. ```json
  121. {
  122. "mcpServers": {
  123. "mem0-mcp": {
  124. "command": "mem0-mcp",
  125. "args": [],
  126. "env": {
  127. "OPENAI_API_KEY": "YOUR_OPENAI_API_KEY_HERE",
  128. "DEFAULT_USER_ID": "user123"
  129. }
  130. }
  131. }
  132. }
  133. ```
  134. ### 2. Using `npx` (Recommended for occasional use)
  135. Configure your MCP client (e.g., Claude Desktop, Cursor, Cline, Roo Code, etc.) to run the server using `npx`:
  136. #### Cloud Storage Configuration (npx)
  137. ```json
  138. {
  139. "mcpServers": {
  140. "mem0-mcp": {
  141. "command": "npx",
  142. "args": [
  143. "-y",
  144. "@pinkpixel/mem0-mcp"
  145. ],
  146. "env": {
  147. "MEM0_API_KEY": "YOUR_MEM0_API_KEY_HERE",
  148. "DEFAULT_USER_ID": "user123",
  149. "DEFAULT_AGENT_ID": "your-agent-id",
  150. "DEFAULT_APP_ID": "your-app-id"
  151. }
  152. }
  153. }
  154. }
  155. ```
  156. #### Supabase Storage Configuration (npx)
  157. ```json
  158. {
  159. "mcpServers": {
  160. "mem0-mcp": {
  161. "command": "npx",
  162. "args": [
  163. "-y",
  164. "@pinkpixel/mem0-mcp"
  165. ],
  166. "env": {
  167. "SUPABASE_URL": "YOUR_SUPABASE_PROJECT_URL",
  168. "SUPABASE_KEY": "YOUR_SUPABASE_ANON_KEY",
  169. "OPENAI_API_KEY": "YOUR_OPENAI_API_KEY_HERE",
  170. "DEFAULT_USER_ID": "user123",
  171. "DEFAULT_AGENT_ID": "your-agent-id",
  172. "DEFAULT_APP_ID": "your-app-id"
  173. }
  174. }
  175. }
  176. }
  177. ```
  178. #### Local Storage Configuration (npx)
  179. ```json
  180. {
  181. "mcpServers": {
  182. "mem0-mcp": {
  183. "command": "npx",
  184. "args": [
  185. "-y",
  186. "@pinkpixel/mem0-mcp"
  187. ],
  188. "env": {
  189. "OPENAI_API_KEY": "YOUR_OPENAI_API_KEY_HERE",
  190. "DEFAULT_USER_ID": "user123"
  191. }
  192. }
  193. }
  194. }
  195. ```
  196. ### 3. Running from Cloned Repository
  197. **Note: This method requires you to git clone the repository first.**
  198. Clone the repository, install dependencies, and build the server:
  199. ```bash
  200. git clone https://github.com/pinkpixel-dev/mem0-mcp
  201. cd mem0-mcp
  202. npm install
  203. npm run build
  204. ```
  205. Then, configure your MCP client to run the built script directly using `node`:
  206. #### Cloud Storage Configuration (Cloned Repository)
  207. ```json
  208. {
  209. "mcpServers": {
  210. "mem0-mcp": {
  211. "command": "node",
  212. "args": [
  213. "/absolute/path/to/mem0-mcp/build/index.js"
  214. ],
  215. "env": {
  216. "MEM0_API_KEY": "YOUR_MEM0_API_KEY_HERE",
  217. "DEFAULT_USER_ID": "user123",
  218. "DEFAULT_AGENT_ID": "your-agent-id",
  219. "DEFAULT_APP_ID": "your-app-id"
  220. }
  221. }
  222. }
  223. }
  224. ```
  225. #### Supabase Storage Configuration (Cloned Repository)
  226. ```json
  227. {
  228. "mcpServers": {
  229. "mem0-mcp": {
  230. "command": "node",
  231. "args": [
  232. "/absolute/path/to/mem0-mcp/build/index.js"
  233. ],
  234. "env": {
  235. "SUPABASE_URL": "YOUR_SUPABASE_PROJECT_URL",
  236. "SUPABASE_KEY": "YOUR_SUPABASE_ANON_KEY",
  237. "OPENAI_API_KEY": "YOUR_OPENAI_API_KEY_HERE",
  238. "DEFAULT_USER_ID": "user123",
  239. "DEFAULT_AGENT_ID": "your-agent-id",
  240. "DEFAULT_APP_ID": "your-app-id"
  241. }
  242. }
  243. }
  244. }
  245. ```
  246. #### Local Storage Configuration (Cloned Repository)
  247. ```json
  248. {
  249. "mcpServers": {
  250. "mem0-mcp": {
  251. "command": "node",
  252. "args": [
  253. "/absolute/path/to/mem0-mcp/build/index.js"
  254. ],
  255. "env": {
  256. "OPENAI_API_KEY": "YOUR_OPENAI_API_KEY_HERE",
  257. "DEFAULT_USER_ID": "user123"
  258. },
  259. "disabled": false,
  260. "alwaysAllow": [
  261. "add_memory",
  262. "search_memory",
  263. "delete_memory"
  264. ]
  265. }
  266. }
  267. }
  268. ```
  269. **Important Notes:**
  270. 1. Replace `/absolute/path/to/mem0-mcp/` with the actual absolute path to your cloned repository
  271. 2. Use the `build/index.js` file, not the `src/index.ts` file
  272. 3. The MCP server requires clean stdout for protocol communication - any libraries or code that writes to stdout may interfere with the protocol
  273. ## Supabase Setup 🗄️
  274. If you choose to use Supabase storage mode, you'll need to set up your Supabase database with the required table.
  275. ### 1. Create a Supabase Project
  276. 1. Go to [supabase.com](https://supabase.com) and create a new project
  277. 2. Note your project URL and anon key from the project settings
  278. ### 2. Run SQL Migrations
  279. Run these SQL commands in your Supabase SQL Editor:
  280. ```sql
  281. -- Enable the vector extension
  282. create extension if not exists vector;
  283. -- Create the memories table
  284. create table if not exists memories (
  285. id text primary key,
  286. embedding vector(1536),
  287. metadata jsonb,
  288. created_at timestamp with time zone default timezone('utc', now()),
  289. updated_at timestamp with time zone default timezone('utc', now())
  290. );
  291. -- Create the vector similarity search function
  292. create or replace function match_vectors(
  293. query_embedding vector(1536),
  294. match_count int,
  295. filter jsonb default '{}'::jsonb
  296. )
  297. returns table (
  298. id text,
  299. similarity float,
  300. metadata jsonb
  301. )
  302. language plpgsql
  303. as $$
  304. begin
  305. return query
  306. select
  307. t.id::text,
  308. 1 - (t.embedding <=> query_embedding) as similarity,
  309. t.metadata
  310. from memories t
  311. where case
  312. when filter::text = '{}'::text then true
  313. else t.metadata @> filter
  314. end
  315. order by t.embedding <=> query_embedding
  316. limit match_count;
  317. end;
  318. $$;
  319. -- Create the memory_history table for history tracking
  320. create table if not exists memory_history (
  321. id text primary key,
  322. memory_id text not null,
  323. previous_value text,
  324. new_value text,
  325. action text not null,
  326. created_at timestamp with time zone default timezone('utc', now()),
  327. updated_at timestamp with time zone,
  328. is_deleted integer default 0
  329. );
  330. ```
  331. ### 3. Set Environment Variables
  332. Add these to your MCP configuration:
  333. - `SUPABASE_URL`: Your Supabase project URL (e.g., `https://your-project.supabase.co`)
  334. - `SUPABASE_KEY`: Your Supabase anon key
  335. - `OPENAI_API_KEY`: Your OpenAI API key (for embeddings)
  336. ### Benefits of Supabase Mode
  337. ✅ **Persistent Storage** - Data survives server restarts
  338. ✅ **Free Tier Available** - Generous free tier for development
  339. ✅ **Self-Hostable** - Can run your own Supabase instance
  340. ✅ **Scalable** - Grows with your needs
  341. ✅ **SQL Access** - Direct database access for advanced queries
  342. ✅ **Real-time Features** - Built-in real-time subscriptions
  343. ## Parameter Configuration 🎯
  344. ### Understanding Mem0 Parameters
  345. The server uses four key parameters to organize and scope memories:
  346. 1. **`userId`** - Identifies the user (required)
  347. 2. **`agentId`** - Identifies the LLM/agent making the tool call (optional)
  348. 3. **`appId`** - Identifies the user's project/application - **this controls project scope!** (optional)
  349. 4. **`sessionId`** - Identifies the conversation session (maps to `run_id` in Mem0) (optional)
  350. ### Environment Variable Fallbacks 🔄
  351. The MCP server supports environment variable fallbacks for user identification and project settings:
  352. - `DEFAULT_USER_ID`: Fallback user ID when not provided in tool calls
  353. - `DEFAULT_AGENT_ID`: Fallback agent ID for identifying the LLM/agent
  354. - `DEFAULT_APP_ID`: Fallback app ID for project scoping
  355. #### **Priority Order (Important!)**
  356. 1. **Tool Parameters** (highest priority) - Values provided by the LLM in tool calls
  357. 2. **Environment Variables** (fallback) - Values from your MCP configuration
  358. #### **Example Behavior:**
  359. ```json
  360. // Your MCP config
  361. "env": {
  362. "DEFAULT_USER_ID": "john-doe",
  363. "DEFAULT_AGENT_ID": "my-assistant",
  364. "DEFAULT_APP_ID": "my-project"
  365. }
  366. ```
  367. **If LLM provides parameters:**
  368. ```json
  369. {
  370. "tool": "add_memory",
  371. "arguments": {
  372. "content": "Remember this",
  373. "userId": "session-123", // ← Overrides DEFAULT_USER_ID
  374. "agentId": "different-agent", // ← Overrides DEFAULT_AGENT_ID
  375. "appId": "special-project" // ← Overrides DEFAULT_APP_ID
  376. // sessionId omitted // ← No fallback, will be undefined
  377. }
  378. }
  379. ```
  380. **Result**: Uses `session-123`, `different-agent`, and `special-project`
  381. **If LLM omits parameters:**
  382. ```json
  383. {
  384. "tool": "add_memory",
  385. "arguments": {
  386. "content": "Remember this"
  387. // All IDs omitted - uses environment variables
  388. }
  389. }
  390. ```
  391. **Result**: Uses `john-doe`, `my-assistant`, and `my-project`
  392. #### **Controlling LLM Behavior**
  393. To ensure your environment variables are used, instruct your LLM:
  394. - *"Use the default user ID configured in the environment"*
  395. - *"Don't specify userId, agentId, or appId parameters"*
  396. - *"Let the server use the configured defaults"*
  397. #### **System Prompt Recommendation**
  398. For best results, include instructions in your system prompt like:
  399. ```
  400. When creating memories, use:
  401. - agentId: "my-assistant"
  402. - appId: "my-project"
  403. - sessionId: "current-conversation-id"
  404. ```
  405. Example configuration using `DEFAULT_USER_ID`:
  406. ```json
  407. {
  408. "mcpServers": {
  409. "mem0-mcp": {
  410. "command": "npx",
  411. "args": [
  412. "-y",
  413. "@pinkpixel/mem0-mcp"
  414. ],
  415. "env": {
  416. "MEM0_API_KEY": "YOUR_MEM0_API_KEY_HERE",
  417. "DEFAULT_USER_ID": "user123",
  418. "ORG_ID": "your-org-id",
  419. "PROJECT_ID": "your-project-id"
  420. }
  421. }
  422. }
  423. }
  424. ```
  425. Or when running directly with `node`:
  426. ```bash
  427. git clone https://github.com/pinkpixel-dev/mem0-mcp
  428. cd mem0-mcp
  429. npm install
  430. npm run build
  431. ```
  432. ```json
  433. {
  434. "mcpServers": {
  435. "mem0-mcp": {
  436. "command": "node",
  437. "args": [
  438. "path/to/mem0-mcp/build/index.js"
  439. ],
  440. "env": {
  441. "OPENAI_API_KEY": "YOUR_OPENAI_API_KEY_HERE",
  442. "DEFAULT_USER_ID": "user123"
  443. }
  444. }
  445. }
  446. }
  447. ```
  448. ## Storage Mode Comparison 🔄
  449. ### Cloud Storage (Mem0 API) ☁️
  450. * **Persistent by default** - Your memories remain available across sessions and server restarts
  451. * **No local database required** - All data is stored on Mem0's servers
  452. * **Higher retrieval quality** - Uses Mem0's optimized search algorithms
  453. * **Additional fields** - Supports `agent_id` and `threshold` parameters
  454. * **Fully managed** - No setup or maintenance required
  455. * **Requires** - A Mem0 API key
  456. ### Supabase Storage 🗄️
  457. * **Persistent storage** - Data is stored in your Supabase PostgreSQL database
  458. * **Free tier available** - Generous free tier for development and small projects
  459. * **Self-hostable** - Can run your own Supabase instance for complete control
  460. * **SQL access** - Direct database access for advanced queries and analytics
  461. * **Scalable** - Grows with your needs, from free tier to enterprise
  462. * **Vector search** - Uses pgvector extension for efficient similarity search
  463. * **Real-time features** - Built-in real-time subscriptions and webhooks
  464. * **Requires** - Supabase project setup and OpenAI API key for embeddings
  465. ### Local Storage (OpenAI API) 💾
  466. * **In-memory by default** - Data is stored only in RAM and is **not persistent long-term**. While some caching may occur, you should not rely on this for permanent storage.
  467. * **Data loss risk** - Memory data will be lost on server restart, system reboot, or if the process is terminated
  468. * **Recommended for** - Development, testing, or temporary use only
  469. * **For persistent storage** - Use the Cloud Storage or Supabase options if you need reliable long-term memory
  470. * **Uses OpenAI embeddings** - For vector search functionality
  471. * **Self-contained** - All data stays on your machine
  472. * **Requires** - An OpenAI API key
  473. ## Development 💻
  474. Clone the repository and install dependencies:
  475. ```bash
  476. git clone https://github.com/pinkpixel-dev/mem0-mcp
  477. cd mem0-mcp
  478. npm install
  479. ```
  480. Build the server:
  481. ```bash
  482. npm run build
  483. ```
  484. For development with auto-rebuild on file changes:
  485. ```bash
  486. npm run watch
  487. ```
  488. ## Debugging 🐞
  489. Since MCP servers communicate over stdio, debugging can be challenging. Here are some approaches:
  490. 1. **Use the MCP Inspector**: This tool can monitor the MCP protocol communication:
  491. ```bash
  492. npm run inspector
  493. ```
  494. 2. **Console Logging**: When adding console logs, always use `console.error()` instead of `console.log()` to avoid interfering with the MCP protocol
  495. 3. **Environment Files**: Use a `.env` file for local development to simplify setting API keys and other configuration options
  496. ## Technical Implementation Notes 🔧
  497. ### 1. Platform V3 Async Additions & Polling
  498. Mem0 Cloud V3 addition is an asynchronous background task. When calling `add_memory`, the server submits the request to `/v3/memories/add/` and receives an `eventId`.
  499. * **Synchronous Polling (Default):** The server polls the event status endpoint (`/v1/event/{id}/`) every 500ms for up to `timeoutMs` (default `15000`ms) until the status becomes `SUCCEEDED` or `FAILED`. Once resolved, it returns the final outcome.
  500. * **Asynchronous Execution:** Pass `"waitForCompletion": false` to bypass polling. The server will immediately return the `eventId` and a `PENDING` status.
  501. ### 2. Nested V3 Filter Normalization
  502. The Mem0 Cloud V3 search and list endpoints reject top-level scope IDs (`user_id`, `agent_id`, `app_id`, `run_id`) and return an HTTP 400 error. V3 requires these fields inside the nested `filters` object.
  503. To prevent breaking client configurations, this server automatically normalizes top-level scope variables (`userId`, `agentId`, `appId`, `runId`/`sessionId`) and merges them into the nested `filters` object under the hood before sending the API request.
  504. ### 3. Capability Gating
  505. Different backends support different feature sets. Call `get_memory_capabilities` to get a structured capability matrix of the active backend.
  506. * **Cloud Mode:** Fully supports all features (`apiVersion: "v3"`, async events, listing, audit histories, logical queries).
  507. * **Supabase / Local Modes:** Standard V1 vector interfaces. Unsupported cloud-specific tools (like `get_memory_history` or `list_memories`) will fail gracefully with clear feature-unavailable messages.
  508. ### 4. Logging & Protocol Stability
  509. MCP servers communicate using JSON-RPC over `stdout`. Any unexpected library logs printed to `stdout` will corrupt the protocol channel and cause clients to crash.
  510. This server overrides the default `console` output methods (such as `console.log`) to redirect/mute standard logging, ensuring clean stdio communication.
  511. ---
  512. Made with 💖 by Pink Pixel

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.