@yeyuan98/mem0-mcp

@yeyuan98/mem0-mcp

An MCP (Model Context Protocol) server that fronts a self-hosted Mem0 REST API. It exposes 10 memory tools over stdio so any MCP-compatible client (OpenCode, Claude Code, Cursor, …) can read and write memories that live in your own pgvector store.

• Single source of truth = your self-hosted server. Memories written via MCP and via the REST API/dashboard are the same data.
• Agent-friendly retrieval. Tool descriptions teach when and how to search; search_memories distills/dedupes results into a compact envelope; and a composite recall tool rewrites a query into keywords and fans out parallel searches so agents get just-right information in one call.
• Thin wrapper, no mem0ai dependency. The server is just HTTP calls with X-API-Key. No LLM, embedder, or vector-store dependencies are pulled into the MCP process.
• Stdio transport (launched by your MCP client).
• Built for the self-deployment optimized Mem0 fork (github.com/yeyuan98/mem0).

Links

• Package: https://www.npmjs.com/package/@yeyuan98/mem0-mcp
• Repo: https://github.com/yeyuan98/mem0

Install

npm install -g @yeyuan98/mem0-mcp
# or use directly via npx:
npx @yeyuan98/mem0-mcp

Requires Node.js 20+.

Configure

Connection

Variable	Required	Default	Description
MEM0_BASE_URL	no	http://localhost:8888	Base URL of your self-hosted Mem0 REST API, e.g. https://mem0api.example.com
MEM0_API_KEY	yes	—	The server's X-API-Key (starts with m0sk_). Use an admin key for full tool coverage (see below).

Scope defaults (optional)

Memories are scoped by user_id, agent_id, and run_id. You almost never need to pass them on a call — reads and writes auto-scope via this resolution ladder:

• Explicit per-call identity (e.g. agent_id="coder") — always honored.
• MEM0_DEFAULT_USER_ID (or _AGENT_ID / _RUN_ID) env var.
• Auto-discovery via list_entities:
  • A token in the query matches a known identity → scope to it (so "what is alice's hobby?" auto-scopes to alice).
  • Exactly one identity exists → scope to it (the common single-user case: zero-config).
  • Two or more identities with no match → returns a helpful error listing them (pass user_id/agent_id/run_id or set MEM0_DEFAULT_*).
  • Empty store (no identities yet) → a local default identity (MEM0_DEFAULT_USER_ID → OS user → default); the first write creates it.

Writes never auto-match names. There is no query token for add_memory — if the store has multiple identities and you omit an id, the write errors; otherwise it lands on the discovered/default identity. Pass user_id/agent_id/run_id explicitly to target a specific scope (e.g. agent_id="coder" for facts about an agent).

Variable	Required	Default	Description
MEM0_DEFAULT_USER_ID	no	—	Skip discovery and scope every call here. Disambiguates multi-identity stores.
MEM0_DEFAULT_AGENT_ID	no	—	Default agent_id.
MEM0_DEFAULT_RUN_ID	no	—	Default run_id.

Tenant-constrained scoping. The server confines every regular (non-admin) API key to its own user_id (forced on create/search/list; client-supplied user_id is ignored). Agent/run scoping still works within that tenant. Admins are unrestricted and can read/write any user_id/agent_id/run_id, including memories with no user_id. Use an admin key if you manage multiple tenants.

Destructive ops (delete_all_memories, delete_entities) do not auto-scope — they require an explicit identity (or MEM0_DEFAULT_USER_ID) so a wipe is never accidental. A regular key can only bulk-delete its own tenant's memories; delete_entities for anything other than your own user entity requires an admin key.

Connect your client

OpenCode

~/.config/opencode/opencode.json:

{
  "mcp": {
    "mem0": {
      "type": "local",
      "command": ["mem0-mcp"],
      "env": {
        "MEM0_BASE_URL": "https://mem0api.example.com",
        "MEM0_API_KEY": "m0sk_your_key",
        "MEM0_DEFAULT_USER_ID": "alice"
      }
    }
  }
}

Claude Code

claude mcp add mem0 --scope user --transport stdio \
  -e MEM0_BASE_URL=https://mem0api.example.com \
  -e MEM0_API_KEY=m0sk_your_key \
  -e MEM0_DEFAULT_USER_ID=alice \
  -- npx -y @yeyuan98/mem0-mcp

Cursor / generic .mcp.json

{
  "mcpServers": {
    "mem0": {
      "command": "npx",
      "args": ["-y", "@yeyuan98/mem0-mcp"],
      "env": {
        "MEM0_BASE_URL": "https://mem0api.example.com",
        "MEM0_API_KEY": "m0sk_your_key"
      }
    }
  }
}

Restart your client after adding the server.

Tools

Tool	Description	Admin key required?
add_memory	Store atomic memory(ies) from messages for a user/agent/run	no
search_memories	Semantic search, scoped; returns a distilled/deduped envelope	no
recall	Composite retrieval: rewrites query → fans out parallel searches → dedupes/ranks	no
get_memories	List/browse a scope without ranking (audit / page)	no-id list → yes
get_memory	Get one memory by ID (or a mem0:<12hex> citation)	no
update_memory	Update a memory's text/metadata (metadata is replaced, not merged)	no
delete_memory	Delete one memory by ID (accepts a mem0:<12hex> citation)	no
delete_all_memories	Bulk-delete all memories for a user/agent/run (regular keys are confined to their own tenant)	no
list_entities	List users/agents/runs with memory counts	no
delete_entities	Delete an entity and cascade-delete its memories (regular keys may delete only their own user entity)	yes

Operations that need an admin key return a clear 403-derived error if a non-admin key is supplied.

Retry safety. If add_memory times out or returns an error, do not blindly retry it — the write may already have been committed. Verify with search_memories (or recall) first; retrying creates duplicate memories.

Getting just-right information from memory

Which read tool to use?

Situation	Use
A request may depend on past work/preferences/decisions, and you're unsure which query to try	recall (default — fans out for you)
You know the exact query/category; want one ranked pass	search_memories
Auditing / paging everything in a scope (no ranking)	get_memories
Following up on a mem0:<12hex> citation from a previous result	get_memory

Query phrasing (applies to search_memories and the raw query you hand to recall): phrase queries as noun-phrase index terms — 3–6 content keywords (proper nouns, technical terms, numbers). Drop pronouns (I, you, my), question words (what, how, why), and filler. Don't paste the raw user message as a query. For multi-part or comparative questions, run several searches with different phrasings and combine — one search is rarely enough.

Category filtering. search_memories accepts a filters object supporting the server's operators: exact match ({"type":"decision"}), comparisons ({"confidence":{"gte":0.8}}), and logic ({"AND":[...]} / {"OR":[...]} / {"NOT":[...]}). Tag writes with a metadata.type (decision / task_learning / anti_pattern / convention / identity / preference) so these filters return useful results. recall's intent parameter adds one such category search automatically.

Scoping is automatic — see the "Scope defaults" ladder above. You only pass user_id to override the auto-resolved scope.

Result shape. search_memories and recall return a distilled envelope:

{
  "count": 2,
  "raw_count": 5,
  "query": "...",
  "categories_hit": ["decision", "preference"],
  "results": [{ "id": "mem0:a1b2c3d4e5f6", "memory": "...", "score": 0.9, "type": "decision" }],
  "note": "2 of 5 raw hit(s) after dedup. ..."
}

The mem0:<12hex> ids are citation handles, not raw UUIDs. get_memory, update_memory, and delete_memory resolve them back to the full UUID automatically (same-session from the result list; otherwise via a scoped re-fetch). To scope that re-fetch to a specific user/agent/run, pass user_id / agent_id / run_id to the id-based tool. If a citation is stale, re-run search_memories or recall to refresh it. Pass raw: true to search_memories if you need the unprocessed server response.

Programmatic use

import { createMcpServer, loadConfig } from "@yeyuan98/mem0-mcp";

const server = createMcpServer(loadConfig());
// attach to any MCP transport you like

Development

cd integrations/mem0-rest-mcp
pnpm install
pnpm run build        # tsup → dist/
pnpm run typecheck    # tsc --noEmit
pnpm test             # vitest run

Inspect the server interactively:

npx @modelcontextprotocol/inspector node dist/bin.js
# then set MEM0_BASE_URL / MEM0_API_KEY in the inspector env

License

Apache-2.0