Mem0 MCP

Integra-se ao Mem0.ai para fornecer capacidades de memória persistente para LLMs, suportando armazenamento em nuvem, Supabase e local.

GitHub

Experimente este MCPPatrocinado

Documentação

Servidor MCP @pinkpixel/mem0-mcp ✨

Um servidor Model Context Protocol (MCP) que se integra ao Mem0.ai para fornecer capacidades de memória persistente para LLMs. Ele permite que agentes de IA armazenem e recuperem informações entre sessões.

Este servidor utiliza o SDK Node.js mem0ai para sua funcionalidade principal.

Recursos 🧠

Ferramentas Modernizadas e Avançadas (v0.8.0)

add_memory: Armazena uma memória a partir de conteúdo de texto ou matrizes de mensagens estruturadas.
- Entradas: content (string) ou messages (matriz de objetos de papel/conteúdo), userId (string), runId / sessionId (string), agentId (string), appId (string), metadata (objeto), infer (booleano), customInstructions (string), waitForCompletion (booleano, padrão: true), timeoutMs (número, padrão: 15000)
- Comportamento: As adições do Cloud V3 são assíncronas. Por padrão, esta ferramenta consulta a fila em segundo plano até a conclusão. Passe waitForCompletion: false para obter o eventId imediatamente.
search_memories: Pesquisa memórias usando filtros híbridos semânticos e BM25.
- Entradas: query (string), userId (string), runId / sessionId (string), agentId (string), appId (string), filters (objeto), threshold (número), topK (número), rerank (booleano), referenceDate (string)
- Comportamento: Aninha automaticamente variáveis de escopo dentro do bloco filters V3 para evitar erros de validação da API.
search_memory: Alias compatível com versões anteriores para search_memories.
list_memories: Listagem paginada de registros de memória com escopo por identificadores.
- Entradas: userId (string), runId / sessionId (string), agentId (string), appId (string), filters (objeto), page (número), pageSize (número)
get_memory: Recupera um único registro de memória pelo seu ID.
- Entradas: memoryId (string)
update_memory: Modifica o texto ou os metadados de uma memória existente.
- Entradas: memoryId (string), text (string), metadata (objeto)
delete_memory: Exclui um registro de memória específico por ID.
- Entradas: memoryId (string)
get_memory_history: Recupera a trilha de auditoria das revisões de memória (somente nuvem).
- Entradas: memoryId (string)
get_memory_capabilities: Expõe a matriz de recursos e os sinalizadores de suporte do modo de armazenamento de backend ativo.
- Entradas: Nenhuma
batch_update_memories: Executa atualizações em massa do conteúdo de texto para múltiplas memórias (somente nuvem).
- Entradas: updates (matriz de objetos { memoryId: string, text: string })
batch_delete_memories: Executa exclusões em massa de múltiplas memórias.
- Entradas: memoryIds (matriz de strings), confirm (booleano, deve ser true para executar)
rate_memory: Envia avaliação de feedback de qualidade para um registro de memória (somente nuvem).
- Entradas: memoryId (string), feedback (string: positive, negative, very_negative), reason (string, opcional)
get_memory_event: Recupera manualmente os detalhes de um trabalho de evento em segundo plano específico (somente nuvem).
- Entradas: eventId (string)
list_memory_events: Lista os logs de histórico de eventos de processamento de memória em segundo plano (somente nuvem).
- Entradas: page (número), pageSize (número)
create_memory_export: Inicia um trabalho de consulta de exportação de memória assíncrono (somente nuvem).
- Entradas: schema (objeto), filters (objeto, opcional), exportInstructions (string, opcional)
get_memory_export: Recupera o status e os metadados de download de um trabalho de exportação de memória (somente nuvem).
- Entradas: exportId (string)

Pré-requisitos 🔑

Este servidor suporta três modos de armazenamento:

Modo de Armazenamento em Nuvem ☁️ (Recomendado para produção)
- Requer uma chave de API Mem0 (fornecida como variável de ambiente MEM0_API_KEY)
- As memórias são armazenadas persistentemente nos servidores em nuvem da Mem0
- Nenhum banco de dados local necessário
- Suporte completo de recursos com filtragem e pesquisa avançadas
Modo de Armazenamento Supabase 🗄️ (Recomendado para auto-hospedagem)
- Requer credenciais Supabase (variáveis de ambiente SUPABASE_URL e SUPABASE_KEY)
- Requer chave de API OpenAI (variável de ambiente OPENAI_API_KEY) para embeddings
- As memórias são armazenadas persistentemente no seu banco de dados Supabase
- Camada gratuita disponível, opção auto-hospedável
- Requer configuração inicial do banco de dados (migrações SQL fornecidas abaixo)
Modo de Armazenamento Local 💾 (Somente desenvolvimento/teste)
- Requer uma chave de API OpenAI (fornecida como variável de ambiente OPENAI_API_KEY)
- As memórias são armazenadas em um banco de dados vetorial em memória (não persistente por padrão)
- Os dados são perdidos quando o servidor reinicia, a menos que configurado para armazenamento persistente

Instalação e Configuração ⚙️

Você pode executar este servidor de três maneiras principais:

Instalação via Smithery

Para instalar o Mem0 Memory Server para Claude Desktop automaticamente via Smithery:

npx -y @smithery/cli install @pinkpixel-dev/mem0-mcp-server --client claude

1. Instalação Global (Recomendado para uso frequente)

Instale o pacote globalmente e use o comando mem0-mcp:

npm install -g @pinkpixel/mem0-mcp

Após a instalação global, você pode executar o servidor diretamente:

mem0-mcp

Configure seu cliente MCP para usar o comando global:

Configuração de Armazenamento em Nuvem (Instalação Global)

{
  "mcpServers": {
    "mem0-mcp": {
      "command": "mem0-mcp",
      "args": [],
      "env": {
        "MEM0_API_KEY": "YOUR_MEM0_API_KEY_HERE",
        "DEFAULT_USER_ID": "user123",
        "DEFAULT_AGENT_ID": "your-agent-id",
        "DEFAULT_APP_ID": "your-app-id"
      }
    }
  }
}

Configuração de Armazenamento Supabase (Instalação Global)

{
  "mcpServers": {
    "mem0-mcp": {
      "command": "mem0-mcp",
      "args": [],
      "env": {
        "SUPABASE_URL": "YOUR_SUPABASE_PROJECT_URL",
        "SUPABASE_KEY": "YOUR_SUPABASE_ANON_KEY",
        "OPENAI_API_KEY": "YOUR_OPENAI_API_KEY_HERE",
        "DEFAULT_USER_ID": "user123",
        "DEFAULT_AGENT_ID": "your-agent-id",
        "DEFAULT_APP_ID": "your-app-id"
      }
    }
  }
}

Configuração de Armazenamento Local (Instalação Global)

{
  "mcpServers": {
    "mem0-mcp": {
      "command": "mem0-mcp",
      "args": [],
      "env": {
        "OPENAI_API_KEY": "YOUR_OPENAI_API_KEY_HERE",
        "DEFAULT_USER_ID": "user123"
      }
    }
  }
}

2. Usando `npx` (Recomendado para uso ocasional)

Configure seu cliente MCP (ex.: Claude Desktop, Cursor, Cline, Roo Code, etc.) para executar o servidor usando npx:

Configuração de Armazenamento em Nuvem (npx)

{
  "mcpServers": {
    "mem0-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@pinkpixel/mem0-mcp"
      ],
      "env": {
        "MEM0_API_KEY": "YOUR_MEM0_API_KEY_HERE",
        "DEFAULT_USER_ID": "user123",
        "DEFAULT_AGENT_ID": "your-agent-id",
        "DEFAULT_APP_ID": "your-app-id"
      }
    }
  }
}

Configuração de Armazenamento Supabase (npx)

{
  "mcpServers": {
    "mem0-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@pinkpixel/mem0-mcp"
      ],
      "env": {
        "SUPABASE_URL": "YOUR_SUPABASE_PROJECT_URL",
        "SUPABASE_KEY": "YOUR_SUPABASE_ANON_KEY",
        "OPENAI_API_KEY": "YOUR_OPENAI_API_KEY_HERE",
        "DEFAULT_USER_ID": "user123",
        "DEFAULT_AGENT_ID": "your-agent-id",
        "DEFAULT_APP_ID": "your-app-id"
      }
    }
  }
}

Configuração de Armazenamento Local (npx)

{
  "mcpServers": {
    "mem0-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@pinkpixel/mem0-mcp"
      ],
      "env": {
        "OPENAI_API_KEY": "YOUR_OPENAI_API_KEY_HERE",
        "DEFAULT_USER_ID": "user123"
      }
    }
  }
}

3. Executando a partir do Repositório Clonado

Nota: Este método requer que você clone o repositório git primeiro.

Clone o repositório, instale as dependências e compile o servidor:

git clone https://github.com/pinkpixel-dev/mem0-mcp
cd mem0-mcp
npm install
npm run build

Em seguida, configure seu cliente MCP para executar o script compilado diretamente usando node:

Configuração de Armazenamento em Nuvem (Repositório Clonado)

{
  "mcpServers": {
    "mem0-mcp": {
      "command": "node",
      "args": [
        "/absolute/path/to/mem0-mcp/build/index.js"
      ],
      "env": {
        "MEM0_API_KEY": "YOUR_MEM0_API_KEY_HERE",
        "DEFAULT_USER_ID": "user123",
        "DEFAULT_AGENT_ID": "your-agent-id",
        "DEFAULT_APP_ID": "your-app-id"
      }
    }
  }
}

Configuração de Armazenamento Supabase (Repositório Clonado)

{
  "mcpServers": {
    "mem0-mcp": {
      "command": "node",
      "args": [
        "/absolute/path/to/mem0-mcp/build/index.js"
      ],
      "env": {
        "SUPABASE_URL": "YOUR_SUPABASE_PROJECT_URL",
        "SUPABASE_KEY": "YOUR_SUPABASE_ANON_KEY",
        "OPENAI_API_KEY": "YOUR_OPENAI_API_KEY_HERE",
        "DEFAULT_USER_ID": "user123",
        "DEFAULT_AGENT_ID": "your-agent-id",
        "DEFAULT_APP_ID": "your-app-id"
      }
    }
  }
}

Configuração de Armazenamento Local (Repositório Clonado)

{
  "mcpServers": {
    "mem0-mcp": {
      "command": "node",
      "args": [
        "/absolute/path/to/mem0-mcp/build/index.js"
      ],
      "env": {
        "OPENAI_API_KEY": "YOUR_OPENAI_API_KEY_HERE",
        "DEFAULT_USER_ID": "user123"
      },
      "disabled": false,
      "alwaysAllow": [
        "add_memory",
        "search_memory",
        "delete_memory"
      ]
    }
  }
}

Notas Importantes:

Substitua /absolute/path/to/mem0-mcp/ pelo caminho absoluto real para o seu repositório clonado
Use o arquivo build/index.js, não o arquivo src/index.ts
O servidor MCP requer stdout limpo para comunicação de protocolo - quaisquer bibliotecas ou código que escrevam em stdout podem interferir no protocolo

Configuração do Supabase 🗄️

Se você escolher usar o modo de armazenamento Supabase, precisará configurar seu banco de dados Supabase com a tabela necessária.

1. Criar um Projeto Supabase

Acesse supabase.com e crie um novo projeto
Anote a URL do seu projeto e a chave anônima nas configurações do projeto

2. Executar Migrações SQL

Execute estes comandos SQL no seu Editor SQL do Supabase:

-- Enable the vector extension
create extension if not exists vector;

-- Create the memories table
create table if not exists memories (
  id text primary key,
  embedding vector(1536),
  metadata jsonb,
  created_at timestamp with time zone default timezone('utc', now()),
  updated_at timestamp with time zone default timezone('utc', now())
);

-- Create the vector similarity search function
create or replace function match_vectors(
  query_embedding vector(1536),
  match_count int,
  filter jsonb default '{}'::jsonb
)
returns table (
  id text,
  similarity float,
  metadata jsonb
)
language plpgsql
as $$
begin
  return query
  select
    t.id::text,
    1 - (t.embedding <=> query_embedding) as similarity,
    t.metadata
  from memories t
  where case
    when filter::text = '{}'::text then true
    else t.metadata @> filter
  end
  order by t.embedding <=> query_embedding
  limit match_count;
end;
$$;

-- Create the memory_history table for history tracking
create table if not exists memory_history (
  id text primary key,
  memory_id text not null,
  previous_value text,
  new_value text,
  action text not null,
  created_at timestamp with time zone default timezone('utc', now()),
  updated_at timestamp with time zone,
  is_deleted integer default 0
);

3. Definir Variáveis de Ambiente

Adicione estas à sua configuração MCP:

SUPABASE_URL: A URL do seu projeto Supabase (ex.: https://your-project.supabase.co)
SUPABASE_KEY: Sua chave anônima Supabase
OPENAI_API_KEY: Sua chave de API OpenAI (para embeddings)

Benefícios do Modo Supabase

✅ Armazenamento Persistente - Os dados sobrevivem a reinicializações do servidor ✅ Camada Gratuita Disponível - Camada gratuita generosa para desenvolvimento ✅ Auto-Hospedável - Pode executar sua própria instância Supabase ✅ Escalável - Cresce com suas necessidades ✅ Acesso SQL - Acesso direto ao banco de dados para consultas avançadas ✅ Recursos em Tempo Real - Assinaturas em tempo real integradas

Configuração de Parâmetros 🎯

Entendendo os Parâmetros Mem0

O servidor usa quatro parâmetros-chave para organizar e definir o escopo das memórias:

userId - Identifica o usuário (obrigatório)
agentId - Identifica o LLM/agente que faz a chamada de ferramenta (opcional)
appId - Identifica o projeto/aplicação do usuário - isso controla o escopo do projeto! (opcional)
sessionId - Identifica a sessão de conversa (mapeia para run_id no Mem0) (opcional)

Fallbacks de Variáveis de Ambiente 🔄

O servidor MCP suporta fallbacks de variáveis de ambiente para identificação do usuário e configurações do projeto:

DEFAULT_USER_ID: ID de usuário fallback quando não fornecido nas chamadas de ferramenta
DEFAULT_AGENT_ID: ID de agente fallback para identificar o LLM/agente
DEFAULT_APP_ID: ID de aplicativo fallback para escopo do projeto

Ordem de Prioridade (Importante!)

Parâmetros de Ferramenta (maior prioridade) - Valores fornecidos pelo LLM nas chamadas de ferramenta
Variáveis de Ambiente (fallback) - Valores da sua configuração MCP

Exemplo de Comportamento:

// Your MCP config
"env": {
  "DEFAULT_USER_ID": "john-doe",
  "DEFAULT_AGENT_ID": "my-assistant",
  "DEFAULT_APP_ID": "my-project"
}

Se o LLM fornecer parâmetros:

{
  "tool": "add_memory",
  "arguments": {
    "content": "Remember this",
    "userId": "session-123",        // ← Overrides DEFAULT_USER_ID
    "agentId": "different-agent",   // ← Overrides DEFAULT_AGENT_ID
    "appId": "special-project"      // ← Overrides DEFAULT_APP_ID
    // sessionId omitted           // ← No fallback, will be undefined
  }
}

Resultado: Usa session-123, different-agent e special-project

Se o LLM omitir parâmetros:

{
  "tool": "add_memory",
  "arguments": {
    "content": "Remember this"
    // All IDs omitted - uses environment variables
  }
}

Resultado: Usa john-doe, my-assistant e my-project

Controlando o Comportamento do LLM

Para garantir que suas variáveis de ambiente sejam usadas, instrua seu LLM:

"Use o ID de usuário padrão configurado no ambiente"
"Não especifique os parâmetros userId, agentId ou appId"
"Deixe o servidor usar os padrões configurados"

Recomendação de Prompt de Sistema

Para melhores resultados, inclua instruções no seu prompt de sistema como:

When creating memories, use:
- agentId: "my-assistant"
- appId: "my-project"
- sessionId: "current-conversation-id"

Exemplo de configuração usando DEFAULT_USER_ID:

{
  "mcpServers": {
    "mem0-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@pinkpixel/mem0-mcp"
      ],
      "env": {
        "MEM0_API_KEY": "YOUR_MEM0_API_KEY_HERE",
        "DEFAULT_USER_ID": "user123",
        "ORG_ID": "your-org-id",
        "PROJECT_ID": "your-project-id"
      }
    }
  }
}

Ou ao executar diretamente com node:

git clone https://github.com/pinkpixel-dev/mem0-mcp
cd mem0-mcp
npm install
npm run build

{
  "mcpServers": {
    "mem0-mcp": {
      "command": "node",
      "args": [
        "path/to/mem0-mcp/build/index.js"
      ],
      "env": {
        "OPENAI_API_KEY": "YOUR_OPENAI_API_KEY_HERE",
        "DEFAULT_USER_ID": "user123"
      }
    }
  }
}

Comparação de Modos de Armazenamento 🔄

Armazenamento em Nuvem (API Mem0) ☁️

Persistente por padrão - Suas memórias permanecem disponíveis entre sessões e reinicializações do servidor
Nenhum banco de dados local necessário - Todos os dados são armazenados nos servidores da Mem0
Maior qualidade de recuperação - Usa os algoritmos de busca otimizados da Mem0
Campos adicionais - Suporta parâmetros agent_id e threshold
Totalmente gerenciado - Nenhuma configuração ou manutenção necessária
Requer - Uma chave de API Mem0

Armazenamento Supabase 🗄️

Armazenamento persistente - Os dados são armazenados no seu banco de dados PostgreSQL Supabase
Camada gratuita disponível - Camada gratuita generosa para desenvolvimento e pequenos projetos
Auto-hospedável - Pode executar sua própria instância Supabase para controle total
Acesso SQL - Acesso direto ao banco de dados para consultas avançadas e análises
Escalável - Cresce com suas necessidades, da camada gratuita ao empresarial
Busca vetorial - Usa a extensão pgvector para busca eficiente de similaridade
Recursos em tempo real - Assinaturas em tempo real e webhooks integrados
Requer - Configuração do projeto Supabase e chave de API OpenAI para embeddings

Armazenamento Local (API OpenAI) 💾

Em memória por padrão - Os dados são armazenados apenas na RAM e não são persistentes a longo prazo. Embora algum cache possa ocorrer, você não deve confiar nisso para armazenamento permanente.
Risco de perda de dados - Os dados de memória serão perdidos na reinicialização do servidor, reinicialização do sistema ou se o processo for encerrado
Recomendado para - Desenvolvimento, teste ou uso temporário apenas
Para armazenamento persistente - Use as opções de Armazenamento em Nuvem ou Supabase se precisar de memória confiável de longo prazo
Usa embeddings OpenAI - Para funcionalidade de busca vetorial
Autocontido - Todos os dados permanecem na sua máquina
Requer - Uma chave de API OpenAI

Desenvolvimento 💻

Clone o repositório e instale as dependências:

git clone https://github.com/pinkpixel-dev/mem0-mcp
cd mem0-mcp
npm install

Compile o servidor:

npm run build

Para desenvolvimento com recompilação automática ao alterar arquivos:

npm run watch

Depuração 🐞

Como os servidores MCP se comunicam via stdio, a depuração pode ser desafiadora. Aqui estão algumas abordagens:

Use o MCP Inspector: Esta ferramenta pode monitorar a comunicação do protocolo MCP:

npm run inspector

Registro de Console: Ao adicionar registros de console, sempre use console.error() em vez de console.log() para evitar interferência com o protocolo MCP
Arquivos de Ambiente: Use um arquivo .env para desenvolvimento local para simplificar a configuração de chaves de API e outras opções de configuração

Notas Técnicas de Implementação 🔧

1. Adições Assíncronas da Plataforma V3 e Polling

A adição do Mem0 Cloud V3 é uma tarefa assíncrona em segundo plano. Ao chamar add_memory, o servidor envia a solicitação para /v3/memories/add/ e recebe um eventId.

Polling Síncrono (Padrão): O servidor consulta o endpoint de status do evento (/v1/event/{id}/) a cada 500ms por até timeoutMs (padrão 15000ms) até que o status se torne SUCCEEDED ou FAILED. Quando resolvido, ele retorna o resultado final.
Execução Assíncrona: Passe "waitForCompletion": false para ignorar o polling. O servidor retornará imediatamente o eventId e um status PENDING.

2. Normalização de Filtros V3 Aninhados

Os endpoints de busca e listagem do Mem0 Cloud V3 rejeitam IDs de escopo de nível superior (user_id, agent_id, app_id, run_id) e retornam um erro HTTP 400. O V3 exige que esses campos estejam dentro do objeto aninhado filters. Para evitar quebrar configurações de clientes, este servidor normaliza automaticamente as variáveis de escopo de nível superior (userId, agentId, appId, runId/sessionId) e as mescla no objeto aninhado filters internamente antes de enviar a solicitação à API.

3. Gating de Recursos

Diferentes backends suportam diferentes conjuntos de recursos. Chame get_memory_capabilities para obter uma matriz de capacidades estruturada do backend ativo.

Modo Cloud: Suporta totalmente todos os recursos (apiVersion: "v3", eventos assíncronos, listagem, históricos de auditoria, consultas lógicas).
Modos Supabase / Local: Interfaces vetoriais padrão V1. Ferramentas específicas da nuvem não suportadas (como get_memory_history ou list_memories) falharão graciosamente com mensagens claras de recurso indisponível.

4. Registro e Estabilidade do Protocolo

Os servidores MCP se comunicam usando JSON-RPC sobre stdout. Quaisquer logs de biblioteca inesperados impressos em stdout corromperão o canal do protocolo e causarão falhas nos clientes. Este servidor substitui os métodos de saída padrão do console (como console.log) para redirecionar/ignorar o registro padrão, garantindo uma comunicação stdio limpa.

Feito com 💖 por Pink Pixel