MCP-Mem0

This project serves as a template for building custom MCP servers. To extend it:

1. Add Tools: Create new methods and decorate them with @mcp.tool().
2. Add Resources/Prompts: Use @mcp.resource() and @mcp.prompt() to expose additional data or interaction patterns.
3. Manage Lifespan: Create a custom lifespan function to manage dependencies like database connections or API clients.
4. Helpers: Use utils.py for shared helper functions.

Depending on your chosen transport protocol, use the following commands:

SSE Transport

Requires TRANSPORT=sse in your .env file.

Using uv:

uv run src/main.py

Using Docker:

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

Stdio Transport

With stdio, the MCP client itself manages the server lifecycle, so no manual run command is required. The client will spin up the server process directly.

# SSE with uv
uv run src/main.py

# SSE with Docker
docker run --env-file .env -p:8050:8050 mcp/mem0

If the server is running with sse transport, use the following configurations for your client:

Standard MCP Client:

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

Windsurf Users: Use serverUrl instead of url:

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

n8n Users: Use host.docker.internal to reach the host machine from within the n8n container: http://host.docker.internal:8050/sse

To install the project locally using uv:

1. Install uv via pip: pip install uv.
2. Clone the repository: git clone https://github.com/coleam00/mcp-mem0.git && cd mcp-mem0.
3. Install dependencies: uv pip install -e ..
4. Initialize your environment file: cp .env.example .env.
5. Configure the required environment variables in .env.

To run the MCP server as a container:

1. Build the Docker image (defaulting to port 8050): docker build -t mcp/mem0 --build-arg PORT=8050 ..
2. Configure your environment variables in a .env file based on .env.example before running.

The following environment variables must be configured in your .env file or passed to the server:

The MCP-Mem0 server exposes three primary tools for AI agents to interact with long-term memory:

1. save_memory: Stores information in long-term memory with semantic indexing.
2. get_all_memories: Retrieves all stored memories to provide comprehensive context to the agent.
3. search_memories: Performs a semantic search to find specific relevant memories.

The get_all_memories tool retrieves all stored memories for the default user. It returns a JSON-formatted list of memory contents. Results are paginated (defaulting to 50 items per page). Use this tool when you need the complete context of all previously stored memories.

# Example tool call via MCP client
memories = await get_all_memories()
print(memories)

The search_memories tool performs a semantic search to find relevant information based on a natural language query. Results are ranked by relevance.

Arguments:

• query (str): The search query string.
• limit (int, default: 3): The maximum number of results to return.

Always search memories before making decisions to ensure you leverage existing knowledge.

# Example tool call via MCP client
results = await search_memories(query="What is the user's favorite color?", limit=5)
print(results)

The save_memory tool allows you to store information into long-term memory. The content is processed and indexed for later retrieval via semantic search. It uses a default user ID of user.

# Example tool call via MCP client
await save_memory(text="The user prefers dark mode in all applications.")

The server's communication protocol is determined by the TRANSPORT environment variable:

• If TRANSPORT=sse, the server runs using SSE (Server-Sent Events) transport.
• For any other value (defaulting to stdio), the server runs using stdio transport.

# To run with SSE transport
export TRANSPORT=sse
python src/main.py

# To run with stdio transport (default)
export TRANSPORT=stdio
python src/main.py