# mem0ai/mem0-mcp architecture

> Architecture diagram of the GitHub repository mem0ai/mem0-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mem0ai/mem0-mcp
- Repository: https://github.com/mem0ai/mem0-mcp

## Overview

##### Project type and purpose
- This is a cloud-native SSE-based MCP (Model Context Protocol) server written in Python that delegates persistent storage and semantic search of “coding preferences” to a Node-based mem0 microservice.
- Its purpose is to let Cursor agents connect via an SSE endpoint, then call three main tools (add, list, search) against a mem0 store.

##### File structure
- Top-level:
- .env, .python-version, pyproject.toml, uv.lock, main.py, README.md
- “node/mem0”: a self-contained Node project (package.json, tsconfig.json, src/index.ts, build config).
- Python side: main.py is the entrypoint for the SSE server; pyproject.toml and uv.lock manage dependencies and plugin installation.
- Node side: mem0 microservice under node/mem0 uses TypeScript and tsup for bundling, with pnpm workspace.
- No internal database—the Node service calls the external mem0.ai API using MEM0_API_KEY.

##### README for additional insights
- The server listens on 0.0.0.0:8080 by default and exposes /sse for Streaming SSE connections.
- Provides three RPC-style tools (add, get_all, search) over MCP.
- Emphasizes decoupling: Python server, Node service, and mem0.ai endpoint are independent processes.

a. Main components:
- Cursor client (Agent)
- Python MCP SSE server (main.py)
- mem0 microservice (Node/mem0)
- External mem0.ai API
- Environment/config (.env, MEM0_API_KEY)
b. Relationships & interactions:
1. Cursor Agent opens SSE connection to Python server /sse
2. Agent issues MCP tool calls (add/get_all/search)
3. Python server forwards calls to the Node mem0 microservice (e.g., via local HTTP or spawn)
4. Node service invokes External mem0.ai API (over HTTPS)
5. mem0.ai returns results to Node service, then to Python server, then streamed back to Agent
c. Architectural patterns & principles:
- Microservices boundary between Python and Node layers
- SSE for reactive, streaming context updates
- External dependency injection via .env
- Clear separation of control (Python) vs. storage/search (Node + mem0.ai)
d. Key technologies & libraries:
- Python asyncio / FastAPI or custom SSE server (main.py)
- UV toolchain (uv venv, uv run) for Python
- pnpm, TypeScript, tsup for Node build
- mem0.ai SDK calls in Node
- Model Context Protocol over SSE

##### Final recommendations
- Keep it detailed enough to show the flow of a single “add_coding_preference” request end-to-end.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Client Layer"
        Agent["Cursor Agent"]:::client
    end

    subgraph "Server Layer"
        Env[".env"]:::config
        PythonServer["Python MCP SSE Server (main.py)"]:::service
        PyProj["pyproject.toml"]:::config
        UVLock["uv.lock"]:::config
        DocPy["README.md"]:::config
    end

    subgraph "Node Service Layer"
        Env -.-> NodeRoot["Node mem0 Service"]:::service
        NodeDocs["node/mem0/README.md"]:::config
        NodeRoot --> Index["src/index.ts"]:::code
        NodeRoot --> Tsup["tsup.config.ts"]:::config
        NodeRoot --> TSConfig["tsconfig.json"]:::config
        NodeRoot --> Package["package.json"]:::config
    end

    subgraph "External Services"
        Mem0API["mem0.ai API"]:::external
    end

    Agent -->|"SSE /sse (MCP)"| PythonServer
    Env --> PythonServer
    PyProj --> PythonServer
    UVLock --> PythonServer
    PythonServer -->|"HTTP RPC (add,get_all,search)"| NodeRoot
    NodeRoot -->|"HTTPS (mem0.ai SDK)"| Mem0API
    Mem0API -->|"Response JSON"| NodeRoot
    NodeRoot -->|"RPC Response"| PythonServer
    PythonServer -->|"SSE stream"| Agent

    click PythonServer "https://github.com/mem0ai/mem0-mcp/blob/main/main.py"
    click PyProj "https://github.com/mem0ai/mem0-mcp/blob/main/pyproject.toml"
    click UVLock "https://github.com/mem0ai/mem0-mcp/blob/main/uv.lock"
    click Env "https://github.com/mem0ai/mem0-mcp/blob/main/.env"
    click NodeRoot "https://github.com/mem0ai/mem0-mcp/tree/main/node/mem0/"
    click Index "https://github.com/mem0ai/mem0-mcp/blob/main/node/mem0/src/index.ts"
    click Tsup "https://github.com/mem0ai/mem0-mcp/blob/main/node/mem0/tsup.config.ts"
    click TSConfig "https://github.com/mem0ai/mem0-mcp/blob/main/node/mem0/tsconfig.json"
    click Package "https://github.com/mem0ai/mem0-mcp/blob/main/node/mem0/package.json"
    click DocPy "https://github.com/mem0ai/mem0-mcp/blob/main/README.md"
    click NodeDocs "https://github.com/mem0ai/mem0-mcp/blob/main/node/mem0/README.md"

    classDef client fill:#a8f0c6,stroke:#333,stroke-width:1px
    classDef service fill:#a0c4ff,stroke:#333,stroke-width:1px
    classDef external fill:#ffd6a5,stroke:#333,stroke-width:1px
    classDef config fill:#f0e68c,stroke:#333,stroke-width:1px
    classDef code fill:#d0f0fd,stroke:#333,stroke-width:1px
```
