exovault-mcp-server

MCP server for ExoVault — encrypted, durable memory for AI agents. Gives your agent persistent memory, notes, knowledge graph, tasks, and semantic search via Model Context Protocol.

Quick Start

1. Get an Agent Key

Sign up at exovault.co and generate an agent key (exv_...) from the Connect Wizard.

2. Add to Your MCP Client

Claude Code — add to ~/.claude/settings.json:

{
  "mcpServers": {
    "exo-vault": {
      "command": "npx",
      "args": ["exovault-mcp-server"],
      "env": {
        "EXOVAULT_AGENT_KEY": "exv_your_key_here",
        "EXOVAULT_API_URL": "https://exovault.co"
      }
    }
  }
}

Cursor — add to .cursor/mcp.json:

{
  "mcpServers": {
    "exo-vault": {
      "command": "npx",
      "args": ["exovault-mcp-server"],
      "env": {
        "EXOVAULT_AGENT_KEY": "exv_your_key_here",
        "EXOVAULT_API_URL": "https://exovault.co"
      }
    }
  }
}

Any MCP-compatible client — use the same config format with npx exovault-mcp-server as the command.

3. Restart Your Client

MCP servers are loaded on startup. Restart your client to activate ExoVault.

Interactive Setup

Alternatively, run the CLI wizard:

npx exovault-mcp-server setup --agent-key exv_your_key_here

This validates your key and writes the config to ~/.exovault-mcp/config.json.

Tools

The MCP server exposes 35+ tools organized by category:

Memory

| Tool | Description | |------|-------------| | write_memory | Store durable memories (fact, skill, preference, constraint, task, episodic, correction) | | read_memories | Read memories by ID (batch, max 50) | | search_memories | Semantic + keyword hybrid search with filters | | update_memory | Update content, type, importance, entities | | archive_memory | Archive or unarchive a memory | | get_related_memories | Find related memories via entity links | | cleanup_memories | Find and archive stale/low-importance memories (dry-run supported) |

Notes

| Tool | Description | |------|-------------| | list_notes | List notes with previews, filterable by vault/folder | | read_note | Read full decrypted note content | | read_notes | Batch read multiple notes (max 20) | | search_notes | Keyword search across notes (weighted: title > tags > content) | | create_note | Create an encrypted note | | update_note | Update note title, content, or tags | | delete_note | Permanently delete a note |

Vaults & Folders

| Tool | Description | |------|-------------| | list_vaults | List all vaults with metadata | | create_vault | Create a new vault (idempotent by name) | | list_folders | List folders in a vault | | create_folder | Create a folder with optional parent | | move_note | Move a note to a folder or vault root |

Search & Knowledge Graph

| Tool | Description | |------|-------------| | semantic_search | Vector similarity search across notes and memories | | search_and_read | Hybrid search (70% semantic + 30% keyword) with auto-read | | explore_graph | Knowledge graph traversal — zero LLM cost | | get_links | Get knowledge graph links (incoming/outgoing/both) | | add_link | Create graph links (9 relation types) | | remove_link | Remove a graph link |

Session & Context

| Tool | Description | |------|-------------| | session_start | Load session context (episodic summaries, facts, tasks, constraints) | | context_checkpoint | Save session checkpoint with optional bulk memory writes |

Tasks

| Tool | Description | |------|-------------| | create_task | Create a tracked task with optional auto-completion criteria | | update_task | Update task status, priority, or assignment | | list_tasks | List tasks with filters | | create_plan_tasks | Decompose a plan into tracked tasks |

Messages

| Tool | Description | |------|-------------| | send_message | Send directed messages between agents | | ack_message | Acknowledge receipt of a message | | read_messages | Read inbox with filters |

Documents & Ingestion

| Tool | Description | |------|-------------| | read_document | Read vault documents (instructions, skills, checks) | | update_document | Append to vault documents | | read_docs | Read public ExoVault documentation | | ingest_turn | Push conversation turns for automatic knowledge extraction | | list_active_agents | List recently active agents |

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | EXOVAULT_AGENT_KEY | Yes | Your agent key (exv_...) | | EXOVAULT_API_URL | No | API URL (default: https://exovault.co) |

How It Works

• All data is encrypted — content is encrypted server-side with your agent's derived key
• Gateway mode — all operations route through the ExoVault API, no direct database access
• Session tracking — agent activity is tracked on the ExoVault dashboard
• Knowledge extraction — conversation turns ingested via ingest_turn are automatically processed for facts, skills, and preferences

Links

• ExoVault Dashboard
• Model Context Protocol

License

MIT