Maio 2026 · 7 min de leitura · Fran Olivares, Fundador da OlivaresAI
@olivaresai/alma-mcp como 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 a sua chave de API Alma, e reinicie. O servidor expõe 35 ferramentas de memória que a IA pode chamar de forma autónoma: guardar uma memória, pesquisar memórias, montar contexto, extrair factos, configurar blocos Soul. O tempo total de configuração é cerca de cinco minutos e funciona no plano gratuito da Alma.O Model Context Protocol (MCP) é o standard aberto que permite a clientes de IA falar com ferramentas e fontes de dados externas. Uma vez que o seu cliente fala MCP, pode ligar um servidor de memória e a IA ganha imediatamente ferramentas para ler e escrever num armazenamento de memória persistente — em todas as conversas, todos os projetos, todos os dias. Este guia percorre a configuração de cinco minutos para os quatro clientes mais comuns em 2026 e responde às perguntas que surgem depois.
Quando o servidor MCP da Alma está ligado, o seu cliente de IA obtém 35 novas ferramentas que pode chamar sem que escreva nada. As mais importantes: alma_remember (guardar um facto ou preferência), alma_recall (pesquisar memórias por query 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 factos de um bloco de texto), alma_update_block (configurar blocos do Soul Engine para identidade de IA), mais ferramentas para episódios, procedimentos, environments, conversas, pesquisa web, geração de ficheiros e mais.
Na prática, a IA chama estas ferramentas quando o utilizador pergunta algo relevante para a memória. "Lembra-te que prefiro módulos ESM" → a IA chama alma_remember. "Que stack acordámos para o novo serviço?" → a IA chama alma_recall. O round-trip da ferramenta é sub-segundo; o utilizador apenas vê uma resposta um pouco mais ponderada.
Passo 1. Registe-se em alma.olivares.ai. Comece com o plano Starter ($14/mês) para o nível de entrada.
Passo 2. Em Settings → API Keys, gere uma chave e copie-a.
Passo 3. Abra o ficheiro de configuração do Claude Desktop. Em macOS vive em ~/Library/Application Support/Claude/claude_desktop_config.json; em 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 topo do JSON.
Passo 5. Reinicie o Claude Desktop. As ferramentas Alma aparecem no slash-menu e o Claude pode chamá-las de forma autónoma. Experimente: "lembra-te que o meu editor preferido é o Helix". Um turno depois: "qual é o meu editor preferido?" — o Claude recorda.
A UI MCP do Cursor vive em Settings → Features → MCP. Adicione um novo servidor com o nome alma, command npx, args -y @olivaresai/alma-mcp, e adicione a variável de ambiente ALMA_API_KEY com a sua chave. Guarde e reinicie o Cursor. As ferramentas Alma aparecem no indicador de uso de ferramentas no chat; o Composer e o inline chat têm ambos acesso. Combinado com o contexto de projeto do Cursor, isto dá à IA tanto a sua consciência do código-base como memória persistente entre projetos.
O Windsurf lê configurações MCP de ~/.windsurf/mcp_config.json. A estrutura espelha o Claude Desktop: um objeto mcpServers com o mesmo bloco Alma. Reinicie o Windsurf após editar. As ferramentas Alma aparecem então no Cascade e o Windsurf pode usá-las durante fluxos agênticos — particularmente útil para refatorações multi-ficheiro onde quer que a IA recorde convenções de sessões anteriores.
O Claude Code (o cliente Claude nativo do terminal) tem a sua própria configuração MCP em ~/.config/claude-code/mcp.json. Cole o mesmo bloco Alma. Corra claude mcp list para verificar que o servidor está registado. Uma vez ligado, o Claude Code pode usar as ferramentas da Alma durante sessões de programação; particularmente poderoso quando combinado com a funcionalidade de environments da Alma para que cada repositório tenha o seu próprio namespace de memória. Ver os docs de integração do Claude Code para o JSON exato.
O servidor MCP da Alma fala MCP vanilla sobre stdio, pelo que qualquer cliente conforme funciona. O padrão é sempre o mesmo: o cliente espera um bloco de configuração command + args + env, corre o servidor como processo filho, e descobre ferramentas via o handshake MCP. Se ficar preso num cliente não listado, os logs do servidor (defina ALMA_DEBUG=1 no env) dizem-lhe se o handshake teve sucesso.
Captura de stack. Diga à IA "estou a usar Bun + Hono + D1 para o novo serviço" — ela chama alma_remember. Dois dias depois numa conversa diferente: "faz scaffold de um route handler para /users" — a IA recorda a stack e produz código Bun + Hono idiomático, sem re-explicação.
Registo de decisões. "Decidimos saltar Redis para o MVP e usar D1 diretamente." O agente guarda a decisão com categoria decision e importância alta. Semanas depois ao rever a arquitetura, "porquê sem Redis?" devolve a decisão original com a fundamentação.
Continuidade entre clientes. Guarde uma memória no Claude Desktop de manhã, referencie-a a partir do Cursor de tarde, consulte-a a partir do Claude Code no terminal à noite. A mesma conta Alma, o mesmo armazenamento de memória, todos os clientes veem tudo.
Sim. O servidor MCP da Alma também expõe recursos (dados só de leitura aos quais o cliente pode subscrever): soul, memories, environments, conversations, budget, blocks, episodes, procedures e mais. Clientes que mostram recursos MCP (Claude Desktop em particular) mostram estes numa barra lateral e podem transmitir atualizações. Pode navegar todo o armazenamento de memória de dentro do Claude Desktop sem abrir um browser.
O servidor MCP só faz o que a IA lhe diz para fazer, e apenas com a sua chave de API — não há broadcasting implícito. Todas as escritas de memória são limitadas à sua conta Alma, encriptadas em repouso e exportáveis a pedido. O servidor corre localmente na sua máquina; não faz proxy através de qualquer terceiro para além da própria API Alma. Em termos de custo: o servidor é gratuito de instalar; o plano Starter ($14/mês) é o nível de entrada da Alma e inclui tudo o necessário para correr o servidor MCP.
Uma vez que o servidor está a correr, o movimento de maior alavancagem é popular blocos do Soul Engine (personalidade, especialização, estilo de comunicação, regras duras) para que a IA tenha uma identidade consistente além da memória factual. A aplicação web Alma em alma.olivares.ai expõe o editor Soul; ver Soul Engine: personalidade de IA que persiste para o padrão completo.
Leitura relacionada: Servidor MCP para memória de IA · Como dar memória persistente à IA · Memória persistente para IA: guia completo 2026 · Documentação do servidor MCP · Integração Claude Code.