Maio de 2026 · 7 min de leitura · Fran Olivares, fundador da OlivaresAI
@olivaresai/alma-mcp como o servidor, cole um único bloco de JSON na configuração do seu cliente MCP (Claude Desktop, Cursor, Windsurf, Claude Code ou qualquer outro cliente compatível) com sua chave de API Alma e reinicie. O servidor expõe 35 tools de memória que a IA pode chamar autonomamente: salvar uma memory, buscar memories, montar contexto, extrair fatos, configurar blocos Soul. O tempo total de setup é de cerca de cinco minutos e funciona no tier gratuito da Alma.O Model Context Protocol (MCP) é o padrão aberto que permite que clientes de IA conversem com ferramentas e fontes de dados externas. Uma vez que seu cliente fala MCP, você pode plugar um servidor de memória e a IA ganha imediatamente tools para ler e escrever em um armazenamento de memória persistente — entre todas as conversas, todos os projetos, todos os dias. Este guia percorre o setup de cinco minutos para os quatro clientes mais comuns em 2026 e responde as perguntas que surgem depois.
Quando o Alma MCP server está conectado, seu cliente de IA ganha 35 novas tools que ele pode chamar sem você digitar nada. As mais importantes: alma_remember (salvar um fato ou preferência), alma_recall (buscar memories por consulta em linguagem natural), alma_assemble_context (construir um contexto estruturado para a pergunta atual a partir de todas as camadas de memória), alma_extract (extrair fatos de um bloco de texto), alma_update_block (configurar blocos do Soul Engine para identidade da IA), além de tools para episodes, procedures, environments, conversations, busca web, geração de arquivos e mais.
Na prática, a IA chama essas tools quando o usuário pergunta algo relevante para memória. "Lembre que eu prefiro módulos ESM" → a IA chama alma_remember. "Que stack combinamos para o novo serviço?" → a IA chama alma_recall. O round-trip da tool é sub-segundo; o usuário só vê uma resposta um pouco mais ponderada.
Passo 1. Cadastre-se em alma.olivares.ai. Comece com o plano Starter ($14/month) para o tier de entrada.
Passo 2. Em Settings → API Keys, gere uma chave e copie-a.
Passo 3. Abra o arquivo de configuração do Claude Desktop. No macOS fica em ~/Library/Application Support/Claude/claude_desktop_config.json; no Windows em %APPDATA%\Claude\claude_desktop_config.json.
Passo 4. Adicione o servidor Alma dentro do objeto mcpServers: { "alma": { "command": "npx", "args": ["-y", "@olivaresai/alma-mcp"], "env": { "ALMA_API_KEY": "your-key" } } }. Se mcpServers ainda não existe, crie-o no nível raiz do JSON.
Passo 5. Reinicie o Claude Desktop. As tools Alma aparecem no menu de slash e o Claude pode chamá-las autonomamente. Tente: "lembre que meu editor favorito é Helix". Um turno depois: "qual meu editor favorito?" — Claude recupera.
A UI MCP do Cursor fica em Settings → Features → MCP. Adicione um novo servidor com nome alma, comando npx, args -y @olivaresai/alma-mcp e adicione a env var ALMA_API_KEY com sua chave. Salve e reinicie o Cursor. As tools Alma aparecem no indicador de tool-use do chat; Composer e o chat inline ambos têm acesso. Combinado com o contexto de projeto do Cursor, isso dá à IA tanto consciência do seu codebase quanto memória persistente entre projetos.
O Windsurf lê configs MCP de ~/.windsurf/mcp_config.json. A estrutura espelha o Claude Desktop: um objeto mcpServers com o mesmo bloco Alma. Reinicie o Windsurf depois de editar. As tools Alma então aparecem no Cascade e o Windsurf pode usá-las durante fluxos agênticos — particularmente útil para refactors multi-arquivo onde você quer que a IA recupere convenções de sessões anteriores.
O Claude Code (o cliente Claude nativo de terminal) tem sua própria config MCP em ~/.config/claude-code/mcp.json. Coloque o mesmo bloco Alma. Rode claude mcp list para verificar que o servidor está registrado. Uma vez conectado, o Claude Code pode usar as tools da Alma durante sessões de programação; particularmente poderoso quando combinado com o feature de environments da Alma para que cada repo tenha seu próprio namespace de memória. Veja a documentação de integração do Claude Code para o JSON exato.
O Alma MCP server fala MCP padrão sobre stdio, então qualquer cliente compliant funciona. O padrão é sempre o mesmo: o cliente espera um bloco de config com command + args + env, roda o servidor como processo filho e descobre tools via o handshake MCP. Se você travar num cliente não-listado, os logs do servidor (defina ALMA_DEBUG=1 no env) te dizem se o handshake deu certo.
Captura de stack. Diga à IA "estou usando Bun + Hono + D1 para o novo serviço" — ela chama alma_remember. Dois dias depois numa conversa diferente: "scaffold um route handler para /users" — a IA recupera o stack e produz código Bun + Hono idiomático, sem reexplicação.
Log de decisões. "Decidimos pular Redis para o MVP e usar D1 diretamente." O agente salva a decisão com category decision e alta importância. Semanas depois ao revisar a arquitetura, "por que sem Redis?" devolve a decisão original com racional.
Continuidade cross-cliente. Salve uma memory no Claude Desktop pela manhã, referencie-a do Cursor à tarde, consulte-a do Claude Code no terminal à noite. Mesma conta Alma, mesmo armazenamento de memória, cada cliente vê tudo.
Sim. O Alma MCP server também expõe resources (dados somente-leitura aos quais o cliente pode se inscrever): soul, memories, environments, conversations, budget, blocks, episodes, procedures e mais. Clientes que surface resources MCP (Claude Desktop em particular) mostram esses numa sidebar e podem streamar atualizações. Você pode navegar o armazenamento de memória inteiro de dentro do Claude Desktop sem abrir um navegador.
O MCP server só faz o que a IA manda fazer e só com sua chave de API — não há broadcasting implícito. Todas as escritas de memória têm escopo na sua conta Alma, são criptografadas em repouso e exportáveis sob demanda. O servidor roda localmente na sua máquina; não faz proxy por nenhum terceiro além da própria API da Alma. Em termos de custo: o servidor é gratuito para instalar; o plano Starter ($14/mo) é o tier de entrada da Alma e inclui tudo que é necessário para rodar o MCP server.
Uma vez que o servidor está rodando, o movimento de maior alavancagem é popular os blocos do Soul Engine (personalidade, expertise, estilo de comunicação, regras rígidas) para que a IA tenha uma identidade consistente além da memória factual. O app web da Alma em alma.olivares.ai expõe o editor Soul; veja Soul Engine: personalidade de IA que gruda para o padrão completo.
Leitura relacionada: MCP Server para memória de IA · Como dar memória persistente à IA · Memória persistente para IA: guia completo 2026 · Documentação do MCP Server · Integração com Claude Code.