@olivaresai/alma-mcp 1.3.0 → 1.3.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +90 -93
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,36 +1,52 @@
|
|
|
1
|
+
<div align="center">
|
|
2
|
+
|
|
1
3
|
# @olivaresai/alma-mcp
|
|
2
4
|
|
|
3
|
-
MCP
|
|
5
|
+
**MCP Server for [Alma](https://alma.olivares.ai) — persistent memory for AI agents.**
|
|
4
6
|
|
|
5
|
-
|
|
7
|
+
[](https://www.npmjs.com/package/@olivaresai/alma-mcp)
|
|
8
|
+
[](https://modelcontextprotocol.io)
|
|
9
|
+
[](https://nodejs.org)
|
|
6
10
|
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
11
|
+
</div>
|
|
12
|
+
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
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.
|
|
16
|
+
|
|
17
|
+
## Setup
|
|
10
18
|
|
|
11
19
|
### Claude Desktop / Cursor / Windsurf
|
|
12
20
|
|
|
13
|
-
Add to your MCP configuration
|
|
21
|
+
Add to your MCP configuration:
|
|
14
22
|
|
|
15
23
|
```json
|
|
16
24
|
{
|
|
17
25
|
"mcpServers": {
|
|
18
26
|
"alma": {
|
|
19
|
-
"command": "
|
|
27
|
+
"command": "npx",
|
|
28
|
+
"args": ["@olivaresai/alma-mcp"],
|
|
20
29
|
"env": {
|
|
21
|
-
"ALMA_API_KEY": "
|
|
22
|
-
"ALMA_BASE_URL": "https://alma.olivares.ai/api/v1"
|
|
30
|
+
"ALMA_API_KEY": "alma_sk_..."
|
|
23
31
|
}
|
|
24
32
|
}
|
|
25
33
|
}
|
|
26
34
|
}
|
|
27
35
|
```
|
|
28
36
|
|
|
37
|
+
### Global install (alternative)
|
|
38
|
+
|
|
39
|
+
```bash
|
|
40
|
+
npm install -g @olivaresai/alma-mcp
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
Then use `"command": "alma-mcp"` instead of `npx`.
|
|
44
|
+
|
|
29
45
|
### Environment Variables
|
|
30
46
|
|
|
31
47
|
| Variable | Required | Description |
|
|
32
48
|
|----------|----------|-------------|
|
|
33
|
-
| `ALMA_API_KEY` | Yes | Your Alma API key |
|
|
49
|
+
| `ALMA_API_KEY` | Yes | Your Alma API key ([get one here](https://alma.olivares.ai/settings)) |
|
|
34
50
|
| `ALMA_BASE_URL` | No | API base URL (default: `https://alma.olivares.ai/api/v1`) |
|
|
35
51
|
| `ALMA_ENVIRONMENT_ID` | No | Default environment ID |
|
|
36
52
|
| `ALMA_DEBUG` | No | Enable debug logging |
|
|
@@ -39,107 +55,88 @@ Add to your MCP configuration (`claude_desktop_config.json` or equivalent):
|
|
|
39
55
|
|
|
40
56
|
### Context
|
|
41
57
|
|
|
42
|
-
| Tool | Description |
|
|
43
|
-
|
|
44
|
-
| `alma_assemble` | Build a complete system prompt
|
|
45
|
-
| `alma_preview_context` | Preview the
|
|
46
|
-
| `alma_focus` | Update
|
|
47
|
-
| `alma_continue_session` | Continue
|
|
58
|
+
| Tool | Description |
|
|
59
|
+
|------|-------------|
|
|
60
|
+
| `alma_assemble` | Build a complete system prompt — soul, memories, episodes, procedures |
|
|
61
|
+
| `alma_preview_context` | Preview the exact system prompt the LLM would see |
|
|
62
|
+
| `alma_focus` | Update active context focus (what you're working on) |
|
|
63
|
+
| `alma_continue_session` | Continue after context limit, new session, or error |
|
|
48
64
|
|
|
49
65
|
### Memory
|
|
50
66
|
|
|
51
|
-
| Tool | Description |
|
|
52
|
-
|
|
53
|
-
| `alma_remember` | Store a new memory
|
|
54
|
-
| `alma_recall` |
|
|
55
|
-
| `alma_search` | Advanced
|
|
56
|
-
| `
|
|
57
|
-
| `
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
| `
|
|
65
|
-
| `
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
|
77
|
-
|
|
78
|
-
| `
|
|
79
|
-
|
|
80
|
-
### Chat
|
|
81
|
-
|
|
82
|
-
| Tool | Description | Parameters |
|
|
83
|
-
|------|-------------|------------|
|
|
84
|
-
| `alma_chat` | Send a message to Alma and get a response. Supports 3 Claude models. | `message` (required), `conversation_id`, `environment_id`, `model` |
|
|
85
|
-
|
|
86
|
-
### Images
|
|
87
|
-
|
|
88
|
-
| Tool | Description | Parameters |
|
|
89
|
-
|------|-------------|------------|
|
|
90
|
-
| `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) |
|
|
91
|
-
|
|
92
|
-
### Memory Management
|
|
93
|
-
|
|
94
|
-
| Tool | Description | Parameters |
|
|
95
|
-
|------|-------------|------------|
|
|
96
|
-
| `alma_update_memory` | Update an existing memory's content, category, or importance. | `id` (required), `content`, `category`, `importance` (0-1) |
|
|
97
|
-
|
|
98
|
-
### Environments
|
|
99
|
-
|
|
100
|
-
| Tool | Description | Parameters |
|
|
101
|
-
|------|-------------|------------|
|
|
102
|
-
| `alma_list_environments` | List all available environments. | _(none)_ |
|
|
103
|
-
| `alma_create_environment` | Create a new environment. | `name` (required, max 100 chars) |
|
|
104
|
-
|
|
105
|
-
### Data
|
|
106
|
-
|
|
107
|
-
| Tool | Description | Parameters |
|
|
108
|
-
|------|-------------|------------|
|
|
109
|
-
| `alma_export` | Export data from Alma (conversations, memories, soul, or all). | `type` (required: conversation/memories/soul/all), `format` (md/json/html), `conversation_id` |
|
|
67
|
+
| Tool | Description |
|
|
68
|
+
|------|-------------|
|
|
69
|
+
| `alma_remember` | Store a new memory |
|
|
70
|
+
| `alma_recall` | Quick keyword search across memories |
|
|
71
|
+
| `alma_search` | Advanced search — keyword, semantic, or hybrid with filters |
|
|
72
|
+
| `alma_update_memory` | Update an existing memory's content, category, or importance |
|
|
73
|
+
| `alma_delete_memory` | Delete a specific memory |
|
|
74
|
+
| `alma_extract` | Extract memories and episodes from text (conversations, notes) |
|
|
75
|
+
|
|
76
|
+
### Episodes & Procedures
|
|
77
|
+
|
|
78
|
+
| Tool | Description |
|
|
79
|
+
|------|-------------|
|
|
80
|
+
| `alma_list_episodes` | List conversation episode summaries |
|
|
81
|
+
| `alma_search_episodes` | Search episodes by topic |
|
|
82
|
+
| `alma_create_episode` | Create a new episode manually |
|
|
83
|
+
| `alma_list_procedures` | List trigger-action behavioral rules |
|
|
84
|
+
| `alma_create_procedure` | Create a new procedure |
|
|
85
|
+
|
|
86
|
+
### Soul, Chat & More
|
|
87
|
+
|
|
88
|
+
| Tool | Description |
|
|
89
|
+
|------|-------------|
|
|
90
|
+
| `alma_update_block` | Update a soul memory block (identity, rules, etc.) |
|
|
91
|
+
| `alma_chat` | Send a message to Alma and get a response |
|
|
92
|
+
| `alma_generate_image` | Generate an image via Image Studio |
|
|
93
|
+
| `alma_export` | Export data (conversations, memories, soul, all) |
|
|
94
|
+
| `alma_list_environments` | List all environments |
|
|
95
|
+
| `alma_create_environment` | Create a new environment |
|
|
110
96
|
|
|
111
97
|
## Resources (9)
|
|
112
98
|
|
|
113
99
|
| Resource URI | Description |
|
|
114
100
|
|-------------|-------------|
|
|
115
|
-
| `alma://soul` | Current soul configuration
|
|
101
|
+
| `alma://soul` | Current soul configuration |
|
|
116
102
|
| `alma://memories` | Recent memories (last 50) |
|
|
117
|
-
| `alma://memories/{category}` | Memories
|
|
103
|
+
| `alma://memories/{category}` | Memories by category (general, preference, fact, decision, project) |
|
|
118
104
|
| `alma://environments` | All available environments |
|
|
119
|
-
| `alma://conversations` | Recent
|
|
120
|
-
| `alma://budget` |
|
|
121
|
-
| `alma://blocks` | All memory blocks
|
|
105
|
+
| `alma://conversations` | Recent conversations (last 20) |
|
|
106
|
+
| `alma://budget` | Token budget status |
|
|
107
|
+
| `alma://blocks` | All soul memory blocks |
|
|
122
108
|
| `alma://episodes` | Recent episodes (last 20) |
|
|
123
109
|
| `alma://procedures` | All stored procedures (limit 50) |
|
|
124
110
|
|
|
125
|
-
##
|
|
111
|
+
## Models
|
|
126
112
|
|
|
127
|
-
3 models
|
|
113
|
+
3 Claude models available via `alma_chat`:
|
|
128
114
|
|
|
129
|
-
| Model |
|
|
130
|
-
|
|
131
|
-
| `claude-haiku` |
|
|
132
|
-
| `claude-sonnet` |
|
|
133
|
-
| `claude-opus` |
|
|
115
|
+
| Model | Best For |
|
|
116
|
+
|-------|----------|
|
|
117
|
+
| `claude-haiku` | Fast responses, simple tasks |
|
|
118
|
+
| `claude-sonnet` | Balanced quality and speed |
|
|
119
|
+
| `claude-opus` | Deep reasoning, complex work |
|
|
120
|
+
|
|
121
|
+
## Compatible Clients
|
|
122
|
+
|
|
123
|
+
- **Claude Desktop** — Anthropic's official desktop app
|
|
124
|
+
- **Cursor** — AI-powered code editor
|
|
125
|
+
- **Windsurf** — AI development environment
|
|
126
|
+
- Any [MCP-compatible](https://modelcontextprotocol.io) client
|
|
134
127
|
|
|
135
128
|
## Links
|
|
136
129
|
|
|
137
|
-
- [Alma
|
|
138
|
-
- [Documentation](https://
|
|
139
|
-
- [SDK](https://www.npmjs.com/package/@olivaresai/alma-sdk)
|
|
130
|
+
- [Alma App](https://alma.olivares.ai)
|
|
131
|
+
- [Documentation](https://olivares.ai/docs)
|
|
132
|
+
- [JavaScript SDK](https://www.npmjs.com/package/@olivaresai/alma-sdk)
|
|
140
133
|
- [VSCode Extension](https://marketplace.visualstudio.com/items?itemName=olivares.alma-vscode)
|
|
141
|
-
- [
|
|
134
|
+
- [GitHub](https://github.com/olivaresai/alma)
|
|
135
|
+
|
|
136
|
+
---
|
|
137
|
+
|
|
138
|
+
<div align="center">
|
|
142
139
|
|
|
143
|
-
|
|
140
|
+
*Built by [olivares.ai](https://olivares.ai) — Give your AI a soul.*
|
|
144
141
|
|
|
145
|
-
|
|
142
|
+
</div>
|