openapi: 3.1.0
info:
  title: Mneme
  version: 1.0.0
servers:
  - url: https://getmneme.com
security:
  - OAuth2: []
paths:
  /api/actions/calibrate:
    get:
      operationId: calibrate
      summary: Run this first to calibrate system
      responses:
        '200':
          description: Calibration complete with system state
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  directive:
                    type: string
                    description: IMPORTANT instruction to follow
                  metrics:
                    type: object

  /api/actions/orchestrate:
    post:
      operationId: orchestrate
      x-openai-isConsequential: false
      summary: Call this for every user message - extracts memories and returns context
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - message
              properties:
                message:
                  type: string
                  description: The user's message to process
      responses:
        '200':
          description: Context for GPT to generate response
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  memoriesExtracted:
                    type: integer
                    description: Number of memories saved from this message
                  attunement:
                    type: object
                    description: Current conversation attunement state
                    properties:
                      turnCount:
                        type: integer
                      topics:
                        type: array
                        items:
                          type: string
                      emotionalRegister:
                        type: string
                      depthLevel:
                        type: number
                  context:
                    type: object
                    description: Context to inform your response
                    properties:
                      persona:
                        type: array
                        items:
                          type: string
                        description: Persona-core memories
                      relevant:
                        type: array
                        items:
                          type: string
                        description: Relevant memories for this message
                      style:
                        type: string
                        description: Response style guidelines
                  instruction:
                    type: string
                    description: How to use this context

  /api/actions/memories/batch:
    post:
      operationId: createMemoriesBatch
      x-openai-isConsequential: false
      summary: Persona seeding only. Extract 15-20 memories in 2 batches of 10. Each needs L2 docs.
      description: For persona seeding. Type=persona, importance=5, include L2 (reason, triggerContext, problemSolved, antiPatterns). Do NOT pause mid-batch.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - memories
              properties:
                memories:
                  type: array
                  description: Array of 10 memories max per batch. For persona seeding, do 2 batches of 10.
                  items:
                    type: object
                    required:
                      - content
                      - type
                      - tags
                    properties:
                      content:
                        type: string
                        description: The memory content
                      type:
                        type: string
                        enum: [persona, preference, pattern, fact, failure, correction, knowledge]
                        description: Use 'persona' for persona-core memories
                      tags:
                        type: array
                        items:
                          type: string
                      importance:
                        type: integer
                        minimum: 1
                        maximum: 5
                        description: Set to 5 for persona-core
                      l2:
                        type: object
                        description: REQUIRED L2 WHY documentation
                        properties:
                          reason:
                            type: string
                            description: Why this memory matters
                          triggerContext:
                            type: string
                            description: What situation triggered this
                          problemSolved:
                            type: string
                            description: What problem this addresses
                          antiPatterns:
                            type: array
                            items:
                              type: string
                            description: What NOT to do
      responses:
        '201':
          description: Batch created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  created:
                    type: integer
                  total:
                    type: integer
                  results:
                    type: array
                    items:
                      type: object

components:
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://getmneme.com/api/oauth/authorize
          tokenUrl: https://getmneme.com/api/oauth/token
          scopes:
            read: Read access to user's memories
            write: Create and update memories
  schemas: {}