memo-mcp

memo-mcp is a guarded Streamable HTTP MCP gateway for a private, self-hosted Mem0 REST API. It exposes a small, non-destructive memory-tool surface while keeping Mem0, PostgreSQL and internal API credentials off the public network.

It is designed as a reference implementation for one trusted memory scope. Before allowing multiple people to use it, integrate a server-side policy adapter that derives the memory scope from authenticated membership. Never let a browser or MCP client choose MEMORY_SCOPE.

Security model

• Mem0 remains private; expose only this gateway through a reverse proxy.

• Non-browser clients use a distinct, revocable bearer token.

• Browser clients can use OAuth/OIDC token introspection with exact issuer, audience, immutable subject and scope checks.

• memo_remember_fact requires mem0.write for OAuth clients.

• The gateway deliberately provides no memory-deletion tool. Perform deletion through a separate, private administrative workflow with explicit approval.

• The gateway rejects common credential and private-key formats before they can be written to memory. This is a safety net, not a replacement for operator policy.

• A caller must never select its own memory scope. In multi-user deployments, a trusted application must derive that scope from server-side membership.

Related MCP server: memex

Quick start

1. Copy .env.example to .env and replace every placeholder with your own private values. Do not commit .env.

2. Create a private Docker network and start the service with docker compose -f compose.example.yml up -d --build.

3. Route only the gateway through HTTPS. Do not publish Mem0, PostgreSQL or any populated environment file.

4. Verify that the protected-resource metadata returns 200 when OAuth is enabled and that an anonymous /mcp request returns 401.

Tools

• memo_search_memory

• memo_remember_fact

Configuration

See .env.example. PUBLIC_MCP_URL, MCP_ALLOWED_HOSTS, and MCP_ALLOWED_ORIGINS must describe your own HTTPS endpoint. The gateway calls the underlying Mem0 API using X-API-Key.

MCP_ALLOWED_HOSTS is mandatory. The container build context excludes .env, Git metadata, and local Python artifacts so they cannot be copied to an image by accident.

Development

python -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
python -m unittest discover -s tests -v

This project uses the official Python MCP SDK.