mem0-oss-mcp

Small MCP bridge for the self-hosted Mem0 OSS server from mem0ai/mem0/server.

It exposes the Mem0 MCP tool names expected by Codex and forwards them to a self-hosted Mem0 REST API.

Configuration

MEM0_OSS_BASE_URL=http://<mem0-host>:<mem0-port>
MEM0_OSS_API_KEY=m0sk_xxx

# Recommended: route memory operations through the control-plane sidecar.
MEM0_SIDECAR_BASE_URL=http://mem0-platform-sidecar:8765
MEM0_SIDECAR_PROJECT_ID=default
MEM0_SIDECAR_REQUIRED=true
# Required with the sidecar's secure default. This is the private operator
# credential, not a dashboard-created client key.
MEM0_SIDECAR_API_KEY=replace-with-private-operator-key
# Optional; defaults to a per-process ID and a five-minute heartbeat.
# MEM0_SIDECAR_INSTANCE_ID=mem0-oss-mcp-1
# MEM0_SIDECAR_HEARTBEAT_INTERVAL_SECONDS=300

MEM0_OSS_MCP_HOST=0.0.0.0
MEM0_OSS_MCP_PORT=8080
# disabled | static | hybrid | core_api_key
MEM0_OSS_MCP_AUTH_MODE=static
MEM0_OSS_MCP_CLIENT_AUTH_URL=http://mem0:8000/auth/me
MEM0_OSS_MCP_CLIENT_AUTH_TIMEOUT_SECONDS=5
MEM0_OSS_MCP_TOKEN=change-me

MEM0_OSS_DEFAULT_USER_ID=codex
MEM0_OSS_DEFAULT_APP_ID=default
MEM0_OSS_LIST_FETCH_LIMIT=5000
MEM0_OSS_BACKEND_LIST_RETRY_LIMIT=1000
# Optional: only set when backend top_k should differ from MEM0_OSS_LIST_FETCH_LIMIT.
# MEM0_OSS_BACKEND_LIST_FETCH_LIMIT=5000

MEM0_OSS_BASE_URL is the base URL of your Mem0 OSS REST server. The port is not assumed.

Clients configure only the public MCP URL and bearer token. MEM0_SIDECAR_* variables are private bridge/operator settings and must not be copied into Codex, OpenCode, Cursor, Claude, Hermes, or other client configuration.

MCP client authentication

static and hybrid require a non-empty MEM0_OSS_MCP_TOKEN. When neither a mode nor a legacy token is configured, startup fails closed. disabled must be selected explicitly and requires MEM0_OSS_MCP_HOST to be a loopback address; there is no non-loopback override. core_api_key validates the incoming bearer credential through Core /auth/me; the MCP process receives no static shared secret. Core unavailability returns a sanitized 503, while an invalid or revoked key returns 401.

Create one named Core admin API key per client in the dashboard's Client Keys page. Codex and OpenCode continue using MEM0_OSS_MCP_TOKEN as their local environment variable name, but its value becomes that client's m0sk_... key. The endpoint and MCP configuration remain unchanged.

When sidecar routing is enabled with a trusted MEM0_SIDECAR_API_KEY, Requests attributes new rows as Legacy shared MCP key for legacy_static or by the Core key label and prefix for core_api_key. Without that private bridge credential, sidecar rejects caller-supplied attribution instead of trusting it. Historical rows created before attribution remain Unknown (pre-attribution); they are never guessed or backfilled.

When MEM0_SIDECAR_BASE_URL is set, all memory operations plus entity list/delete use the sidecar so its durable project/app index stays current. MEM0_SIDECAR_PROJECT_ID supplies the project boundary, while each tool call's concrete app_id remains intact. If the sidecar setting is absent, the bridge keeps the legacy direct-OSS behavior. A sidecar request failure is returned to the caller and is never retried as a direct write, avoiding accidental double-writes.

With sidecar routing enabled, the bridge reports a bounded read/write routing capability heartbeat at startup, during health checks, and every five minutes. When MEM0_SIDECAR_REQUIRED=true, startup fails unless the private operator credential can call the protected heartbeat route. Server-side AUTO_SAFE consolidation requires a current heartbeat. Set MEM0_SIDECAR_REQUIRED=true in production so a missing sidecar URL fails at startup instead of silently selecting legacy direct mode.

get_memories fetches a larger backend candidate window before applying local app_id and metadata filters. MEM0_OSS_LIST_FETCH_LIMIT is the sidecar target window and, by default, the largest top_k sent to the backend. Set MEM0_OSS_BACKEND_LIST_FETCH_LIMIT only when the backend limit must differ. The default target is 5000. Older Mem0 OSS builds may reject list requests above 1000, so the sidecar retries with MEM0_OSS_BACKEND_LIST_RETRY_LIMIT and returns degraded_fetch_limit: true. When the fetched backend window is full, responses include truncated: true and complete: false; consolidation tools should not treat that listing as complete.

Codex should connect to this bridge, not directly to Mem0 OSS:

[mcp_servers.mem0]
url = "https://<bridge-host>/mcp"
bearer_token_env_var = "MEM0_OSS_MCP_TOKEN"

The bridge itself does not terminate TLS. Keep its 0.0.0.0:8080 listener on a private application network and publish remote MCP only through an HTTPS reverse proxy or gateway.

Related MCP server: Mem0 MCP Server

Codex plugin

This repository also publishes a Codex plugin marketplace at .agents/plugins/marketplace.json.

To use the checked-in plugin, provide the bridge URL and bearer token in the Codex process environment, then add the marketplace and install the plugin:

MEM0_OSS_MCP_URL=https://<bridge-host>/mcp
MEM0_OSS_MCP_TOKEN=change-me

codex plugin marketplace add SteinX/mem0-oss-mcp
codex plugin add mem0-oss@mem0-oss-mcp

For Codex Desktop, or for any host, port, domain, or token that should live outside the Codex process environment, generate a local plugin instance instead of editing files in this repository. Pass the bridge endpoint and token at install time; the installer writes the token to a local private dotenv file and the generated MCP config stores only the endpoint, token variable name, and dotenv path. The recommended shell flow reads the token from stdin so it does not appear in process listings.

printf '%s\n' "$MEM0_OSS_MCP_TOKEN" | \
  python3 plugins/mem0-oss/scripts/install_codex_plugin.py \
  --url https://<bridge-host>/mcp \
  --token-stdin \
  --install

The installer writes a local marketplace under ~/.mem0-oss-mcp/codex-plugins, patches only that generated copy, and then installs it through codex plugin add. It never writes token values into .mcp.json, hook commands, or repository files. By default, token values passed with --token-stdin or --token are stored in ~/.mem0-oss-mcp/codex-plugins/env/<plugin-name>.env with owner-only permissions. You can still pass --env-file /path/to/bridge.env to choose the dotenv location yourself.

For the full official Mem0 Codex plugin experience, including skills and lifecycle hooks, use the official Mem0 repository submodule as the upstream plugin source:

git submodule update --init --depth 1 third_party/mem0

printf '%s\n' "$MEM0_OSS_MCP_TOKEN" | \
  python3 plugins/mem0-oss/scripts/install_codex_plugin.py \
  --url https://<bridge-host>/mcp \
  --token-stdin \
  --token-env-var MEM0_OSS_MCP_TOKEN \
  --with-hooks \
  --install

--with-hooks copies third_party/mem0/integrations/mem0-plugin into the generated local marketplace, adds a small Mem0 OSS compatibility layer, and merges the official Codex hook entries into ~/.codex/hooks.json. Official hook and skill files stay in the submodule, not vendored into this repository. The generated full plugin also replaces the upstream /mem0:dream skill with an OSS manual-trigger variant that checks listing completeness and requires confirmation before applying changes. To upgrade them:

git -C third_party/mem0 fetch origin
git -C third_party/mem0 checkout origin/main
git add third_party/mem0

Then rerun install_codex_plugin.py so the generated local marketplace copy and hook paths are refreshed.

The default --mcp-transport auto chooses stdio when --env-file is present. Use --mcp-transport http only when you explicitly want direct HTTP MCP config with bearer_token_env_var; in that mode, Codex must receive the named token environment variable before a new thread starts.

Multiple instances can use different plugin IDs and token variables:

printf '%s\n' "$MEM0_HOME_MCP_TOKEN" | \
  python3 plugins/mem0-oss/scripts/install_codex_plugin.py \
  --name mem0-home \
  --display-name "Mem0 Home" \
  --url https://mem0-home.example.com:18443/mcp \
  --token-stdin \
  --token-env-var MEM0_HOME_MCP_TOKEN \
  --with-hooks \
  --install

OpenCode plugin

OpenCode's official Mem0 plugin is a native TypeScript plugin rather than an MCP-only config. To use that full plugin experience with Mem0 OSS, generate a local OpenCode plugin copy from the official Mem0 submodule and overlay the OSS compatibility client:

git submodule update --init --depth 1 third_party/mem0

printf '%s\n' "$MEM0_OSS_MCP_TOKEN" | \
  python3 plugins/mem0-oss/scripts/install_opencode_plugin.py \
  --url https://<bridge-host>/mcp \
  --token-stdin \
  --install

The installer writes a generated copy under ~/.mem0-oss-mcp/opencode-plugins/<name>, builds it with Bun, and installs a small loader in ~/.config/opencode/plugins/<name>.js. OpenCode loads local plugins from that directory at startup. The generated plugin keeps the upstream OpenCode hooks, native tools, and skills, while its memory client forwards operations to mem0-oss-mcp through JSON-RPC tools/call.

Generated plugins default to explicit capture: periodic message capture is off, and memories are written through the plugin's explicit memory tools. The upstream client-side Dream workflow is also off because durable consolidation belongs on the server. These defaults can be changed deliberately:

• --auto-capture-mode bounded samples every tenth message, with normalized duplicate suppression and per-session/per-day limits.

• --auto-capture-mode legacy restores the upstream every-third-message behavior.

• --client-dream re-enables the upstream client-side Dream workflow.

Existing MEM0_OSS_AUTO_CAPTURE_MODE and MEM0_DREAM environment values take precedence over installer defaults.

Token values passed with --token-stdin or --token are written to a local private dotenv file under ~/.mem0-oss-mcp/opencode-plugins/env/; they are not written to generated TypeScript source. Pass --env-file when you want to choose the dotenv path yourself.

To update the upstream OpenCode plugin files, update the third_party/mem0 submodule and rerun install_opencode_plugin.py.

Run

PYTHONPATH=src python3 -m mem0_oss_mcp.server

Docker:

docker build -t mem0-oss-mcp .
docker run --rm -p 8080:8080 --env-file .env mem0-oss-mcp

Tools

• add_memory

• search_memories

• get_memories

• get_memory

• update_memory

• delete_memory

• delete_all_memories

• delete_entities

• list_entities

• list_events

• get_event_status

list_events and get_event_status are implemented locally because the OSS REST server writes synchronously and does not expose the platform event API.