Memanto MCP

MEMANTO é um agente de memória. Ele lembra, recorda e responde — para que seus agentes possam alcançar objetivos de longo prazo e evitar confusão.

GitHub

1.8k

Experimente este MCPPatrocinado

Documentação

Servidor Memanto MCP

Memória semântica persistente para qualquer agente compatível com MCP.

Este pacote expõe as primitivas de memória do Memanto — remember, recall, answer e afins — como ferramentas do Model Context Protocol (MCP) para que qualquer cliente MCP (Claude Desktop, Cursor, Windsurf, Cline, Continue, Goose, agentes personalizados, …) possa se conectar à memória de longo prazo em uma única linha de configuração.

Uma chave de API Moorcheh → memória semântica tipada em todos os agentes que compartilham o namespace, com recuperação abaixo de 90 ms, detecção de conflitos e zero latência de ingestão.

Instalação

pip install memanto-mcp

Requer Python 3.10+, memanto>=0.2.13, mcp>=1.2,<2 e uma chave de API Moorcheh (nível gratuito: 100 mil operações/mês).

Início rápido (Claude Desktop)

Obtenha uma chave de API Moorcheh no console.
Edite claude_desktop_config.json (Configurações → Desenvolvedor → Editar Config):

{
  "mcpServers": {
    "memanto": {
      "command": "memanto-mcp",
      "env": {
        "MOORCHEH_API_KEY": "mch_xxxxxxxxxxxxxxxxxx",
        "MEMANTO_DEFAULT_AGENT_ID": "my-assistant"
      }
    }
  }
}

Reinicie o Claude Desktop. Peça para "lembrar que prefiro respostas concisas" — e amanhã, em um novo chat, pergunte "o que eu prefiro?".

A primeira chamada cria automaticamente o agente e o namespace my-assistant; cada chamada subsequente reutiliza a mesma memória persistente.

Início rápido (Cursor / Windsurf / Cline / Continue / Goose)

A maioria dos clientes consome um arquivo de configuração no formato MCP padrão. O mesmo trecho JSON funciona quase sem alterações:

{
  "mcpServers": {
    "memanto": {
      "command": "memanto-mcp",
      "env": {
        "MOORCHEH_API_KEY": "mch_xxxxxxxxxxxxxxxxxx",
        "MEMANTO_DEFAULT_AGENT_ID": "cursor-workspace"
      }
    }
  }
}

Cliente	Caminho do config
Claude Desktop	`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) / `%APPDATA%\Claude\claude_desktop_config.json` (Windows)
Cursor	`~/.cursor/mcp.json` (ou por projeto `.cursor/mcp.json`)
Windsurf	`~/.codeium/windsurf/mcp_config.json`
Cline (VS Code)	`~/.config/Code/User/globalStorage/cline.cline/settings/cline_mcp_settings.json`
Continue	`~/.continue/config.json` → `experimental.modelContextProtocolServers`
Goose	`~/.config/goose/config.yaml`

Ferramentas disponíveis

O servidor registra 7 ferramentas de memória por padrão. Defina MEMANTO_EXPOSE_ADMIN=true para também expor 4 ferramentas de gerenciamento de agentes.

Ferramentas de memória (sempre ativas)

Ferramenta	Quando o agente deve chamá-la
`remember`	Persistir um único novo fato/preferência/decisão/objetivo/instrução.
`batch_remember`	Persistir até 100 memórias em uma única chamada (ex.: extraídas de um documento).
`recall`	Busca semântica — sempre verifique aqui antes de pedir ao usuário para repetir informações estáveis.
`recall_recent`	"O que acabamos de decidir?" — do mais recente para o mais antigo, sem necessidade de consulta.
`recall_as_of`	Recuperação em um ponto no tempo — "o que sabíamos em 2025-11-01?"
`recall_changed_since`	Diferencial — "o que há de novo desde a última verificação?"
`answer`	RAG: resposta fundamentada do LLM sintetizada sobre as memórias do agente.

Ferramentas de administração de agentes (opt-in)

Ativadas quando MEMANTO_EXPOSE_ADMIN=true:

Ferramenta	Finalidade
`create_agent`	Criar um novo namespace de memória.
`list_agents`	Listar todos os agentes que a chave de API pode ver.
`get_agent`	Consultar os metadados de um agente.
`delete_agent`	Remover os metadados locais de um agente.

Tipos de memória aceitos por remember / batch_remember: fact, preference, goal, decision, artifact, learning, event, instruction, relationship, context, observation, commitment, error.

Valores de proveniência: explicit_statement, inferred, corrected, validated, observed, imported.

Atribuição de origem

source identifica quem escreveu uma memória, para que a recuperação possa ser atribuída e filtrada por escritor. É aberto: user, agent, tool, system ou um escritor específico como cursor, codex, claude_code, mem0. Os rótulos são limitados a 64 letras, dígitos, ., _ ou - para que #source:<value> continue sendo um filtro utilizável.

Quando uma chamada de ferramenta omite source, o servidor atribui a escrita ao cliente MCP conectado a partir do handshake de inicialização (cursor, codex, claude-ai, …), recorrendo a mcp-agent quando o cliente não envia nome. Dois editores que compartilham um mesmo agente permanecem, portanto, distinguíveis na recuperação sem qualquer configuração extra.

Configuração

Toda a configuração é feita por variáveis de ambiente (ordem de carregamento: env do processo → arquivo .env no diretório de trabalho).

Variável	Obrigatória	Padrão	Descrição
`MOORCHEH_API_KEY`	sim	—	Chave de API Moorcheh.
`MEMANTO_DEFAULT_AGENT_ID`	recomendada	nenhum	Agente padrão. Quando definido, as chamadas de ferramenta podem omitir `agent_id`.
`MEMANTO_AGENT_PATTERN`	não	`tool`	Padrão (`support`/`project`/`tool`) usado ao criar automaticamente o agente padrão.
`MEMANTO_AGENT_AUTO_CREATE`	não	`true`	Criar o agente padrão no primeiro uso se não existir. Agentes explícitos não padrão devem já existir.
`MEMANTO_SESSION_DURATION_HOURS`	não	padrão do servidor (6)	Vida útil da sessão em horas.
`MEMANTO_EXPOSE_ADMIN`	não	`false`	Registrar as 4 ferramentas de gerenciamento de agentes.
`MEMANTO_MCP_TRANSPORT`	não	`stdio`	`stdio`, `sse` ou `streamable-http`.
`MEMANTO_MCP_HOST`	não	`127.0.0.1`	Host de vinculação para transportes sse/http.
`MEMANTO_MCP_PORT`	não	`8765`	Porta de vinculação para transportes sse/http.
`MEMANTO_MCP_LOG_LEVEL`	não	`INFO`	Nível de log (os logs são sempre enviados para stderr).

Flags de CLI (memanto-mcp --transport sse --port 9000) sobrescrevem variáveis de ambiente.

Execução via HTTP / SSE

Para clientes remotos ou configurações multiprocesso, execute o servidor em um transporte de rede:

# Streamable HTTP (recommended modern transport)
memanto-mcp --transport streamable-http --host 0.0.0.0 --port 8765

# Server-Sent Events (older, still widely supported)
memanto-mcp --transport sse --host 0.0.0.0 --port 8765

Em seguida, aponte seu cliente para http://your-host:8765/mcp (ou o caminho que o transporte escolhido anunciar). Combine com um proxy reverso + autenticação para implantações em produção — o servidor autentica upstream para a Moorcheh usando sua chave de API, mas não autentica clientes MCP de entrada.

Como funciona

┌──────────────┐    MCP/stdio    ┌──────────────────┐    Moorcheh API    ┌─────────────┐
│ Claude / IDE │ ──────────────► │  memanto-mcp     │ ────────────────► │   Moorcheh  │
│   (client)   │ ◄────────────── │  (this package)  │ ◄──────────────── │   Service   │
└──────────────┘    tool calls   └──────────────────┘    HTTPS+API key   └─────────────┘
                                          │
                                          └─ uses memanto.cli.client.SdkClient
                                             (same client the Memanto CLI uses)

Na inicialização, as configurações são validadas; a chave de API é verificada de forma preguiçosa na primeira chamada de ferramenta.
Na primeira invocação de ferramenta de memória para um determinado agente, o servidor garante que o agente exista (cria automaticamente se necessário) e ativa uma sessão JWT. As sessões se renovam automaticamente antes da expiração, para que conexões MCP de longa duração nunca encontrem um erro de sessão expirada no meio da conversa.
O servidor mantém intencionalmente a sessão ativa no encerramento: as sessões JWT são limitadas por TTL e outros clientes Memanto (CLI, REST) podem querer compartilhá-las.

Incorporação programática

Se você está construindo um host MCP personalizado ou conectando este servidor a um processo maior, você pode construir a instância FastMCP diretamente:

from memanto_mcp import MCPServerSettings, build_server

settings = MCPServerSettings()  # reads env / .env
mcp = build_server(settings)

# Add your own tools alongside Memanto's, then run.
mcp.run(transport="stdio")

Solução de problemas

Sintoma	Correção
`configuration error: MOORCHEH_API_KEY is required`	Defina a variável de ambiente no bloco `env` da configuração do seu cliente MCP.
`Agent '…' does not exist and MEMANTO_AGENT_AUTO_CREATE is disabled`	Reative a criação automática ou chame `create_agent` (ferramentas de administração) / `memanto agent create <id>` uma vez.
As ferramentas nunca aparecem no cliente	Confirme que o cliente suporta MCP e que o caminho do config corresponde. Veja o log MCP do cliente: as linhas de stderr do servidor (prefixadas com `memanto_mcp`) aparecerão lá na inicialização.
Saída distorcida no modo stdio	Algo do seu lado está escrevendo em stdout — esse canal é reservado para JSON-RPC. Mova os logs para stderr. O próprio servidor só escreve em stderr.
Primeira chamada lenta	Custo de inicialização a frio: importação do SDK + primeira ativação de sessão. Chamadas subsequentes reutilizam a sessão ativa.

Licença

MIT — mesma do projeto Memanto. Veja LICENSE.