MCP-Persistence-Layer: Agent Knowledge Reservoir

This repository presents a reference implementation of a Model Context Protocol (MCP) server infrastructure, leveraging the Mem0 backend to furnish AI entities with durable, queryable memory functionality.

Utilize this codebase as a structural blueprint for fabricating your bespoke MCP servers, or present it as an exemplary standard to an AI coding associate for guidance on architectural patterns and code fidelity.

Architectural Summary

This project illustrates the methodology for constructing an MCP endpoint capable of persisting, retrieving, and semantically cross-referencing agent memories using the Mem0 engine. It serves as a tangible template for rapid deployment of custom MCP backends.

The implementation strictly adheres to the architectural guidelines promulgated by Anthropic for MCP server development, ensuring interoperability with any conforming client.

Core Capabilities

The persistence service exposes three fundamental operational modalities for memory administration:

1. save_memory: Commits arbitrary data into the long-term repository, automatically tagged with semantic indexes.
2. get_all_memories: Fetches the entirety of the accumulated memory corpus for exhaustive contextual review.
3. search_memories: Executes intelligent vector search against stored data to locate contextually pertinent records.

System Prerequisites

To successfully deploy this component, the following dependencies are required:

• Python environment version 3.12 or newer
• A PostgreSQL database instance, ideally managed via Supabase, to host vector embeddings.
• Valid API credentials for your chosen Large Language Model (LLM) vendor (e.g., OpenAI, OpenRouter, or Ollama).
• Docker utility if packaging the MCP service into a containerized deployment (highly recommended).

Deployment Procedures

Utilizing uv (Python Package Manager)

1. Install uv if not already present in your environment: bash pip install uv

2. Clone the repository source code: bash git clone https://github.com/coleam00/mcp-mem0.git cd mcp-mem0

3. Install required libraries into an editable environment: bash uv pip install -e .

4. Duplicate the environment example file to create the active configuration file: bash cp .env.example .env

5. Populate the configuration parameters within the newly created .env file (refer to the Configuration section).

Containerized Deployment with Docker (Preferred Method)

1. Construct the distribution image: bash docker build -t mcp/mem0 --build-arg PORT=8050 .

2. Prepare and configure the .env file containing necessary environment secrets.

Configuration Parameters

The operational settings for the server are governed by the following environment variables specified in the .env file:

Variable Name	Functionality Description	Illustrative Value
TRANSPORT	Defines the communication modality (either sse for streaming or stdio for direct I/O)	sse
HOST	Network interface binding address for SSE transport	0.0.0.0
PORT	Network socket port number when utilizing SSE	8050
LLM_PROVIDER	Identifier for the external LLM service being employed	openai
LLM_BASE_URL	URI endpoint for the LLM service invocation	https://api.openai.com/v1
LLM_API_KEY	Secret credential required for authenticating with the LLM service	sk-...
LLM_CHOICE	The specific model identifier selected for general language tasks	gpt-4o-mini
EMBEDDING_MODEL_CHOICE	The model designated for generating semantic vector representations	text-embedding-3-small
DATABASE_URL	The connection string furnishing access to the PostgreSQL data store	postgresql://user:pass@host:port/db

Executing the Server Instance

Local Execution (Using uv)

Server-Sent Events (SSE) Mode

bash

Ensure TRANSPORT=sse is set in .env, then execute:

uv run src/main.py

The server initializes, exposing itself as a network resource ready for connection via the specified configuration schema.

Standard Input/Output (Stdio) Mode

When employing stdio, the consuming MCP client application is responsible for initiating and managing the server process directly, thus requiring no explicit execution command here.

Containerized Execution (Using Docker)

Server-Sent Events (SSE) Mode

bash docker run --env-file .env -p:8050:8050 mcp/mem0

The container starts the service, creating a network endpoint accessible externally, which clients can then target using the subsequent configuration snippets.

Standard Input/Output (Stdio) Mode

In the stdio transport scenario, the client environment manages the container lifecycle, so no separate execution command is necessary at this stage.

Interfacing with MCP Clients

SSE Transport Connection Setup

When the server is operational using SSE transport, integrate it with your client application using the following configuration structure:

{ "mcpServers": { "mem0": { "transport": "sse", "url": "http://localhost:8050/sse" } } }

Windsurf Client Note: For Windsurf users, substitute the url field with serverUrl in the configuration:

{ "mcpServers": { "mem0": { "transport": "sse", "serverUrl": "http://localhost:8050/sse" } } }

n8n Client Note: If operating n8n within its standard Docker environment, localhost resolves to the container itself. You must reference the host machine via host.docker.internal to reach the externally mapped port:

The resulting full endpoint path becomes: http://host.docker.internal:8050/sse

Verify that the configured port matches the port specified during server startup (default is 8050).

Python Client with Stdio Configuration

To enable connectivity from clients like Claude Desktop, Windsurf, or any other MCP-enabled system via Python's stdio channel, utilize this structure in the client's MCP configuration block:

{ "mcpServers": { "mem0": { "command": "your/path/to/mcp-mem0/.venv/Scripts/python.exe", "args": ["your/path/to/mcp-mem0/src/main.py"], "env": { "TRANSPORT": "stdio", "LLM_PROVIDER": "openai", "LLM_BASE_URL": "https://api.openai.com/v1", "LLM_API_KEY": "YOUR-API-KEY", "LLM_CHOICE": "gpt-4o-mini", "EMBEDDING_MODEL_CHOICE": "text-embedding-3-small", "DATABASE_URL": "YOUR-DATABASE-URL" } } } }

Dockerized Client with Stdio Configuration

For scenarios where the MCP client invokes the server via a Docker container using stdio pipes:

{ "mcpServers": { "mem0": { "command": "docker", "args": ["run", "--rm", "-i", "-e", "TRANSPORT", "-e", "LLM_PROVIDER", "-e", "LLM_BASE_URL", "-e", "LLM_API_KEY", "-e", "LLM_CHOICE", "-e", "EMBEDDING_MODEL_CHOICE", "-e", "DATABASE_URL", "mcp/mem0"], "env": { "TRANSPORT": "stdio", "LLM_PROVIDER": "openai", "LLM_BASE_URL": "https://api.openai.com/v1", "LLM_API_KEY": "YOUR-API-KEY", "LLM_CHOICE": "gpt-4o-mini", "EMBEDDING_MODEL_CHOICE": "text-embedding-3-small", "DATABASE_URL": "YOUR-DATABASE-URL" } } } }

Guide to Custom Server Development

This boilerplate serves as an excellent starting point for constructing more sophisticated MCP service modules. To proceed with customization:

1. Extend functionality by adding new capabilities via methods decorated with @mcp.tool().
2. Implement necessary setup/teardown logic in the lifespan handler to initialize custom clients or database handlers via @mcp.lifespan().
3. Modify source files within utils.py to implement any required auxiliary utility functions for your server logic.
4. Integrate custom knowledge artifacts using @mcp.resource() and predefined instructional text using @mcp.prompt() decorators.