mem0-mcp-server

mem0-mcp-server

Servidor MCP que expõe a API Mem0 v2 para agentes de IA armazenarem, recuperarem e pesquisarem memórias de longo prazo usando busca semântica através do protocolo MCP padronizado.

Visão Geral

O Mem0-MCP Server é um servidor MCP (Model Context Protocol) auto-hospedado que conecta agentes de IA ao armazenamento persistente de memória. Ele permite retenção inteligente de contexto entre conversas e sessões usando a API AsyncMemory do Mem0.

Principais Recursos:

• Integração com Protocolo MCP - Expõe funcionalidades do Mem0 via ferramentas MCP
• Busca Semântica de Memória - Recuperação de memória baseada em similaridade com busca vetorial
• Isolamento Multi-Tenant - Isolamento de memória com escopo por Usuário/Agente/Sessão
• Transporte Flexível - stdio para agentes locais, SSE para conexões remotas
• Gerenciamento de Configuração - Validação baseada em Pydantic com suporte a variáveis de ambiente

Documentação

Seção	Descrição
Referência da API	Documentação completa da API para todos os módulos e ferramentas
Guias de Padrões	Documentação de padrões de design (Singleton, Repository, etc.)
Exemplos de Uso	Guias de introdução e uso avançado
Implantação	Configuração do Docker Compose e detalhes dos serviços
Arquitetura	Arquitetura do sistema e interações entre componentes

Início Rápido

Instalação

# 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"

Configuração

Crie ~/.config/mem0-mcp-server/settings.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"
    }
  }
}

Executando o Servidor

# 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

Configuração do OpenCode

Em ~/config/opencode/opencode.json

Configuração do OpenCode

Em ~/config/opencode/opencode.json

	"mcp": {
		"mem0": {
			"type": "remote",
			"enabled": true,
			"url": "http://localhost:8050/sse"
		}
    }

Ferramentas MCP

Ferramenta	Descrição
add_memory	Armazena informações na memória de longo prazo com indexação semântica
search_memories	Busca memórias usando similaridade semântica
get_memory	Recupera memória específica por ID
update_memory	Atualiza conteúdo de memória existente
delete_memory	Remove memória do armazenamento
list_memories	Lista memórias com filtragem e paginação

Exemplo de Uso

# 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
})

Arquitetura

AI Agent → FastMCP Server → MemoryManager → Mem0 AsyncMemory → Redis
              │                                  │
              ├── SafeLogger (stdout/stderr)     │
              ├── Transport (stdio/SSE)          │
              └── Config (Pydantic validation)   │

Componentes:

• COMP-1: ConfigLoader - Carregamento e validação de configuração
• COMP-2: FastMCP Server - Servidor de protocolo MCP
• COMP-3: MemoryManager - Operações de memória com isolamento multi-tenant
• COMP-4: MCP Tools - Definições de ferramentas
• COMP-5: SafeLogger - Separação de fluxos de saída

Configuração

Precedência de Parâmetros

Os valores de configuração são resolvidos na seguinte ordem:

1. Parâmetros de ferramenta (diretos)
2. Variáveis de ambiente (com prefixo MCP_)
3. Valores do arquivo de configuração
4. Padrões codificados (hardcoded)

Variáveis de Ambiente

Variável	Padrão	Descrição
OPENAI_API_KEY	(obrigatório)	Chave da API OpenAI para LLM
MCP_TRANSPORT	sse	Tipo de transporte (stdio, sse)
MCP_HOST	0.0.0.0	Endereço de bind do servidor
MCP_PORT	8080	Porta de bind do servidor

Implantação

Docker

# 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

Serviços:

Serviço	Descrição
mem0-mcp	Servidor MCP expondo a API Mem0 na porta 8050
ollama-qwen3-embedding	Ollama com qwen3-embedding:8b para embeddings vetoriais (porta 11434)
ollama-qwen	Ollama com qwen2.5:7b para completions de chat (porta 11435)

Consulte Implantação → Docker para configuração detalhada.

Kubernetes

# Using Helm chart
helm install mem0-mcp ./charts/mem0-mcp-server

Desenvolvimento

Comando	Descrição
make install	Instala dependências com uv
make lint	Verifica o código com ruff
make lint-fix	Corrige automaticamente problemas de lint
make typecheck	Verificação de tipos com pyright
make test	Executa todos os testes
make test-unit	Executa apenas testes unitários
make test-coverage	Executa testes com relatório de cobertura
make build	Constrói imagem Docker
make run	Executa servidor de desenvolvimento

Execute múltiplos comandos: make install && make lint && make typecheck && make test

Consulte Makefile para todos os comandos disponíveis, incluindo gerenciamento do Docker (docker-up, docker-down, docker-logs, etc.).

Estrutura do Projeto

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

Licença

MIT License