# Cloud Memory MCP

A minimal, tag-free personal memory system that syncs across all Claude interfaces (mobile, web, desktop, Claude Code). Built on Cloudflare's edge stack for zero-maintenance serverless operation.

## Features

- **Semantic Search**: Store memories with automatic embeddings, search by meaning
- **Cross-Platform**: Works with Claude Desktop, Claude Code, claude.ai, and mobile
- **Zero Maintenance**: Runs entirely on Cloudflare's edge infrastructure
- **Privacy-First**: Your memories stay in your Cloudflare account
- **Simple Design**: No tags, no categories - just store and search

## Quick Start

### Installation

```bash
npm install -g cloud-memory-mcp
# or
npx cloud-memory-mcp init
```

### Setup

Run the interactive setup wizard:

```bash
cloud-memory-mcp init
```

This will:
1. Prompt for your Cloudflare API token
2. Create a D1 database for memory storage
3. Create a Vectorize index for semantic search
4. Deploy a Cloudflare Worker
5. Generate a secure API token
6. Output configuration for Claude Desktop, Claude Code, and claude.ai

### Configuration

After setup, add the MCP server to your Claude apps:

---

#### Claude.ai (Web)

1. Go to **Settings → Connectors → Add MCP Server**
2. Enter the server URL: `https://cloud-memory-mcp.YOUR_SUBDOMAIN.workers.dev/mcp`
3. Leave OAuth Client ID and Secret **empty**
4. Click Connect
5. An authorization page will open - enter your API token (starts with `cmm_`)
6. Click **Authorize** to complete the connection

---

#### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "memory": {
      "url": "https://cloud-memory-mcp.YOUR_SUBDOMAIN.workers.dev/mcp",
      "transport": "sse",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}
```

---

#### Claude Code

Add to `~/.claude/settings.json`:

```json
{
  "mcpServers": {
    "memory": {
      "url": "https://cloud-memory-mcp.YOUR_SUBDOMAIN.workers.dev/mcp",
      "transport": "sse",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

## MCP Tools

### `remember`

Store a new memory with automatic embedding generation.

```json
{
  "content": "The security consultancy charges $2k for quick scan, $5k for full audit",
  "source": "web"
}
```

### `recall`

Semantic search with optional filters.

```json
{
  "query": "security pricing",
  "limit": 10,
  "after": "2025-01-01T00:00:00Z",
  "source": "web",
  "threshold": 0.3
}
```

### `forget`

Delete memories by ID or time range.

```json
{
  "id": "01HXK5V2XQZJ8N4M3R7P6T9Y2W"
}
```

Or bulk delete:
```json
{
  "before": "2024-01-01T00:00:00Z",
  "confirm": true
}
```

### `list`

List recent memories without semantic search.

```json
{
  "limit": 20,
  "offset": 0,
  "source": "claude-code",
  "order": "newest"
}
```

### `stats`

Get memory statistics.

```json
{}
```

Returns:
```json
{
  "total_memories": 1523,
  "by_source": {
    "mobile": 234,
    "web": 890,
    "claude-code": 399
  },
  "oldest": "2025-01-15T08:00:00Z",
  "newest": "2025-06-20T14:30:00Z"
}
```

## CLI Commands

### `cloud-memory-mcp init`

Interactive setup wizard that creates all necessary Cloudflare resources.

### `cloud-memory-mcp status`

Check deployment status and memory statistics.

### `cloud-memory-mcp deploy`

Redeploy the worker after making local changes.

### `cloud-memory-mcp destroy`

Tear down all Cloudflare resources. Requires typing "delete my memories" to confirm.

### `cloud-memory-mcp token show`

Display your current API token (for copying to new devices).

### `cloud-memory-mcp token rotate`

Generate a new token and invalidate the old one.

## Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                    Cloudflare Edge                          │
├─────────────────────────────────────────────────────────────┤
│   ┌─────────────┐    ┌─────────────┐    ┌──────────────┐   │
│   │   Worker    │    │     D1      │    │  Vectorize   │   │
│   │  (MCP API)  │◄──►│  (SQLite)   │◄──►│ (Embeddings) │   │
│   └─────────────┘    └─────────────┘    └──────────────┘   │
│          │                                                  │
│          ▼                                                  │
│   ┌─────────────────┐                                      │
│   │   Workers AI    │                                      │
│   │ (bge-m3 embed)  │                                      │
│   └─────────────────┘                                      │
└─────────────────────────────────────────────────────────────┘
                              │
                    MCP over HTTP (SSE)
                              │
        ┌─────────────────────┼─────────────────────┐
        ▼                     ▼                     ▼
   Claude Mobile        Claude.ai Web         Claude Code
```

## Cloudflare Free Tier Limits

| Resource | Free Limit | Notes |
|----------|------------|-------|
| Workers | 100k req/day | Plenty for personal use |
| D1 | 5GB storage, 5M rows read/day | ~500k memories at 10KB each |
| Vectorize | 200k vectors, 30M queried/month | Ample for personal use |
| Workers AI | 10k neurons/day | ~300 embeddings/day |

## Development

### Prerequisites

- Node.js 18+
- npm or yarn
- Cloudflare account

### Local Development

```bash
# Install dependencies
npm install

# Build
npm run build

# Run locally with wrangler
npm run dev
```

### Project Structure

```
cloud-memory-mcp/
├── src/
│   ├── index.ts              # Worker entry point, MCP handler
│   ├── tools/
│   │   ├── remember.ts       # remember tool
│   │   ├── recall.ts         # recall tool
│   │   ├── forget.ts         # forget tool
│   │   ├── list.ts           # list tool
│   │   └── stats.ts          # stats tool
│   ├── lib/
│   │   ├── embeddings.ts     # Workers AI embeddings
│   │   ├── vectorize.ts      # Vectorize operations
│   │   ├── db.ts             # D1 database operations
│   │   └── ulid.ts           # ULID generation
│   └── types.ts              # TypeScript interfaces
├── cli/
│   ├── index.ts              # CLI entry point
│   ├── commands/
│   │   ├── init.ts           # Setup wizard
│   │   ├── deploy.ts         # Deploy worker
│   │   ├── status.ts         # Check status
│   │   ├── destroy.ts        # Tear down
│   │   └── token.ts          # Token management
│   └── lib/
│       ├── cloudflare-api.ts # Cloudflare API client
│       ├── prompts.ts        # Interactive prompts
│       ├── config.ts         # Config management
│       └── crypto.ts         # Token generation
├── migrations/
│   └── 0001_initial.sql      # D1 schema
├── wrangler.toml             # Cloudflare Worker config
├── package.json
└── tsconfig.json
```

## Security

- All requests (except `/health`) require bearer token authentication
- Tokens use the format `cmm_` + 32 random alphanumeric characters
- Tokens are stored as encrypted Cloudflare Worker secrets
- Local credentials are stored in `~/.config/cloud-memory-mcp/credentials.json`

## License

MIT