t6_mem0/API_DESIGN.md

# MEM0 REST API Design Document

## Overview

The Mem0 Memory System REST API provides programmatic access to memory operations, built on top of mem0 v0.1.115 with Supabase vector storage and Neo4j graph relationships.

## Base Configuration

- **Base URL**: `http://localhost:8080/v1`
- **Content-Type**: `application/json`
- **Authentication**: Bearer token (API Key)
- **Rate Limiting**: 100 requests/minute per API key

## API Architecture

### Core Components

1. **FastAPI Server** - Modern Python web framework with automatic OpenAPI docs
2. **Authentication Middleware** - API key validation and rate limiting  
3. **Memory Service Layer** - Abstraction over mem0 core functionality
4. **Request/Response Models** - Pydantic models for validation
5. **Error Handling** - Standardized error responses
6. **Logging & Monitoring** - Request/response logging

### Data Flow

```
Client Request → Authentication → Validation → Memory Service → mem0 Core → Supabase/Neo4j → Response
```

## Endpoint Design

### 1. Health & Status Endpoints

#### GET /health
- **Purpose**: Basic health check
- **Response**: `{"status": "healthy", "timestamp": "2025-07-31T10:00:00Z"}`
- **Auth**: None required

#### GET /status  
- **Purpose**: Detailed system status
- **Response**: Database connections, service health, version info
- **Auth**: API key required

### 2. Memory CRUD Operations

#### POST /memories
- **Purpose**: Add new memory
- **Request Body**:
  ```json
  {
    "messages": [
      {"role": "user", "content": "I love working with Python and AI"}
    ],
    "user_id": "user_123",
    "metadata": {"source": "chat", "category": "preferences"}
  }
  ```
- **Response**:
  ```json
  {
    "success": true,
    "data": {
      "results": [
        {
          "id": "mem_abc123",
          "memory": "User loves working with Python and AI",
          "event": "ADD",
          "created_at": "2025-07-31T10:00:00Z"
        }
      ]
    },
    "message": "Memory added successfully"
  }
  ```

#### GET /memories/search
- **Purpose**: Search memories by content
- **Query Parameters**:
  - `query` (required): Search query string
  - `user_id` (required): User identifier
  - `limit` (optional, default=10): Number of results
  - `threshold` (optional, default=0.0): Similarity threshold
- **Response**:
  ```json
  {
    "success": true,
    "data": {
      "results": [
        {
          "id": "mem_abc123",
          "memory": "User loves working with Python and AI",
          "score": 0.95,
          "created_at": "2025-07-31T10:00:00Z",
          "metadata": {"source": "chat"}
        }
      ],
      "query": "Python programming",
      "total_results": 1
    }
  }
  ```

#### GET /memories/{memory_id}
- **Purpose**: Retrieve specific memory by ID
- **Path Parameters**: `memory_id` - Memory identifier
- **Response**: Single memory object with full details

#### PUT /memories/{memory_id}
- **Purpose**: Update existing memory
- **Request Body**: Updated memory content and metadata
- **Response**: Updated memory object

#### DELETE /memories/{memory_id}
- **Purpose**: Delete specific memory
- **Response**: Confirmation of deletion

#### GET /memories/user/{user_id}
- **Purpose**: Retrieve all memories for a user
- **Path Parameters**: `user_id` - User identifier
- **Query Parameters**:
  - `limit` (optional): Number of results
  - `offset` (optional): Pagination offset
- **Response**: List of user's memories

### 3. User Management

#### GET /users/{user_id}/stats
- **Purpose**: Get user memory statistics
- **Response**: Memory counts, recent activity, storage usage

#### DELETE /users/{user_id}/memories
- **Purpose**: Delete all memories for a user
- **Response**: Confirmation and count of deleted memories

### 4. System Operations

#### GET /metrics
- **Purpose**: API performance metrics
- **Response**: Request counts, response times, error rates
- **Auth**: Admin API key required

## Request/Response Models

### Standard Response Format

All API responses follow this structure:

```json
{
  "success": boolean,
  "data": object | array | null,
  "message": string,
  "timestamp": "ISO 8601 string",
  "request_id": "uuid"
}
```

### Error Response Format

```json
{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human readable error message",
    "details": object,
    "request_id": "uuid"
  },
  "timestamp": "ISO 8601 string"
}
```

### Memory Object Structure

```json
{
  "id": "mem_abc123def456",
  "memory": "Processed memory content",
  "user_id": "user_123",
  "hash": "content_hash",
  "score": 0.95,
  "metadata": {
    "source": "api",
    "category": "user_preference",
    "custom_field": "value"
  },
  "created_at": "2025-07-31T10:00:00Z",
  "updated_at": "2025-07-31T10:00:00Z"
}
```

## Authentication & Security

### API Key Authentication

- **Header**: `Authorization: Bearer <api_key>`
- **Format**: `mem0_<random_string>` (e.g., `mem0_abc123def456`)
- **Validation**: Keys stored securely, validated on each request
- **Scope**: Different keys can have different permissions

### Rate Limiting

- **Default**: 100 requests per minute per API key
- **Burst**: Up to 20 requests in 10 seconds
- **Headers**: Rate limit info in response headers
  ```
  X-RateLimit-Limit: 100
  X-RateLimit-Remaining: 95
  X-RateLimit-Reset: 1627849200
  ```

### Input Validation

- **Pydantic Models**: Automatic request validation
- **Sanitization**: Content sanitization for XSS prevention
- **Size Limits**: Request body size limits
- **User ID Format**: Validation of user identifier format

## Error Codes

| Code | HTTP Status | Description |
|------|------------|-------------|
| `INVALID_REQUEST` | 400 | Malformed request body or parameters |
| `UNAUTHORIZED` | 401 | Invalid or missing API key |
| `FORBIDDEN` | 403 | API key lacks required permissions |
| `MEMORY_NOT_FOUND` | 404 | Memory with given ID does not exist |
| `USER_NOT_FOUND` | 404 | User has no memories |
| `RATE_LIMIT_EXCEEDED` | 429 | Too many requests |
| `VALIDATION_ERROR` | 422 | Request validation failed |
| `INTERNAL_ERROR` | 500 | Server error |
| `SERVICE_UNAVAILABLE` | 503 | Database or mem0 service unavailable |

## Configuration

### Environment Variables

```bash
# API Configuration
API_HOST=localhost
API_PORT=8080
API_WORKERS=4
API_LOG_LEVEL=info

# Authentication
API_KEYS=mem0_dev_key_123,mem0_prod_key_456
ADMIN_API_KEYS=mem0_admin_key_789

# Rate Limiting
RATE_LIMIT_REQUESTS=100
RATE_LIMIT_WINDOW_MINUTES=1

# mem0 Configuration (from existing config.py)
# Database connections already configured in Phase 1
```

## Performance Considerations

### Caching Strategy
- **Memory Results**: Cache frequently accessed memories
- **User Stats**: Cache user statistics for performance
- **Rate Limiting**: Redis-based rate limit tracking

### Database Optimization
- **Connection Pooling**: Efficient database connections
- **Query Optimization**: Optimized vector similarity searches
- **Indexing**: Proper database indexes for performance

### Monitoring & Logging
- **Request Logging**: All API requests logged
- **Performance Metrics**: Response time tracking
- **Error Tracking**: Comprehensive error logging
- **Health Checks**: Automated health monitoring

## Development Phases

### Phase 2.1: Core API Implementation
1. Basic FastAPI server setup
2. Authentication middleware
3. Core memory CRUD endpoints
4. Basic error handling

### Phase 2.2: Advanced Features  
1. Search and filtering capabilities
2. User management endpoints
3. Rate limiting implementation
4. Comprehensive validation

### Phase 2.3: Production Features
1. Performance optimization
2. Monitoring and metrics
3. Docker containerization
4. API documentation generation

## Testing Strategy

### Unit Tests
- Individual endpoint testing
- Authentication testing
- Validation testing
- Error handling testing

### Integration Tests
- End-to-end API workflows
- Database integration testing
- mem0 service integration
- Multi-user scenarios

### Performance Tests
- Load testing with realistic data
- Rate limiting verification
- Database performance under load
- Memory usage optimization

## Documentation

### Auto-Generated Docs
- **OpenAPI/Swagger**: Automatic API documentation
- **Interactive Testing**: Built-in API testing interface
- **Schema Documentation**: Request/response schemas

### Manual Documentation
- **API Guide**: Usage examples and best practices
- **Integration Guide**: How to integrate with the API
- **Troubleshooting**: Common issues and solutions

---

This design provides a comprehensive REST API that leverages the fully functional mem0 + Supabase infrastructure from Phase 1, with enterprise-ready features for authentication, rate limiting, and monitoring.