# MemVault MCP Server - Claude Desktop Integration

MemVault offers TWO MCP server modes:

## 🌐 SaaS Mode (Recommended for Production)

Users connect Claude Desktop directly to your hosted MemVault API using their API key.

### Features

- **save_memory** - Save code events with auto-classification
- **recall_memory** - Search memories by content or entity
- **get_account_status** - Check subscription and usage

### Setup for End Users

1. **Get API Key** from https://memvault-demo-g38n.vercel.app/dashboard

2. **Configure Claude Desktop**

Edit `~/.config/Claude/claude_desktop_config.json` (macOS/Linux) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "memvault": {
      "command": "npx",
      "args": ["-y", "@jakops88-hub/memvault-mcp"],
      "env": {
        "MEMVAULT_API_KEY": "your-api-key-here",
        "MEMVAULT_API_URL": "https://moderate-krystal-memvault-af80fe26.koyeb.app"
      }
    }
  }
}
```

3. **Restart Claude Desktop**

### Local Testing (SaaS Mode)

```bash
MEMVAULT_API_KEY=your-key MEMVAULT_API_URL=http://localhost:3000 npm run mcp:client
```

---

## 🔧 Direct Mode (For Self-Hosted Deployments)

Advanced users can run MCP server directly against their own PostgreSQL database.

### Features

All SaaS features plus:
- **search_memories** - Advanced filtering by type/entity
- **get_entity_timeline** - Complete entity history
- **get_memory_graph** - View temporal graph connections

### Setup

Edit Claude Desktop config:

```json
{
  "mcpServers": {
    "memvault-direct": {
      "command": "npx",
      "args": ["ts-node", "/path/to/Long-Term-Memory-API/src/scripts/mcp-server.ts"],
      "env": {
        "DATABASE_URL": "postgresql://...",
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}
```

### Local Testing (Direct Mode)

```bash
npm run mcp
```

---

## Usage Examples

Once configured, Claude can automatically use MemVault:

### Save a Memory
```
"Remember that I fixed the authentication bug by adding proper null checks"
```

### Search Memories
```
"What changes did I make to the auth system?"
```

### Check Status
```
"How much of my MemVault quota have I used?"
```

---

## Troubleshooting

### Trial Expired Error

If you see "Your MemVault trial has ended", upgrade at your dashboard.

### Connection Errors

1. **SaaS Mode**: Verify `MEMVAULT_API_KEY` and `MEMVAULT_API_URL`
2. **Direct Mode**: Check `DATABASE_URL` and database connectivity

### Server Not Showing in Claude

1. Check Claude Desktop logs (Help → View Logs)
2. Verify config JSON syntax
3. Ensure all environment variables are set
4. Test with `npm run mcp:client` first

---

## Architecture

### SaaS Mode
```
Claude Desktop → stdio → MCP Client → HTTPS → MemVault API → PostgreSQL
```

### Direct Mode
```
Claude Desktop → stdio → MCP Server → Prisma Client → PostgreSQL
```

The SaaS mode is recommended for most users as it handles authentication, rate limiting, and billing automatically.