openapi: 3.1.0
info:
  title: Mnemoverse Memory API
  description: >
    Persistent memory for AI. Store preferences, decisions, and lessons — recall them
    across sessions and tools. One API key, one memory, everywhere.
  version: 1.0.0

servers:
  - url: https://core.mnemoverse.com/api/v1
    description: Production

components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-Api-Key
      description: Your Mnemoverse API key (starts with mk_live_)

  schemas:
    WriteRequest:
      type: object
      required: [content]
      properties:
        content:
          type: string
          minLength: 1
          maxLength: 10000
          description: The memory to store — a preference, decision, lesson, or fact
        concepts:
          type: array
          items:
            type: string
          description: Key concepts for linking related memories
        domain:
          type: string
          description: "Namespace to organize memories (e.g. 'engineering', 'user:alice')"
          default: general

    WriteResponse:
      type: object
      properties:
        stored:
          type: boolean
          description: True if the memory passed the importance gate
        atom_id:
          type: string
          format: uuid
          nullable: true
          description: ID of the stored memory, or null if filtered
        importance:
          type: number
          description: Computed importance score (0 to 1)
        reason:
          type: string
          description: Why the memory was stored or filtered

    ReadRequest:
      type: object
      required: [query]
      properties:
        query:
          type: string
          minLength: 1
          maxLength: 5000
          description: Natural language search query
        top_k:
          type: integer
          minimum: 1
          maximum: 50
          default: 5
          description: Maximum number of results
        domain:
          type: string
          description: Filter by domain namespace
        include_associations:
          type: boolean
          default: true
          description: Expand results via Hebbian concept associations

    MemoryItem:
      type: object
      properties:
        atom_id:
          type: string
          format: uuid
        content:
          type: string
          description: The stored memory text
        relevance:
          type: number
          description: Relevance score (0 to 1)
        concepts:
          type: array
          items:
            type: string
        domain:
          type: string

    ReadResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/MemoryItem'
        search_time_ms:
          type: number

    FeedbackRequest:
      type: object
      required: [atom_ids, outcome]
      properties:
        atom_ids:
          type: array
          items:
            type: string
            format: uuid
          minItems: 1
          description: IDs of memories to give feedback on
        outcome:
          type: number
          minimum: -1
          maximum: 1
          description: "How helpful: 1.0 = very helpful, 0 = neutral, -1.0 = harmful"

    FeedbackResponse:
      type: object
      properties:
        updated_count:
          type: integer

    StatsResponse:
      type: object
      properties:
        total_atoms:
          type: integer
          description: Total memories stored
        episodes:
          type: integer
        prototypes:
          type: integer
        hebbian_edges:
          type: integer
          description: Concept-concept associations
        domains:
          type: array
          items:
            type: string
        avg_valence:
          type: number
        avg_importance:
          type: number

security:
  - apiKey: []

paths:
  /memory/write:
    post:
      operationId: writeMemory
      summary: Store a memory
      description: >
        Store a preference, decision, lesson, or fact that should persist across sessions.
        Call this PROACTIVELY whenever the user shares something worth remembering.
        The importance gate automatically filters noise — low-value or duplicate memories
        are rejected.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WriteRequest'
      responses:
        '200':
          description: Memory processed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WriteResponse'

  /memory/read:
    post:
      operationId: readMemory
      summary: Search memories
      description: >
        Search the user's memory by natural language query. ALWAYS call this BEFORE answering
        questions about preferences, past decisions, project setup, or anything discussed before.
        This is your long-term memory — it persists across sessions. Semantic search + Hebbian
        concept expansion finds the most relevant memories.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReadRequest'
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReadResponse'

  /memory/feedback:
    post:
      operationId: giveFeedback
      summary: Rate memory usefulness
      description: >
        Report whether retrieved memories were helpful. Positive feedback makes memories
        easier to find next time. Negative feedback lets them fade. Call this after using
        memories from readMemory.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FeedbackRequest'
      responses:
        '200':
          description: Feedback recorded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeedbackResponse'

  /memory/stats:
    get:
      operationId: getMemoryStats
      summary: Memory statistics
      description: >
        Get memory statistics — total memories stored, domains, association count,
        average quality scores. Useful for understanding memory state.
      responses:
        '200':
          description: Statistics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatsResponse'