@olivaresai/alma-mcp 1.3.0

package/LICENSE

@@ -0,0 +1,6 @@
+Copyright (c) 2024-2026 OlivaresAI. All rights reserved.
+
+This software is proprietary and confidential. Unauthorized copying, modification,
+distribution, or use of this software, via any medium, is strictly prohibited.
+
+For licensing inquiries, contact: hello@olivares.ai

package/README.md

@@ -0,0 +1,145 @@
+# @olivaresai/alma-mcp
+
+MCP (Model Context Protocol) server for [Alma](https://alma.olivares.ai) — persistent memory for AI agents. Gives any MCP-compatible client (Claude Desktop, Cursor, Windsurf, etc.) full access to Alma's memory, context, and chat capabilities.
+
+## Setup
+
+```bash
+npm install -g @olivaresai/alma-mcp
+```
+
+### Claude Desktop / Cursor / Windsurf
+
+Add to your MCP configuration (`claude_desktop_config.json` or equivalent):
+
+```json
+{
+  "mcpServers": {
+    "alma": {
+      "command": "alma-mcp",
+      "env": {
+        "ALMA_API_KEY": "your-api-key",
+        "ALMA_BASE_URL": "https://alma.olivares.ai/api/v1"
+      }
+    }
+  }
+}
+```
+
+### Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `ALMA_API_KEY` | Yes | Your Alma API key |
+| `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 | Parameters |
+|------|-------------|------------|
+| `alma_assemble` | Build a complete system prompt from Alma — includes identity (soul), relevant memories, recent episodes, and learned procedures. Use this before sending a message to an LLM. | `message` (required), `environment_id`, `token_budget` |
+| `alma_preview_context` | Preview the full system prompt that Alma would assemble. Shows exactly what the LLM sees. Useful for debugging. | `message` |
+| `alma_focus` | Update Alma's active context focus. Tell Alma what you're currently working on so it can prioritize relevant memories. | `context` (required, max 2000 chars), `source` (web/extension/mcp/api) |
+| `alma_continue_session` | Continue a session after context limit, new session, or error. Generates a summary and continuation prompt. | `conversation_text` (required), `reason` (required: context_limit/new_session/error), `environment_id` |
+
+### Memory
+
+| Tool | Description | Parameters |
+|------|-------------|------------|
+| `alma_remember` | Store a new memory in Alma. | `content` (required, max 50000 chars), `category` (general/preference/fact/decision/project), `importance` (0-1) |
+| `alma_recall` | Search memories by keyword. | `query` (required), `limit` (1-50, default 10) |
+| `alma_search` | Advanced memory search with filters — keyword, semantic, or hybrid mode with date ranges and importance thresholds. | `query` (required), `mode` (keyword/semantic/hybrid), `from`/`to` (ISO dates), `category`, `min_importance` (0-1), `limit` (1-50) |
+| `alma_delete_memory` | Delete a specific memory by ID. | `id` (required) |
+| `alma_extract` | Extract memories and episodes from a block of text (conversation, meeting notes, etc.). | `text` (required, 10-200K chars), `save` (default true), `environment_id` |
+
+### Episodes
+
+| Tool | Description | Parameters |
+|------|-------------|------------|
+| `alma_list_episodes` | List conversation episodes (summaries with topics and outcomes). | `limit` (1-100, default 20), `offset` |
+| `alma_search_episodes` | Search episodes by topic. | `topic` (required), `limit` (1-50, default 10) |
+| `alma_create_episode` | Create a new episode manually. | `summary` (required, max 5000 chars), `topics` (string array), `outcome` |
+
+### Procedures
+
+| Tool | Description | Parameters |
+|------|-------------|------------|
+| `alma_list_procedures` | List stored procedures (trigger-action rules). | `limit` (1-100, default 50), `offset` |
+| `alma_create_procedure` | Create a new procedure. | `trigger_pattern` (required), `action` (required), `context` |
+
+### Soul & Blocks
+
+| Tool | Description | Parameters |
+|------|-------------|------------|
+| `alma_update_block` | Update a soul memory block (identity, rules, language, etc.). | `label` (required), `value` (required) |
+
+### Chat
+
+| Tool | Description | Parameters |
+|------|-------------|------------|
+| `alma_chat` | Send a message to Alma and get a response. Supports 3 Claude models. | `message` (required), `conversation_id`, `environment_id`, `model` |
+
+### Images
+
+| Tool | Description | Parameters |
+|------|-------------|------------|
+| `alma_generate_image` | Generate an image via Alma's Image Studio (Replicate Flux / Leonardo). Requires a paid plan. | `prompt` (required), `style` (natural/vivid/artistic), `size` (square/landscape/portrait) |
+
+### Memory Management
+
+| Tool | Description | Parameters |
+|------|-------------|------------|
+| `alma_update_memory` | Update an existing memory's content, category, or importance. | `id` (required), `content`, `category`, `importance` (0-1) |
+
+### Environments
+
+| Tool | Description | Parameters |
+|------|-------------|------------|
+| `alma_list_environments` | List all available environments. | _(none)_ |
+| `alma_create_environment` | Create a new environment. | `name` (required, max 100 chars) |
+
+### Data
+
+| Tool | Description | Parameters |
+|------|-------------|------------|
+| `alma_export` | Export data from Alma (conversations, memories, soul, or all). | `type` (required: conversation/memories/soul/all), `format` (md/json/html), `conversation_id` |
+
+## Resources (9)
+
+| Resource URI | Description |
+|-------------|-------------|
+| `alma://soul` | Current soul configuration (identity, personality, tone, rules) |
+| `alma://memories` | Recent memories (last 50) |
+| `alma://memories/{category}` | Memories filtered by category (general, preference, fact, decision, project) |
+| `alma://environments` | All available environments |
+| `alma://conversations` | Recent chat conversations (last 20) |
+| `alma://budget` | Current token budget status (usage, remaining, purchased) |
+| `alma://blocks` | All memory blocks (identity, worldview, style, rules, etc.) |
+| `alma://episodes` | Recent episodes (last 20) |
+| `alma://procedures` | All stored procedures (limit 50) |
+
+## Supported Models
+
+3 models (Anthropic Claude):
+
+| Model | Tier | Best For |
+|-------|------|----------|
+| `claude-haiku` | Normal | Fast responses, simple tasks |
+| `claude-sonnet` | Advanced | Balanced quality and speed |
+| `claude-opus` | Complex | Highest quality, deep reasoning |
+
+## Links
+
+- [Alma Platform](https://alma.olivares.ai)
+- [Documentation](https://alma.olivares.ai/docs)
+- [SDK](https://www.npmjs.com/package/@olivaresai/alma-sdk)
+- [VSCode Extension](https://marketplace.visualstudio.com/items?itemName=olivares.alma-vscode)
+- [OlivaresAI](https://olivares.ai)
+
+## License
+
+Proprietary. See [LICENSE](https://github.com/olivaresai/alma/blob/main/LICENSE) for details.