@olivaresai/alma-mcp

MCP Server for Alma — persistent memory for AI agents.

Gives any MCP-compatible AI client full access to Alma's persistent memory, context assembly, chat, and data management. Your AI remembers everything — across sessions, tools, and platforms.

Setup

Claude Desktop / Cursor / Windsurf

Add to your MCP configuration:

{
  "mcpServers": {
    "alma": {
      "command": "npx",
      "args": ["@olivaresai/alma-mcp"],
      "env": {
        "ALMA_API_KEY": "alma_sk_..."
      }
    }
  }
}

Global install (alternative)

npm install -g @olivaresai/alma-mcp

Then use "command": "alma-mcp" instead of npx.

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | ALMA_API_KEY | Yes | Your Alma API key (get one here) | | ALMA_BASE_URL | No | API base URL (default: https://alma.olivares.ai/api/v1) | | ALMA_ENVIRONMENT_ID | No | Default environment ID | | ALMA_DEBUG | No | Enable debug logging |

Tools (21)

Context

| Tool | Description | |------|-------------| | alma_assemble | Build a complete system prompt — soul, memories, episodes, procedures | | alma_preview_context | Preview the exact system prompt the LLM would see | | alma_focus | Update active context focus (what you're working on) | | alma_continue_session | Continue after context limit, new session, or error |

Memory

| Tool | Description | |------|-------------| | alma_remember | Store a new memory | | alma_recall | Quick keyword search across memories | | alma_search | Advanced search — keyword, semantic, or hybrid with filters | | alma_update_memory | Update an existing memory's content, category, or importance | | alma_delete_memory | Delete a specific memory | | alma_extract | Extract memories and episodes from text (conversations, notes) |

Episodes & Procedures

| Tool | Description | |------|-------------| | alma_list_episodes | List conversation episode summaries | | alma_search_episodes | Search episodes by topic | | alma_create_episode | Create a new episode manually | | alma_list_procedures | List trigger-action behavioral rules | | alma_create_procedure | Create a new procedure |

Soul, Chat & More

| Tool | Description | |------|-------------| | alma_update_block | Update a soul memory block (identity, rules, etc.) | | alma_chat | Send a message to Alma and get a response | | alma_generate_image | Generate an image via Image Studio | | alma_export | Export data (conversations, memories, soul, all) | | alma_list_environments | List all environments | | alma_create_environment | Create a new environment |

Resources (9)

| Resource URI | Description | |-------------|-------------| | alma://soul | Current soul configuration | | alma://memories | Recent memories (last 50) | | alma://memories/{category} | Memories by category (general, preference, fact, decision, project) | | alma://environments | All available environments | | alma://conversations | Recent conversations (last 20) | | alma://budget | Token budget status | | alma://blocks | All soul memory blocks | | alma://episodes | Recent episodes (last 20) | | alma://procedures | All stored procedures (limit 50) |

Models

3 Claude models available via alma_chat:

| Model | Best For | |-------|----------| | claude-haiku | Fast responses, simple tasks | | claude-sonnet | Balanced quality and speed | | claude-opus | Deep reasoning, complex work |

Compatible Clients

• Claude Desktop — Anthropic's official desktop app
• Cursor — AI-powered code editor
• Windsurf — AI development environment
• Any MCP-compatible client

Links

• Alma App
• Documentation
• JavaScript SDK
• VSCode Extension
• GitHub

Built by olivares.ai — Give your AI a soul.