mirror of
https://github.com/supermemoryai/supermemory.git
synced 2026-10-10 03:28:14 +00:00
190 lines
6.8 KiB
Text
190 lines
6.8 KiB
Text
---
|
|
title: 'Technical implementation details'
|
|
description: 'Technical implementation details of supermemory MCP'
|
|
---
|
|
|
|
Supermemory MCP Server 4.0 is built as a standalone application on Cloudflare Workers with Durable Objects, providing scalable, persistent connections for AI assistants. The architecture prioritizes **simplicity, reliability, and user experience** while maintaining robust functionality.
|
|
|
|
## Architecture Overview
|
|
|
|
```
|
|
┌─────────────────┐ OAuth/API Key ┌──────────────────┐
|
|
│ MCP Client │◄──────────────►│ Supermemory API │
|
|
│ (Claude, Cursor)│ │ (api.supermemory.ai)
|
|
└────────┬────────┘ └──────────────────┘
|
|
│ ▲
|
|
│ MCP Protocol │ Auth Validation
|
|
▼ │
|
|
┌─────────────────────────────────────────────────────┐
|
|
│ Supermemory MCP Server │
|
|
│ (mcp.supermemory.ai/mcp) │
|
|
│ ┌─────────────────────────────────────────────┐ │
|
|
│ │ Cloudflare Durable Object │ │
|
|
│ │ • Session state │ │
|
|
│ │ • Client info persistence │ │
|
|
│ │ • MCP protocol handling │ │
|
|
│ └─────────────────────────────────────────────┘ │
|
|
└─────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
## Tech Stack
|
|
|
|
- **Runtime:** Cloudflare Workers
|
|
- **State Management:** Durable Objects with SQLite
|
|
- **Web Framework:** Hono
|
|
- **MCP SDK:** @modelcontextprotocol/sdk + agents
|
|
- **API Client:** supermemory SDK
|
|
- **Analytics:** PostHog
|
|
|
|
## Architecture Components
|
|
|
|
### Cloudflare Workers
|
|
|
|
The MCP server runs on Cloudflare Workers, providing:
|
|
- **Global edge deployment** - Low latency worldwide
|
|
- **Automatic scaling** - Handles traffic spikes seamlessly
|
|
- **CPU-based billing** - Cost-efficient since memory connections spend most time waiting between interactions
|
|
- **Built-in security** - DDoS protection and secure infrastructure
|
|
|
|
### Durable Objects
|
|
|
|
Each user session is managed by a Durable Object instance that provides:
|
|
- **Persistent connections** - Long-running WebSocket/SSE connections for MCP protocol
|
|
- **Session state** - Maintains client information and connection state
|
|
- **SQLite storage** - Stores client metadata persistently
|
|
- **Complete isolation** - Each user session runs in its own isolated instance
|
|
|
|
### Authentication Layer
|
|
|
|
The server implements a dual authentication system:
|
|
|
|
**OAuth Flow:**
|
|
1. Client discovers authorization server via `/.well-known/oauth-protected-resource`
|
|
2. User authenticates through Supermemory OAuth provider
|
|
3. Token validated against main API (`/v3/mcp/session-with-key`)
|
|
4. API returns both user info and an API key for subsequent operations
|
|
|
|
**API Key Flow:**
|
|
1. Client provides API key (starting with `sm_`) in Authorization header
|
|
2. Key validated against main API (`/v3/session`)
|
|
3. Direct authentication without OAuth redirect
|
|
|
|
### MCP Protocol Implementation
|
|
|
|
The server implements the Model Context Protocol specification:
|
|
|
|
**Tools:**
|
|
- `memory` - Save or forget user information
|
|
- `recall` - Search memories with hybrid search mode
|
|
- `whoAmI` - Get current user information
|
|
|
|
**Resources:**
|
|
- `supermemory://profile` - User profile with static and dynamic facts
|
|
- `supermemory://projects` - List of available projects
|
|
|
|
**Prompts:**
|
|
- `context` - User profile for system context injection
|
|
|
|
### API Integration
|
|
|
|
The MCP server acts as a bridge between MCP clients and the Supermemory API:
|
|
|
|
**Memory Operations:**
|
|
- Uses the supermemory SDK for all API calls
|
|
- Implements hybrid search mode for better recall accuracy
|
|
- Supports project scoping via `containerTag` parameter
|
|
- Handles content limiting (200k characters max) to prevent token overflow
|
|
|
|
**Profile Generation:**
|
|
- Fetches auto-generated user profiles from the API
|
|
- Separates static (stable preferences) and dynamic (recent activity) facts
|
|
- Combines profile with search results for comprehensive context
|
|
|
|
## Key Features
|
|
|
|
### Hybrid Search
|
|
|
|
The `recall` tool uses hybrid search mode, combining:
|
|
- **Vector search** - Semantic similarity matching
|
|
- **Keyword search** - Exact term matching
|
|
- **Reranking** - Optimizes result relevance
|
|
|
|
This provides more accurate memory retrieval compared to vector-only search.
|
|
|
|
### Project Scoping
|
|
|
|
Memories can be organized by project using the `x-sm-project` header or `containerTag` parameter:
|
|
- Keeps work contexts separate
|
|
- Useful for multi-project development
|
|
- Prevents context bleeding between projects
|
|
|
|
### User Profiles
|
|
|
|
Auto-generated profiles provide:
|
|
- **Static facts** - Stable preferences and characteristics
|
|
- **Dynamic facts** - Recent activity and context
|
|
- **Automatic updates** - Profiles evolve as memories are added
|
|
|
|
### Analytics
|
|
|
|
PostHog integration tracks:
|
|
- Memory additions and deletions
|
|
- Search queries and results
|
|
- Client information (name, version)
|
|
- Session and user identifiers
|
|
|
|
This enables usage monitoring and performance optimization.
|
|
|
|
## Performance Characteristics
|
|
|
|
**Efficiency:**
|
|
- CPU-based billing makes it cost-effective
|
|
- Most time spent waiting (idle) rather than processing
|
|
- Minimal CPU usage despite long-running connections
|
|
|
|
**Scalability:**
|
|
- Durable Objects provide automatic scaling
|
|
- Each session isolated for reliability
|
|
- Global edge deployment reduces latency
|
|
|
|
**Reliability:**
|
|
- Built on Cloudflare's enterprise infrastructure
|
|
- Automatic failover and recovery
|
|
- Session state persisted in SQLite
|
|
|
|
## Development
|
|
|
|
The server is built with modern tooling:
|
|
|
|
**Build System:**
|
|
- Bun for fast package management
|
|
- Wrangler for Cloudflare Workers deployment
|
|
- TypeScript for type safety
|
|
|
|
**Local Development:**
|
|
```bash
|
|
bun install
|
|
bun run dev # Starts at http://localhost:8788
|
|
```
|
|
|
|
**Deployment:**
|
|
```bash
|
|
bun run deploy # Deploys to Cloudflare Workers
|
|
```
|
|
|
|
## Security
|
|
|
|
**Authentication:**
|
|
- OAuth 2.0 with automatic discovery
|
|
- API key validation through main API
|
|
- No credentials stored in MCP server
|
|
|
|
**Data Isolation:**
|
|
- Complete user separation via Durable Objects
|
|
- Session-based access control
|
|
- All data operations scoped to authenticated user
|
|
|
|
**Infrastructure:**
|
|
- Cloudflare's enterprise security
|
|
- DDoS protection
|
|
- Encrypted connections (HTTPS/WSS)
|