# MCP Memory Service API Contract Specification
# This document defines the ACTUAL behavior of the MCP Memory Service API
# Used by the HTTP-MCP bridge and other clients

openapi: 3.0.3
info:
  title: MCP Memory Service API
  version: "6.6.1"
  description: |
    API contract for MCP Memory Service - defines actual response formats
    and status codes that clients can expect.
    
    CRITICAL NOTES:
    - Server returns HTTP 200 for both success and failure cases
    - Use the 'success' field in response body to determine actual result
    - All endpoints use /api prefix

servers:
  - url: https://memory.local:8443/api
    description: Default HTTPS server with self-signed certificate
  - url: http://localhost:8000/api
    description: Development HTTP server

security:
  - BearerAuth: []

paths:
  /health:
    get:
      summary: Service health check
      description: Returns current service status and statistics
      responses:
        '200':
          description: Service is healthy
          content:
            application/json:
              schema:
                type: object
                required:
                  - status
                  - version
                properties:
                  status:
                    type: string
                    enum: [healthy]
                  version:
                    type: string
                    example: "6.6.1"
                  timestamp:
                    type: string
                    format: date-time
                  uptime_seconds:
                    type: number
                  storage_type:
                    type: string
                    enum: [sqlite_vec, cloudflare, hybrid]
                  statistics:
                    type: object
                    properties:
                      total_memories:
                        type: integer
                      total_tags:
                        type: integer
        '503':
          description: Service is unhealthy
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum: [unhealthy]
                  error:
                    type: string

  /memories:
    post:
      summary: Store a memory
      description: |
        Store a new memory in the service.
        
        CRITICAL: Always returns HTTP 200, regardless of success/failure!
        Check the 'success' field in response body to determine actual result.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - content
              properties:
                content:
                  type: string
                  description: Memory content to store
                tags:
                  type: array
                  items:
                    type: string
                  default: []
                memory_type:
                  type: string
                  default: "note"
                metadata:
                  type: object
                  default: {}
      responses:
        '200':
          description: Request processed (check success field!)
          content:
            application/json:
              schema:
                oneOf:
                  - type: object
                    title: Success
                    required:
                      - success
                      - message
                      - content_hash
                      - memory
                    properties:
                      success:
                        type: boolean
                        enum: [true]
                      message:
                        type: string
                        example: "Memory stored successfully"
                      content_hash:
                        type: string
                      memory:
                        $ref: '#/components/schemas/Memory'
                  - type: object
                    title: Duplicate
                    required:
                      - success
                      - message
                      - content_hash
                    properties:
                      success:
                        type: boolean
                        enum: [false]
                      message:
                        type: string
                        example: "Duplicate content detected"
                      content_hash:
                        type: string
                      memory:
                        type: 'null'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    example: "Invalid API key"

  /search:
    get:
      summary: Search memories by content
      parameters:
        - name: q
          in: query
          required: true
          schema:
            type: string
        - name: n_results
          in: query
          schema:
            type: integer
            default: 5
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        memory:
                          $ref: '#/components/schemas/Memory'
                        relevance_score:
                          type: number
                          minimum: 0
                          maximum: 1

  /memories/search/tags:
    get:
      summary: Search memories by tags
      parameters:
        - name: tags
          in: query
          required: true
          schema:
            type: string
          description: Comma-separated list of tags
      responses:
        '200':
          description: Tag search results
          content:
            application/json:
              schema:
                type: object
                properties:
                  memories:
                    type: array
                    items:
                      $ref: '#/components/schemas/Memory'

  /memories/{content_hash}:
    delete:
      summary: Delete a memory by content hash
      parameters:
        - name: content_hash
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Deletion result
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
        '404':
          description: Memory not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: API key for authentication

  schemas:
    Memory:
      type: object
      required:
        - content
        - content_hash
        - tags
        - memory_type
        - created_at_iso
      properties:
        content:
          type: string
        content_hash:
          type: string
        tags:
          type: array
          items:
            type: string
        memory_type:
          type: string
        metadata:
          type: object
        created_at:
          type: number
        created_at_iso:
          type: string
          format: date-time
        updated_at:
          type: number
        updated_at_iso:
          type: string
          format: date-time

# Contract Test Cases
x-contract-tests:
  critical-behaviors:
    - name: "Memory storage returns 200 with success field"
      description: "Server never returns 201 - always 200 with success boolean"
      endpoint: "POST /memories"
      expected:
        status: 200
        body_contains: ["success"]
        
    - name: "Health check uses /api/health path"
      description: "Health endpoint is /api/health not /health"
      endpoint: "GET /health"  
      expected:
        status: 200
        
    - name: "URL construction preserves /api base path"
      description: "Bridge must not replace /api when constructing URLs"
      test: "URL construction"
      
    - name: "Duplicate detection returns success=false"
      description: "Duplicates return 200 with success=false, not error status"
      endpoint: "POST /memories"
      scenario: "duplicate_content"
      expected:
        status: 200
        body:
          success: false