# https://github.com/pinkpixel-dev/mem0-mcp Project Manual Generated at: 2026-06-25 01:46:12 UTC ## Table of Contents - [Project Overview and Architecture](#page-1) - [Memory Tools and API Reference](#page-2) - [Configuration, Parameters, and Storage Modes](#page-3) - [Troubleshooting and Common Failure Modes](#page-4) ## Project Overview and Architecture ### Related Pages Related topics: [Memory Tools and API Reference](#page-2), [Configuration, Parameters, and Storage Modes](#page-3)
Related Source Files The following source files were used to generate this page: - [README.md](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/README.md) - [OVERVIEW.md](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/OVERVIEW.md) - [package.json](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/package.json) - [CHANGELOG.md](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/CHANGELOG.md) - [PARAMETER_GUIDE.md](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/PARAMETER_GUIDE.md) - [glama.json](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/glama.json) - [update-server.md](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/update-server.md) - [src/index.ts](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/src/index.ts) - [src/types.ts](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/src/types.ts) - [src/backends/base.ts](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/src/backends/base.ts) - [src/backends/cloud.ts](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/src/backends/cloud.ts) - [src/backends/supabase.ts](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/src/backends/supabase.ts) - [src/backends/local.ts](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/src/backends/local.ts)
# Project Overview and Architecture ## Purpose and Scope mem0-mcp is a Model Context Protocol (MCP) server that exposes the [mem0](https://mem0.ai) memory platform to MCP-compatible LLM clients such as Cursor, RooCode, and Claude Desktop. It allows agents to persist, retrieve, list, update, and delete long-term memories across conversations by mapping Mem0's REST surface onto a small set of JSON-RPC tools (e.g., `add_memory`, `search_memory`, `list_memories`, `get_memory`, `update_memory`, `delete_memory`). Source: [src/index.ts](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/src/index.ts). The server is published as the npm package `@pinkpixel/mem0-mcp` and is maintained as part of the `pinkpixel-dev` organization. The package metadata is tracked in [glama.json](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/glama.json), which lists `sizzlebop` as the sole maintainer. Source: [glama.json](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/glama.json). Versioning and significant behavioral changes are documented in [CHANGELOG.md](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/CHANGELOG.md). Notable milestones include the v0.5.0 "BREAKING CHANGE" that corrected scope-control parameters to use `app_id`/`agent_id`/`run_id` (instead of the non-functional `orgId`/`projectId` previously advertised), and v0.7.0 which migrated the codebase to the Platform V3 SDK (`mem0ai@^3.0.10`) and split the monolithic entry point into modular backend adapters. Source: [CHANGELOG.md](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/CHANGELOG.md). ## High-Level Architecture The server follows a classic MCP tool-server pattern: a single Node.js process listens on stdio, registers tool schemas, and delegates every data operation to a swappable **backend adapter**. The diagram below captures the runtime flow and the modular split introduced in v0.7.0. Source: [OVERVIEW.md](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/OVERVIEW.md). ```mermaid flowchart LR A[MCP Client
Cursor / RooCode / Claude Desktop] -->|JSON-RPC over stdio| B[Mem0MCPServer
src/index.ts] B -->|Tool Call| C[SafeLogger
stdout-free logging] B -->|Resolve scope params| D{Env defaults +
tool arguments} D -->|cloud mode| E[CloudBackend
backends/cloud.ts] D -->|supabase mode| F[SupabaseBackend
backends/supabase.ts] D -->|local mode| G[LocalBackend
backends/local.ts] E -->|HTTPS V3 API| H[(Mem0 Cloud
Platform V3)] F -->|pgvector| I[(Supabase Postgres)] G -->|in-memory| J[(RAM store)] B -->|Capability gating| K[Tool registry
add/search/list/get/update/delete] ``` Key responsibilities are distributed as follows: - **`Mem0MCPServer`** (in `src/index.ts`) registers JSON-RPC tool schemas, owns the request lifecycle, and exposes a `ListToolsRequestSchema` / `CallToolRequestSchema` handler. Source: [src/index.ts](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/src/index.ts). - **`SafeLogger`** wraps the standard logger so that no debug output is written to stdout, which would otherwise corrupt the MCP protocol channel. Source: [OVERVIEW.md](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/OVERVIEW.md). - **`MemoryBackend` (abstract)** in `src/backends/base.ts` defines the contract that every adapter must implement (`add`, `search`, `list`, `get`, `update`, `delete`, plus `getCapabilities`). Source: [src/backends/base.ts](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/src/backends/base.ts). - **Adapters** — `cloud.ts`, `supabase.ts`, `local.ts` — translate scope parameters and V3 async semantics (event IDs, polling) into the right transport. Source: [src/backends/cloud.ts](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/src/backends/cloud.ts), [src/backends/supabase.ts](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/src/backends/supabase.ts), [src/backends/local.ts](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/src/backends/local.ts). ## Backend Modes and Capability Gating The active backend is selected at startup based on which environment variables are present. The mapping and primary trade-offs are summarized below. Source: [OVERVIEW.md](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/OVERVIEW.md), [PARAMETER_GUIDE.md](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/PARAMETER_GUIDE.md). | Mode | Trigger Env Vars | Storage | Async / Polling | Recommended For | |------|------------------|---------|------------------|-----------------| | Cloud | `MEM0_API_KEY` | Mem0 Platform V3 (hosted) | Yes — V3 additions return an `eventId` and `CloudBackend` polls for completion | Production | | Supabase | `SUPABASE_URL`, `SUPABASE_KEY`, `OPENAI_API_KEY` | Self-hosted Postgres + pgvector | No (synchronous) | Self-hosting, data residency | | Local | `OPENAI_API_KEY` only (no remote creds) | In-memory RAM | No | Development and tests | Tool invocations carry a mix of **tool arguments** and **environment fallbacks** such as `DEFAULT_USER_ID`, `DEFAULT_AGENT_ID`, `DEFAULT_APP_ID`, `DEFAULT_ORG_ID`, and `DEFAULT_PROJECT_ID`. Tool arguments always win when both are present. Source: [PARAMETER_GUIDE.md](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/PARAMETER_GUIDE.md). The `AddResult` type returned by the cloud adapter is `SUCCEEDED | PENDING | FAILED` plus an `eventId`, which reflects the asynchronous V3 write model. Source: [src/types.ts](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/src/types.ts). The `cloud` adapter is the only one that performs background polling because V3 additions are asynchronous; the `supabase` and `local` adapters resolve their writes synchronously and return the materialized `MemoryRecord[]`. Source: [src/types.ts](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/src/types.ts). ## Community-Noted Issues and Configuration Caveats The repository's issue tracker surfaces several recurring friction points that are worth understanding before deploying the server. - **`search_memory` returning empty arrays** — Issue [#4](https://github.com/pinkpixel-dev/mem0-mcp/issues/4) reported that searches consistently returned `[]` even after a successful `add_memory`. The fix shipped in a later npm release, but issue [#6](https://github.com/pinkpixel-dev/mem0-mcp/issues/6) confirms that callers still **must pass `userId` explicitly** for `search_memory` to work, even when `DEFAULT_USER_ID` is configured. Source: community issue tracker. - **`DEFAULT_USER_ID` ignored in cloud mode** — Issue [#3](https://github.com/pinkpixel-dev/mem0-mcp/issues/3) reports that `DEFAULT_USER_ID`, `ORG_ID`, and `PROJECT_ID` were not propagated to the Mem0 dashboard. v0.5.0 corrected the underlying parameter mapping to `app_id` / `agent_id` / `run_id`, which is what actually controls scope on the Mem0 side. Source: [CHANGELOG.md](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/CHANGELOG.md), community issue [#3](https://github.com/pinkpixel-dev/mem0-mcp/issues/3). - **API key handling** — Issue [#2](https://github.com/pinkpixel-dev/mem0-mcp/issues/2) recommends loading secrets from an `envFile` rather than embedding them in `mcp.json`. Source: community issue [#2](https://github.com/pinkpixel-dev/mem0-mcp/issues/2). - **MCP connection failures** — Issue [#1](https://github.com/pinkpixel-dev/mem0-mcp/issues/1) describes a "No connection found for server" error in RooCode after a working setup stopped, often caused by the client dropping the stdio transport. Source: community issue [#1](https://github.com/pinkpixel-dev/mem0-mcp/issues/1). Looking ahead, the design notes in [update-server.md](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/update-server.md) recommend tightening tool names (e.g., `search_memories` over `search_memory`), adding `get_memory_capabilities` for explicit capability gating, and being conservative with destructive batch tools so agents cannot silently purge memory stores. ## See Also - [CHANGELOG.md](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/CHANGELOG.md) — Version-by-version behavioral changes - [PARAMETER_GUIDE.md](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/PARAMETER_GUIDE.md) — Scope identifiers and debugging tips - [update-server.md](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/update-server.md) — Proposed V3-era tool surface --- ## Memory Tools and API Reference ### Related Pages Related topics: [Project Overview and Architecture](#page-1), [Configuration, Parameters, and Storage Modes](#page-3), [Troubleshooting and Common Failure Modes](#page-4)
Related Source Files The following source files were used to generate this page: - [README.md](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/README.md) - [src/types.ts](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/src/types.ts) - [src/backends/base.ts](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/src/backends/base.ts) - [src/backends/supabase.ts](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/src/backends/supabase.ts) - [CHANGELOG.md](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/CHANGELOG.md) - [PARAMETER_GUIDE.md](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/PARAMETER_GUIDE.md) - [ROADMAP.md](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/ROADMAP.md) - [OVERVIEW.md](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/OVERVIEW.md) - [MEMORY.md](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/MEMORY.md) - [package.json](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/package.json)
# Memory Tools and API Reference The `@pinkpixel/mem0-mcp` server exposes a stable Model Context Protocol (MCP) tool surface that lets an LLM agent store, retrieve, search, and audit memories through three swappable backend adapters (Cloud, Supabase, Local) ([OVERVIEW.md:](), [src/backends/base.ts:]()). This page is the canonical reference for every tool name, input shape, return type, and capability flag a client can rely on. ## Architecture at a Glance ```mermaid flowchart LR Agent[LLM Agent / MCP Client] -->|JSON-RPC| Server[Mem0MCPServer] Server -->|tool dispatch| Backend{{MemoryBackend (abstract)}} Backend --> Cloud[CloudBackend
mem0ai v3.0.10] Backend --> Supabase[SupabaseBackend
pgvector + OpenAI] Backend --> Local[LocalBackend
in-memory] Cloud -->|async polling| API[(Mem0 Platform V3 API)] Supabase --> DB[(PostgreSQL / pgvector)] Local --> RAM[(Process Memory)] ``` The contract every backend must satisfy is defined in [src/backends/base.ts]() as the `MemoryBackend` abstract class, which declares the seven core operations (`add`, `search`, `list`, `get`, `update`, `delete`, plus an optional `getHistory`) and a `getCapabilities()` probe. Tool names and JSON schemas are registered centrally by `Mem0MCPServer` and dispatched to the active backend ([OVERVIEW.md](), [MEMORY.md:](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/MEMORY.md)). ## Tool Reference All tools accept JSON arguments over MCP's standard `tools/call` channel. The current shipping surface is summarized below. | Tool | Inputs (required → optional) | Output Shape | Notes | |------|------------------------------|--------------|-------| | `add_memory` | `content` or `messages` → `userId`, `agentId`, `appId`, `runId`, `metadata`, `infer`, `customInstructions`, `waitForCompletion`, `timeoutMs` | `AddResult { status, eventId, memories?, error?, elapsedMs? }` | V3 cloud add is async; result returns `SUCCEEDED` / `PENDING` / `FAILED` ([src/types.ts](), [MEMORY.md:]()). | | `search_memory` | `query` → `userId`, `agentId`, `appId`, `runId`, `filters`, `topK`, `threshold`, `rerank`, `referenceDate` | `SearchResult { memories: MemoryRecord[] }` | V3 fuses semantic + BM25 + entity scoring; entity IDs must live inside `filters`, not as top-level fields ([update-server.md](), [src/types.ts:]()). | | `list_memories` | `userId?`, `agentId?`, `appId?`, `runId?`, `filters?`, `page?`, `pageSize?` | `ListResult { count, next, previous, results }` | Paginated browse without a query string ([update-server.md](), [ROADMAP.md:]()). | | `get_memory` | `memoryId` | `MemoryRecord` | Single-record lookup; recommended before `update_memory` / `delete_memory` ([update-server.md:]()). | | `update_memory` | `memoryId` → `text?`, `metadata?` | `MemoryRecord` | Required in V3 because cloud `add` no longer auto-merges duplicates ([update-server.md](), [MEMORY.md:]()). | | `delete_memory` | `memoryId` | `DeleteResult { success, message }` | Single-record deletion ([src/types.ts](), [README.md:]()). | | `get_memory_history` | `memoryId` | array of historical revisions | **Cloud only**; returns previous text, new text, metadata, timestamps ([README.md](), [src/backends/base.ts:]()). | | `get_memory_capabilities` | none | `MemoryCapabilities` | Lets clients discover which tools the active backend supports before calling them ([src/backends/supabase.ts](), [README.md:]()). | Tool schemas and descriptions are advertised by the server per the MCP spec ([package.json:]() pins `@modelcontextprotocol/sdk` to `1.29.0`). The README's "Tools" section ([README.md:]()) lists these names exactly as registered. ## Data Models All tool return values are typed in [src/types.ts](). The two contracts clients encounter most often are: - **`MemoryRecord`** — the canonical memory object: `id`, `memory` (text), `userId`, `agentId`, `appId`, `runId`, `metadata`, `createdAt`, `updatedAt` ([src/types.ts:]()). - **`MemoryCapabilities`** — a backend feature matrix with fields `mode` (`cloud` | `supabase` | `local`), `apiVersion` (`v3` | `v1`), and boolean flags `supportsAsyncEvents`, `supportsListMemories`, `supportsHistory`, `supportsAdvancedFilters`, `supportsBatchOperations` ([src/types.ts](), [src/backends/supabase.ts:]()). Input shapes are similarly normalized: `NormalizedAddInput` accepts both a shorthand `content` string and a full `messages` array, while `NormalizedSearchInput` requires `query` plus optional scope fields ([src/types.ts:]()). This normalization is what lets the same MCP tool surface work against all three backends. ## Backend Capability Matrix The `get_memory_capabilities` tool lets a model avoid calling tools that will fail. The reference values for the Supabase backend, taken directly from [src/backends/supabase.ts](), are: | Flag | Cloud | Supabase | Local | |------|:-----:|:--------:|:-----:| | `apiVersion` | `v3` | `v1` | `v1` | | `supportsAsyncEvents` | ✅ | ❌ | ❌ | | `supportsListMemories` | ✅ | ❌ | ❌ | | `supportsHistory` | ✅ | ❌ | ❌ | | `supportsAdvancedFilters` | ✅ | ❌ | ❌ | | `supportsBatchOperations` | ✅ | ❌ | ❌ | Source: [src/backends/supabase.ts:](), [MEMORY.md:](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/MEMORY.md). The Cloud backend reports the inverse — `apiVersion: 'v3'` with every flag `true` — because V3 cloud operations include event-driven writes, filter mapping, and the `getHistory` audit endpoint ([update-server.md](), [CHANGELOG.md:](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/CHANGELOG.md)). ## Community-Discovered Gotchas Several issues surfaced repeatedly in user reports and are worth highlighting here so newcomers don't re-debug them: 1. **`search_memory` returned empty arrays** in versions ≤ 0.5.x because the underlying SDK path silently dropped `user_id` scope parameters ([issue #4](https://github.com/pinkpixel-dev/mem0-mcp/issues/4)). The 0.7.0 release resolves this by switching to direct REST calls against the V3 API and normalizing scope into `filters` ([CHANGELOG.md](), [MEMORY.md:]()). 2. **`DEFAULT_USER_ID` config setting had no effect** in cloud mode ([issue #3](https://github.com/pinkpixel-dev/mem0-mcp/issues/3)) — clients must pass `userId` explicitly on each call. Issue #6 confirms the search fix only sticks when `userId` is provided per call ([issue #6](https://github.com/pinkpixel-dev/mem0-mcp/issues/6)). For per-call usage patterns, see [PARAMETER_GUIDE.md:](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/PARAMETER_GUIDE.md). 3. **Storing API keys directly in `mcp.json`** was flagged as a security concern ([issue #2](https://github.com/pinkpixel-dev/mem0-mcp/issues/2)). Prefer the client's `envFile` mechanism over inline `env` entries for `MEM0_API_KEY`, `OPENAI_API_KEY`, `SUPABASE_URL`, and `SUPABASE_KEY`. 4. **Connection drops with `npx -y @pinkpixel/mem0-mcp`** ([issue #1](https://github.com/pinkpixel-dev/mem0-mcp/issues/1)) are typically a client-side "Connected MCP Servers" registration problem rather than a server bug; re-registering the server in the IDE/MCP host usually resolves it. ## See Also - [README.md](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/README.md) — full tool descriptions and installation steps - [PARAMETER_GUIDE.md](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/PARAMETER_GUIDE.md) — `userId` / `agentId` / `appId` / `runId` / `projectId` / `orgId` usage patterns - [CHANGELOG.md](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/CHANGELOG.md) — version history (notably 0.7.0 V3 modernization and the 0.5.x API fix chain) - [ROADMAP.md](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/ROADMAP.md) — planned additions such as `batch_update_memories`, `rate_memory`, and `list_memory_events` - [MEMORY.md](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/MEMORY.md) — design rationale for the modular adapter refactor --- ## Configuration, Parameters, and Storage Modes ### Related Pages Related topics: [Project Overview and Architecture](#page-1), [Memory Tools and API Reference](#page-2), [Troubleshooting and Common Failure Modes](#page-4)
Related Source Files The following source files were used to generate this page: - [README.md](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/README.md) - [OVERVIEW.md](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/OVERVIEW.md) - [PARAMETER_GUIDE.md](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/PARAMETER_GUIDE.md) - [CHANGELOG.md](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/CHANGELOG.md) - [src/index.ts](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/src/index.ts) - [src/types.ts](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/src/types.ts) - [src/backends/base.ts](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/src/backends/base.ts) - [src/backends/supabase.ts](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/src/backends/supabase.ts) - [src/backends/local.ts](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/src/backends/local.ts) - [src/backends/cloud.ts](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/src/backends/cloud.ts)
# Configuration, Parameters, and Storage Modes ## Overview The mem0-mcp server exposes a unified set of memory tools (such as `add_memory`, `search_memory`, `list_memories`, `get_memory`, `update_memory`, and `delete_memory`) to any Model Context Protocol (MCP) client. Behind this single tool surface, the server is built around a **modular adapter pattern** that separates the tool layer from the storage layer. Each request flows from a JSON-RPC handler in `src/index.ts` through a `MemoryBackend` contract defined in [src/backends/base.ts:1-18](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/src/backends/base.ts), which is implemented by one of three interchangeable adapters: `CloudBackend`, `SupabaseBackend`, or `LocalBackend` (Source: [src/backends/base.ts:5-18]()). Configuration determines (a) **which backend is active**, (b) **which environment variables supply credentials and default scope identifiers**, and (c) **which scope identifiers are attached to each memory operation**. Misalignment between these three areas is the root cause of the most common community-reported issues, including the `DEFAULT_USER_ID` problem and the `search_memory` empty-result bug (see [issue #3](https://github.com/pinkpixel-dev/mem0-mcp/issues/3) and [issue #4](https://github.com/pinkpixel-dev/mem0-mcp/issues/4)). ## Storage Modes The server supports three storage modes, each implemented as a class that extends `MemoryBackend`: | Mode | Adapter | Required Environment Variables | Best For | Capability Highlights | |------|---------|-------------------------------|----------|----------------------| | `cloud` | `CloudBackend` (`src/backends/cloud.ts`) | `MEM0_API_KEY` | Production use | Async events, history, advanced filters, batch ops | | `supabase` | `SupabaseBackend` (`src/backends/supabase.ts`) | `SUPABASE_URL`, `SUPABASE_KEY`, `OPENAI_API_KEY` | Self-hosting | Persistent PostgreSQL + pgvector storage | | `local` | `LocalBackend` (`src/backends/local.ts`) | `OPENAI_API_KEY` (for embeddings) | Development / quick testing | In-memory vector store, no persistence | Source: [README.md:1-120](), [OVERVIEW.md:1-120](), [src/backends/supabase.ts:7-22](). The active mode is auto-detected from the environment at startup. Each backend reports its own capability matrix through `getCapabilities()`, allowing the server to advertise only the tools it can actually fulfill. For example, `SupabaseBackend.getCapabilities()` explicitly returns `supportsListMemories: false`, `supportsHistory: false`, and `supportsAdvancedFilters: false` (Source: [src/backends/supabase.ts:23-33]()). Cloud mode returns the full feature set, while local mode is limited to the in-memory subset. ## Configuration and Environment Variables The server is launched through an MCP client configuration file (commonly `mcp.json`). The configuration specifies the `command`/`args` used to start the server and an `env` block that supplies credentials and default scope identifiers. A typical cloud-mode configuration looks like: ```json { "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" }, "disabled": false, "alwaysAllow": ["add_memory", "search_memory"] } } } ``` Source: [OVERVIEW.md:1-80](), [CHANGELOG.md:1-80](). The full set of recognized environment variables includes: - `MEM0_API_KEY` — selects cloud mode and authenticates against Mem0's hosted V3 API. - `SUPABASE_URL` / `SUPABASE_KEY` / `SUPABASE_TABLE_NAME` — select supabase mode. - `OPENAI_API_KEY` — required for embeddings in supabase and local modes. - `DEFAULT_USER_ID`, `DEFAULT_AGENT_ID`, `DEFAULT_APP_ID`, `DEFAULT_RUN_ID` — fallback scope identifiers applied when an LLM does not explicitly pass them. The interactive `config_generator.sh` script shipped with the repository walks users through building this block and writing it to disk, the clipboard, or directly into the Cursor IDE configuration (Source: [OVERVIEW.md:1-80]()). ## Parameters and Scope Identifiers Each memory operation is scoped by a combination of identifiers defined as TypeScript contracts in [src/types.ts:1-120](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/src/types.ts): ```ts export interface ListInput { userId?: string; agentId?: string; appId?: string; runId?: string; filters?: Record; page?: number; pageSize?: number; } ``` Source: [src/types.ts:1-120](). The mapping from these camelCase tool parameters to the underlying Mem0 API fields is: | Tool Parameter | API Field | Purpose | |----------------|-----------|---------| | `userId` | `user_id` | The end user the memory belongs to | | `agentId` | `agent_id` | The LLM/agent making the tool call | | `appId` | `app_id` | Application/project scope | | `runId` / `sessionId` | `run_id` | Session/trace identifier | | `metadata` | `metadata` | Arbitrary structured tags | This mapping is a deliberate fix introduced in version 0.5.0: the earlier `orgId`/`projectId` parameters were removed because those IDs are assigned automatically by Mem0 and cannot be overridden by the client. The `appId` field is the correct mechanism for client-side project scoping (Source: [CHANGELOG.md:1-80](), [PARAMETER_GUIDE.md:1-80]()). Parameter precedence follows a strict order: **tool-call argument → environment default → backend default**. This is the source of the `DEFAULT_USER_ID` issue reported in [issue #3](https://github.com/pinkpixel-dev/mem0-mcp/issues/3). When an MCP host silently omits the `userId` argument, the server must fall back to `DEFAULT_USER_ID` from the environment. If the host *does* pass `userId` (even as an empty string), the tool argument wins and the environment default is ignored — which is the exact behavior the user in [issue #6](https://github.com/pinkpixel-dev/mem0-mcp/issues/6) confirmed. ## Capability Gating and Common Failure Modes The `getCapabilities` tool (registered in [src/index.ts:1-120](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/src/index.ts)) exposes the active backend's feature matrix, so clients can introspect which tools and filters are actually available before issuing a request. This is important because the same tool name (e.g. `list_memories`) exists for all backends, but its behavior and filter expressiveness vary. The most common configuration-related failures reported by the community are: 1. **Empty search results** — caused by mismatched scope identifiers between `add_memory` and `search_memory` calls. Always ensure the same `userId` (or whichever scope is used) is passed to both operations (Source: [issue #4](https://github.com/pinkpixel-dev/mem0-mcp/issues/4)). 2. **Ignored `DEFAULT_USER_ID`** — happens when the host passes an explicit (possibly empty) `userId` argument; the environment default is bypassed (Source: [issue #3](https://github.com/pinkpixel-dev/mem0-mcp/issues/3)). 3. **Secrets in `mcp.json`** — storing API keys in plaintext is discouraged; use `envFile` references or a secrets manager when the MCP host supports it (Source: [issue #2](https://github.com/pinkpixel-dev/mem0-mcp/issues/2)). 4. **No connection to server** — typically a transport mismatch (`cmd /c npx ...` on Windows vs. the host's expected launch command) rather than a configuration defect (Source: [issue #1](https://github.com/pinkpixel-dev/mem0-mcp/issues/1)). For debugging, the recommended workflow is: enable debug logging in the MCP host, test each parameter individually to isolate the failing scope, verify the resolved identifiers on the Mem0 dashboard, and consult `get_memory_capabilities` to confirm the active backend supports the operation you are attempting (Source: [PARAMETER_GUIDE.md:1-60]()). ## See Also - [Architecture and Tool Surface](./Architecture-and-Tool-Surface.md) - [Cloud, Supabase, and Local Backends](./Storage-Backends.md) - [Troubleshooting and Known Issues](./Troubleshooting.md) --- ## Troubleshooting and Common Failure Modes ### Related Pages Related topics: [Memory Tools and API Reference](#page-2), [Configuration, Parameters, and Storage Modes](#page-3)
Related Source Files The following source files were used to generate this page: - [OVERVIEW.md](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/OVERVIEW.md) - [CHANGELOG.md](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/CHANGELOG.md) - [PARAMETER_GUIDE.md](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/PARAMETER_GUIDE.md) - [src/types.ts](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/src/types.ts) - [update-server.md](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/update-server.md) - [ROADMAP.md](https://github.com/pinkpixel-dev/mem0-mcp/blob/main/ROADMAP.md)
# Troubleshooting and Common Failure Modes This page documents known failure modes, diagnostic patterns, and remediation steps for `@pinkpixel/mem0-mcp`, the Model Context Protocol (MCP) server that bridges LLM clients with the Mem0 memory platform. It synthesizes insights from the source code, the changelog, the parameter guide, and the issues reported by the community. The intended audience is a developer or operator who has the server installed and is trying to recover from a misconfiguration or unexpected behavior. ## 1. Server Connection and MCP Transport Issues The most visible failure is the client reporting that the MCP server is not connected. Reported as *"No connection found for server: Memory Management"*, this is a transport-level symptom that has several plausible root causes. - **stdio isolation**: MCP communicates over stdout, so any background library that writes to stdout will corrupt the JSON-RPC stream. The project addresses this with a `SafeLogger` class that intercepts console calls and routes them to stderr when they originate from project or `mem0ai` code. Source: [OVERVIEW.md](OVERVIEW.md) - **Client command mismatch**: When using `npx -y @pinkpixel/mem0-mcp`, the package must resolve to the published `@pinkpixel/mem0-mcp` namespace. The maintainers have also warned about malicious impersonator packages, so verify the package name, GitHub repo, and install command before debugging deeper. Source: [update-server.md](update-server.md) - **Tool permissions / allow-list**: Some MCP clients require the user to explicitly allow tools such as `add_memory` and `search_memory`. Without `alwaysAllow`, the client may refuse to forward calls. Source: [OVERVIEW.md](OVERVIEW.md) - **Resource cleanup on exit**: The `SafeLogger` is intended to clean up on process exit; abrupt termination can leak the wrapper state. Source: [OVERVIEW.md](OVERVIEW.md) Remediation starts with confirming that the server prints a valid handshake to stderr (not stdout) and that the client's `mcp.json` points at the right `command` and `args` pair. ## 2. Parameter Resolution Failures (userId, agentId, appId) A recurring class of community reports is that environment-variable defaults for `userId`, `orgId`, or `projectId` appear to be ignored. - **v0.3.9 — camelCase fix**: Earlier releases used snake_case (`org_id`, `project_id`), which the JavaScript client silently dropped. The fix migrated all calls to camelCase (`organizationId`, `projectId`) and restored the `ORG_ID` / `PROJECT_ID` fallback path. Source: [CHANGELOG.md](CHANGELOG.md) - **v0.5.0 — breaking parameter rename**: The maintainers discovered that `org_id` and `project_id` are auto-assigned by Mem0 and cannot be set by users. They were replaced with the actual Mem0 API parameters: `agentId` (LLM identifier), `userId` (user), `appId` (project scope), and `sessionId` (mapped to `run_id`). Environment fallbacks `DEFAULT_AGENT_ID` and `DEFAULT_APP_ID` were added. Source: [CHANGELOG.md](CHANGELOG.md) - **Precedence rule**: Tool-call parameters take precedence over environment variables. If the agent or the calling code does not pass `userId` explicitly, the env-var default should still be applied, but the community has reported that some clients strip or override these defaults. Source: [CHANGELOGOG.md](CHANGELOG.md) and [PARAMETER_GUIDE.md](PARAMETER_GUIDE.md) - **TypeScript contract**: The internal `AddInput` interface, the `ListInput` shape, and the `UpdateInput` / `SearchResult` interfaces all encode optional scope fields, confirming that scope is meant to be passed per-call rather than inferred. Source: [src/types.ts](src/types.ts) The recommended pattern is to pass the `userId` (and optionally `agentId` / `appId`) on every tool call so the request never relies solely on environment defaults. Recommended shapes are documented in [PARAMETER_GUIDE.md](PARAMETER_GUIDE.md) under "For Individual Users", "For Project Organization", and "For Organization Management". ## 3. Search Returning Empty Arrays Issue #4 ("`search_memory` Always Returns Empty Arrays") is the most commented issue in the project. Add operations succeed, but search returns `[]`. Issue #6 confirms the fix, with the important caveat that the fix is only effective when the `userId` is passed explicitly. - **Root cause**: A scoping mismatch between the `userId` used during `add_memory` and the one used during `search_memory`. Because the env-var fallback is not always honored, the search effectively queries a different (empty) bucket. Source: [CHANGELOG.md](CHANGELOG.md) - **Verification**: The user in issue #6 confirmed the search functionality works only after explicitly passing the `userID` parameter, even though the value matched the one in the config file. Source: community discussion referenced in the issue context - **Secondary risk**: The Mem0 V3 search endpoint expects entity IDs to be nested inside a `filters` object rather than passed as top-level request fields. The adapter layer is responsible for this translation, and mismatched filter shapes can also produce empty results. Source: [update-server.md](update-server.md) Diagnostic steps: (1) confirm the exact `userId` written in `mcp.json`, (2) re-issue the same call with `userId` as a tool parameter, and (3) inspect the Mem0 dashboard to see which bucket the memory was written to. ## 4. Storage-Mode and Capability Mismatches The server dynamically selects a backend (Cloud, Supabase, or Local) based on which environment variables are present. A common failure is invoking a tool that is not implemented for the active backend. | Storage Mode | Required env vars | Failure symptom if missing | Source | |---|---|---|---| | Cloud | `MEM0_API_KEY` | Client fails to initialize, `add_memory` returns auth error | [OVERVIEW.md](OVERVIEW.md) | | Supabase | `SUPABASE_URL`, `SUPABASE_KEY`, `OPENAI_API_KEY` | pgvector connection refused | [OVERVIEW.md](OVERVIEW.md) | | Local | `OPENAI_API_KEY` (for embeddings) | In-memory store works but memories are lost on restart | [OVERVIEW.md](OVERVIEW.md) | The roadmap also notes that `delete_memory` historically had no consistent API across cloud and local modes, requiring fallback strategies (direct API call for cloud, internal `vectorstore` access for local). Operations like `get_memory_history`, `list_memories`, or `get_memory_event` may not be available on every backend, and the maintainers plan to surface this through a `get_memory_capabilities` tool. Source: [ROADMAP.md](ROADMAP.md) and [update-server.md](update-server.md) ## 5. Security and Configuration Hygiene Community issue #2 requested that API keys not be hard-coded in `mcp.json`. Because `mcp.json` is frequently committed to source control or shared in chat, plain-text `MEM0_API_KEY` values are an exposure risk. Where the host platform supports it, prefer the host's secret-injection or `envFile` mechanism. Even if the host does not support that, at minimum the file should be added to `.gitignore`. Source: community discussion in the issue context ## 6. Versioning and Build Pitfalls Several older releases shipped with desynchronized version numbers between `package.json` and the source, and with known parameter bugs. When reproducing an old report, confirm the installed version: - v0.3.0 introduced `delete_memory` and cloud support. Source: [CHANGELOG.md](CHANGELOG.md) - v0.3.2 fixed the `threshold` parameter being passed as `null` to the cloud API. Source: [CHANGELOG.md](CHANGELOG.md) - v0.3.3 fixed the version-mismatch and clarified that `sessionId` is a tool parameter, not an environment variable. Source: [CHANGELOG.md](CHANGELOG.md) - v0.5.0 introduced the breaking parameter rename (`orgId`/`projectId` → `agentId`/`userId`/`appId`/`sessionId`). Source: [CHANGELOG.md](CHANGELOG.md) - v0.7.0 refactored the monolith into modular adapters (`src/backends/cloud.ts`, `supabase.ts`, `local.ts`) and bumped `mem0ai` to `3.0.10` and `@modelcontextprotocol/sdk` to `1.29.0`. Source: [CHANGELOG.md](CHANGELOG.md) If a user is pinned to an old version, upgrading is often the fastest fix for search, parameter, and SDK-mismatch errors. ## 7. Diagnostic Workflow The following decision tree summarizes the order in which to investigate a broken installation. ```mermaid flowchart TD A[Server appears broken] --> B{Client shows connection?} B -- No --> C[Check command, args, package name] C --> D[Inspect stderr for handshake / SafeLogger output] B -- Yes --> E{add_memory works?} E -- No --> F[Verify MEM0_API_KEY or Supabase env vars] F --> G[Match storage mode to installed backend] E -- Yes --> H{search_memory returns results?} H -- No --> I[Pass userId explicitly on every call] I --> J[Confirm scope via Mem0 dashboard] H -- Yes --> K[Healthy] ``` ## See Also - [MEM0-MCP Overview](MEM0-MCP-Overview) — high-level architecture and storage modes - [Parameter Guide](Parameter-Guide) — recommended `userId` / `agentId` / `appId` usage patterns - [Storage Backends](Storage-Backends) — Cloud, Supabase, and Local adapter details - [CHANGELOG](CHANGELOG) — full version history and migration notes --- --- ## Pitfall Log Project: pinkpixel-dev/mem0-mcp Summary: Found 9 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification. ## 1. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/pinkpixel-dev/mem0-mcp/issues/6 ## 2. Capability evidence risk - Capability evidence risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: README/documentation is current enough for a first validation pass. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: capability.assumptions | https://github.com/pinkpixel-dev/mem0-mcp ## 3. Maintenance risk - Maintenance risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/pinkpixel-dev/mem0-mcp ## 4. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: no_demo - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: downstream_validation.risk_items | https://github.com/pinkpixel-dev/mem0-mcp ## 5. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: no_demo - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: risks.scoring_risks | https://github.com/pinkpixel-dev/mem0-mcp ## 6. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/pinkpixel-dev/mem0-mcp/issues/2 ## 7. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/pinkpixel-dev/mem0-mcp/issues/4 ## 8. Maintenance risk - Maintenance risk requires verification - Severity: low - Evidence strength: source_linked - Finding: issue_or_pr_quality=unknown。 - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/pinkpixel-dev/mem0-mcp ## 9. Maintenance risk - Maintenance risk requires verification - Severity: low - Evidence strength: source_linked - Finding: release_recency=unknown。 - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/pinkpixel-dev/mem0-mcp