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:

  {
    "messages": [
      {"role": "user", "content": "I love working with Python and AI"}
    ],
    "user_id": "user_123",
    "metadata": {"source": "chat", "category": "preferences"}
  }
  

• Response:

  {
    "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:

  {
    "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:

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

Error Response Format

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

Memory Object Structure

{
  "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

# 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.