exovault-mcp-server 1.0.1 → 1.0.2
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 +167 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,167 @@
|
|
|
1
|
+
# exovault-mcp-server
|
|
2
|
+
|
|
3
|
+
MCP server for [ExoVault](https://exovault.co) — encrypted, durable memory for AI agents. Gives your agent persistent memory, notes, knowledge graph, tasks, and semantic search via [Model Context Protocol](https://modelcontextprotocol.io).
|
|
4
|
+
|
|
5
|
+
## Quick Start
|
|
6
|
+
|
|
7
|
+
### 1. Get an Agent Key
|
|
8
|
+
|
|
9
|
+
Sign up at [exovault.co](https://exovault.co) and generate an agent key (`exv_...`) from the Connect Wizard.
|
|
10
|
+
|
|
11
|
+
### 2. Add to Your MCP Client
|
|
12
|
+
|
|
13
|
+
**Claude Code** — add to `~/.claude/settings.json`:
|
|
14
|
+
|
|
15
|
+
```json
|
|
16
|
+
{
|
|
17
|
+
"mcpServers": {
|
|
18
|
+
"exo-vault": {
|
|
19
|
+
"command": "npx",
|
|
20
|
+
"args": ["exovault-mcp-server"],
|
|
21
|
+
"env": {
|
|
22
|
+
"EXOVAULT_AGENT_KEY": "exv_your_key_here",
|
|
23
|
+
"EXOVAULT_API_URL": "https://exovault.co"
|
|
24
|
+
}
|
|
25
|
+
}
|
|
26
|
+
}
|
|
27
|
+
}
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
**Cursor** — add to `.cursor/mcp.json`:
|
|
31
|
+
|
|
32
|
+
```json
|
|
33
|
+
{
|
|
34
|
+
"mcpServers": {
|
|
35
|
+
"exo-vault": {
|
|
36
|
+
"command": "npx",
|
|
37
|
+
"args": ["exovault-mcp-server"],
|
|
38
|
+
"env": {
|
|
39
|
+
"EXOVAULT_AGENT_KEY": "exv_your_key_here",
|
|
40
|
+
"EXOVAULT_API_URL": "https://exovault.co"
|
|
41
|
+
}
|
|
42
|
+
}
|
|
43
|
+
}
|
|
44
|
+
}
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
**Any MCP-compatible client** — use the same config format with `npx exovault-mcp-server` as the command.
|
|
48
|
+
|
|
49
|
+
### 3. Restart Your Client
|
|
50
|
+
|
|
51
|
+
MCP servers are loaded on startup. Restart your client to activate ExoVault.
|
|
52
|
+
|
|
53
|
+
## Interactive Setup
|
|
54
|
+
|
|
55
|
+
Alternatively, run the CLI wizard:
|
|
56
|
+
|
|
57
|
+
```bash
|
|
58
|
+
npx exovault-mcp-server setup --agent-key exv_your_key_here
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
This validates your key and writes the config to `~/.exovault-mcp/config.json`.
|
|
62
|
+
|
|
63
|
+
## Tools
|
|
64
|
+
|
|
65
|
+
The MCP server exposes 35+ tools organized by category:
|
|
66
|
+
|
|
67
|
+
### Memory
|
|
68
|
+
|
|
69
|
+
| Tool | Description |
|
|
70
|
+
|------|-------------|
|
|
71
|
+
| `write_memory` | Store durable memories (fact, skill, preference, constraint, task, episodic, correction) |
|
|
72
|
+
| `read_memories` | Read memories by ID (batch, max 50) |
|
|
73
|
+
| `search_memories` | Semantic + keyword hybrid search with filters |
|
|
74
|
+
| `update_memory` | Update content, type, importance, entities |
|
|
75
|
+
| `archive_memory` | Archive or unarchive a memory |
|
|
76
|
+
| `get_related_memories` | Find related memories via entity links |
|
|
77
|
+
| `cleanup_memories` | Find and archive stale/low-importance memories (dry-run supported) |
|
|
78
|
+
|
|
79
|
+
### Notes
|
|
80
|
+
|
|
81
|
+
| Tool | Description |
|
|
82
|
+
|------|-------------|
|
|
83
|
+
| `list_notes` | List notes with previews, filterable by vault/folder |
|
|
84
|
+
| `read_note` | Read full decrypted note content |
|
|
85
|
+
| `read_notes` | Batch read multiple notes (max 20) |
|
|
86
|
+
| `search_notes` | Keyword search across notes (weighted: title > tags > content) |
|
|
87
|
+
| `create_note` | Create an encrypted note |
|
|
88
|
+
| `update_note` | Update note title, content, or tags |
|
|
89
|
+
| `delete_note` | Permanently delete a note |
|
|
90
|
+
|
|
91
|
+
### Vaults & Folders
|
|
92
|
+
|
|
93
|
+
| Tool | Description |
|
|
94
|
+
|------|-------------|
|
|
95
|
+
| `list_vaults` | List all vaults with metadata |
|
|
96
|
+
| `create_vault` | Create a new vault (idempotent by name) |
|
|
97
|
+
| `list_folders` | List folders in a vault |
|
|
98
|
+
| `create_folder` | Create a folder with optional parent |
|
|
99
|
+
| `move_note` | Move a note to a folder or vault root |
|
|
100
|
+
|
|
101
|
+
### Search & Knowledge Graph
|
|
102
|
+
|
|
103
|
+
| Tool | Description |
|
|
104
|
+
|------|-------------|
|
|
105
|
+
| `semantic_search` | Vector similarity search across notes and memories |
|
|
106
|
+
| `search_and_read` | Hybrid search (70% semantic + 30% keyword) with auto-read |
|
|
107
|
+
| `explore_graph` | Knowledge graph traversal — zero LLM cost |
|
|
108
|
+
| `get_links` | Get knowledge graph links (incoming/outgoing/both) |
|
|
109
|
+
| `add_link` | Create graph links (9 relation types) |
|
|
110
|
+
| `remove_link` | Remove a graph link |
|
|
111
|
+
|
|
112
|
+
### Session & Context
|
|
113
|
+
|
|
114
|
+
| Tool | Description |
|
|
115
|
+
|------|-------------|
|
|
116
|
+
| `session_start` | Load session context (episodic summaries, facts, tasks, constraints) |
|
|
117
|
+
| `context_checkpoint` | Save session checkpoint with optional bulk memory writes |
|
|
118
|
+
|
|
119
|
+
### Tasks
|
|
120
|
+
|
|
121
|
+
| Tool | Description |
|
|
122
|
+
|------|-------------|
|
|
123
|
+
| `create_task` | Create a tracked task with optional auto-completion criteria |
|
|
124
|
+
| `update_task` | Update task status, priority, or assignment |
|
|
125
|
+
| `list_tasks` | List tasks with filters |
|
|
126
|
+
| `create_plan_tasks` | Decompose a plan into tracked tasks |
|
|
127
|
+
|
|
128
|
+
### Messages
|
|
129
|
+
|
|
130
|
+
| Tool | Description |
|
|
131
|
+
|------|-------------|
|
|
132
|
+
| `send_message` | Send directed messages between agents |
|
|
133
|
+
| `ack_message` | Acknowledge receipt of a message |
|
|
134
|
+
| `read_messages` | Read inbox with filters |
|
|
135
|
+
|
|
136
|
+
### Documents & Ingestion
|
|
137
|
+
|
|
138
|
+
| Tool | Description |
|
|
139
|
+
|------|-------------|
|
|
140
|
+
| `read_document` | Read vault documents (instructions, skills, checks) |
|
|
141
|
+
| `update_document` | Append to vault documents |
|
|
142
|
+
| `read_docs` | Read public ExoVault documentation |
|
|
143
|
+
| `ingest_turn` | Push conversation turns for automatic knowledge extraction |
|
|
144
|
+
| `list_active_agents` | List recently active agents |
|
|
145
|
+
|
|
146
|
+
## Environment Variables
|
|
147
|
+
|
|
148
|
+
| Variable | Required | Description |
|
|
149
|
+
|----------|----------|-------------|
|
|
150
|
+
| `EXOVAULT_AGENT_KEY` | Yes | Your agent key (`exv_...`) |
|
|
151
|
+
| `EXOVAULT_API_URL` | No | API URL (default: `https://exovault.co`) |
|
|
152
|
+
|
|
153
|
+
## How It Works
|
|
154
|
+
|
|
155
|
+
- **All data is encrypted** — content is encrypted server-side with your agent's derived key
|
|
156
|
+
- **Gateway mode** — all operations route through the ExoVault API, no direct database access
|
|
157
|
+
- **Session tracking** — agent activity is tracked on the ExoVault dashboard
|
|
158
|
+
- **Knowledge extraction** — conversation turns ingested via `ingest_turn` are automatically processed for facts, skills, and preferences
|
|
159
|
+
|
|
160
|
+
## Links
|
|
161
|
+
|
|
162
|
+
- [ExoVault Dashboard](https://exovault.co)
|
|
163
|
+
- [Model Context Protocol](https://modelcontextprotocol.io)
|
|
164
|
+
|
|
165
|
+
## License
|
|
166
|
+
|
|
167
|
+
MIT
|