# Supermemory Stdio MCP Server

A stdio-based MCP (Model Context Protocol) server that wraps [Supermemory's](https://supermemory.ai) REST API. 

**Why?** Supermemory's official MCP uses HTTP transport which doesn't work well with some MCP clients (like Factory/Droid). This server uses stdio transport which is more universally compatible.

## Features

- 🔌 **Stdio transport** - Works with Factory/Droid, Claude Desktop, Cursor, etc.
- 💾 **Persistent memory** - Save and recall information across sessions
- 🔍 **Semantic search** - Find relevant memories using natural language
- 👤 **User profiles** - Auto-generated profiles from stored memories
- 🏷️ **Project scoping** - Organize memories by project

## Installation

```bash
git clone https://github.com/YOUR_USERNAME/supermemory-stdio-mcp.git
cd supermemory-stdio-mcp
npm install
npm run build
```

## Configuration

### Get your API Key

1. Go to [console.supermemory.ai](https://console.supermemory.ai)
2. Create an account and generate an API key (starts with `sm_`)

### Factory/Droid

Add to `~/.factory/mcp.json`:

```json
{
  "mcpServers": {
    "supermemory": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/supermemory-stdio-mcp/dist/index.js"],
      "env": {
        "SUPERMEMORY_API_KEY": "sm_your_api_key_here",
        "SUPERMEMORY_PROJECT": "your-project-name"
      }
    }
  }
}
```

### Claude Desktop

Add to your Claude Desktop config:

```json
{
  "mcpServers": {
    "supermemory": {
      "command": "node",
      "args": ["/path/to/supermemory-stdio-mcp/dist/index.js"],
      "env": {
        "SUPERMEMORY_API_KEY": "sm_your_api_key_here",
        "SUPERMEMORY_PROJECT": "your-project-name"
      }
    }
  }
}
```

## Tools

### `memory`

Save or forget information about the user.

```json
{
  "content": "User prefers dark mode and uses TypeScript",
  "action": "save"
}
```

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `content` | string | Yes | The information to save or forget |
| `action` | `"save"` \| `"forget"` | No | Default: `"save"` |

### `recall`

Search memories and get user profile.

```json
{
  "query": "What are the user's programming preferences?",
  "includeProfile": true
}
```

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | string | Yes | Search query to find relevant memories |
| `includeProfile` | boolean | No | Include user profile (default: `true`) |

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `SUPERMEMORY_API_KEY` | Yes | Your Supermemory API key (starts with `sm_`) |
| `SUPERMEMORY_PROJECT` | No | Project name to scope memories (default: `"default"`) |

## Development

```bash
# Run in development mode (with hot reload)
npm run dev

# Build for production
npm run build

# Run production build
npm start
```

## How It Works

```
┌─────────────────┐     stdio      ┌─────────────────────┐
│   MCP Client    │◄──────────────►│  This MCP Server    │
│ (Factory/Droid) │                │  (stdio transport)  │
└─────────────────┘                └──────────┬──────────┘
                                              │
                                              │ REST API
                                              ▼
                                   ┌─────────────────────┐
                                   │   Supermemory API   │
                                   │ (api.supermemory.ai)│
                                   └─────────────────────┘
```

## License

MIT

## Credits

- [Supermemory](https://supermemory.ai) - The memory API this wraps
- [Model Context Protocol](https://modelcontextprotocol.io) - The protocol standard