Content
# mem0-mcp-server
MCP server exposing Mem0 v2 API for AI agents to store, retrieve, and search long-term memories using semantic search through the standardized MCP protocol.
## Overview
Mem0-MCP Server is a self-hosted MCP (Model Context Protocol) server that bridges AI agents with persistent memory storage. It enables intelligent context retention across conversations and sessions using Mem0's AsyncMemory API.
**Key Features:**
- MCP Protocol Integration - Exposes Mem0 functionality via MCP tools
- Semantic Memory Search - Similarity-based memory retrieval with vector search
- Multi-Tenant Isolation - User/Agent/Session scoped memory isolation
- Flexible Transport - stdio for local agents, SSE for remote connections
- Configuration Management - Pydantic-based validation with environment variable support
## Documentation
| Section | Description |
|---------|-------------|
| [API Reference](./doc/api/) | Complete API documentation for all modules and tools |
| [Pattern Guides](./doc/patterns/) | Design pattern documentation (Singleton, Repository, etc.) |
| [Usage Examples](./doc/examples/) | Getting started and advanced usage guides |
| [Deployment](./doc/deployment/docker-compose.md) | Docker Compose configuration and service details |
| [Architecture](./doc/architecture/) | System architecture and component interactions |
## Quick Start
### Installation
```bash
# Clone and install
git clone https://github.com/your-org/mem0-mcp-server.git
cd mem0-mcp-server
uv sync
# Set environment variables
export OPENAI_API_KEY="your-api-key"
```
### Configuration
Create `~/.config/mem0-mcp-server/settings.json`:
```json
{
"vector_store": {
"provider": "redis",
"config": {
"redis_url": "redis://localhost:6379"
}
},
"llm": {
"provider": "openai",
"config": {
"model": "gpt-4o"
}
},
"embedder": {
"provider": "openai",
"config": {
"model": "text-embedding-3-small"
}
}
}
```
### Running the Server
```bash
# SSE Transport (remote connections)
uv run python -m mcp_server.main
# stdio Transport (local AI agents)
export MCP_TRANSPORT=stdio
uv run python -m mcp_server.main
```
### OpenCode Configuration
In `~/config/opencode/opencode.json`
### OpenCode Configuration
In `~/config/opencode/opencode.json`
```json
"mcp": {
"mem0": {
"type": "remote",
"enabled": true,
"url": "http://localhost:8050/sse"
}
}
```
## MCP Tools
| Tool | Description |
|------|-------------|
| `add_memory` | Store information in long-term memory with semantic indexing |
| `search_memories` | Search memories using semantic similarity |
| `get_memory` | Retrieve specific memory by ID |
| `update_memory` | Update existing memory content |
| `delete_memory` | Remove memory from storage |
| `list_memories` | List memories with filtering and pagination |
## Usage Example
```python
# Add memory
result = await client.call_tool("add_memory", {
"messages": [{"role": "user", "content": "I prefer dark mode"}],
"user_id": "alice"
})
# Search memories
result = await client.call_tool("search_memories", {
"query": "theme preferences",
"filters": {"user_id": "alice"},
"limit": 5
})
```
## Architecture
```
AI Agent → FastMCP Server → MemoryManager → Mem0 AsyncMemory → Redis
│ │
├── SafeLogger (stdout/stderr) │
├── Transport (stdio/SSE) │
└── Config (Pydantic validation) │
```
**Components:**
- **COMP-1**: ConfigLoader - Configuration loading and validation
- **COMP-2**: FastMCP Server - MCP protocol server
- **COMP-3**: MemoryManager - Memory operations with multi-tenant isolation
- **COMP-4**: MCP Tools - Tool definitions
- **COMP-5**: SafeLogger - Output stream separation
## Configuration
### Parameter Precedence
Configuration values are resolved in order:
1. Tool parameters (direct)
2. Environment variables (with MCP_ prefix)
3. Config file values
4. Hardcoded defaults
### Environment Variables
| Variable | Default | Description |
|----------|---------|-------------|
| `OPENAI_API_KEY` | (required) | OpenAI API key for LLM |
| `MCP_TRANSPORT` | `sse` | Transport type (stdio, sse) |
| `MCP_HOST` | `0.0.0.0` | Server bind address |
| `MCP_PORT` | `8080` | Server bind port |
## Deployment
### Docker
```bash
# Using docker-compose
docker-compose up -d
# Using Makefile
make docker-up # Start services with docker compose
make docker-down # Stop services
make docker-logs # Show logs
```
**Services:**
| Service | Description |
|---------|-------------|
| `mem0-mcp` | MCP server exposing Mem0 API on port 8050 |
| `ollama-qwen3-embedding` | Ollama with `qwen3-embedding:8b` for vector embeddings (port 11434) |
| `ollama-qwen` | Ollama with `qwen2.5:7b` for chat completions (port 11435) |
See [Deployment → Docker](./doc/deployment/docker-compose.md) for detailed configuration.
### Kubernetes
```bash
# Using Helm chart
helm install mem0-mcp ./charts/mem0-mcp-server
```
## Development
| Command | Description |
|---------|-------------|
| `make install` | Install dependencies with uv |
| `make lint` | Lint code with ruff |
| `make lint-fix` | Auto-fix linting issues |
| `make typecheck` | Type check with pyright |
| `make test` | Run all tests |
| `make test-unit` | Run unit tests only |
| `make test-coverage` | Run tests with coverage report |
| `make build` | Build Docker image |
| `make run` | Run development server |
Run multiple commands: `make install && make lint && make typecheck && make test`
See [`Makefile`](./Makefile) for all available commands including Docker management (`docker-up`, `docker-down`, `docker-logs`, etc.).
## Project Structure
```
mem0-mcp/
├── src/mcp_server/
│ ├── __init__.py # FastMCP singleton
│ ├── lifespan.py # Resource lifecycle
│ ├── transport.py # Transport selection
│ ├── memory/
│ │ ├── manager.py # MemoryManager
│ │ └── lifespan.py # AsyncMemory lifecycle
│ ├── config/
│ │ ├── settings.py # Pydantic models
│ │ └── loader.py # Config file loading
│ ├── tools/
│ │ ├── add_memory.py
│ │ ├── search_memories.py
│ │ └── ...
│ └── utils/
│ └── safe_logger.py # Output separation
├── doc/
│ ├── api/ # API reference
│ ├── patterns/ # Pattern guides
│ ├── examples/ # Usage examples
│ └── architecture/ # Architecture docs
├── tests/
├── Makefile
├── Dockerfile
└── docker-compose.yml
```
## License
MIT License
