openapi: 3.0.3
info:
  title: NomeAI Memories API
  version: "1.0.1"
  description: External memory API for AI: save, retrieve, delete memories. Minimal but strict schemas.
servers:
  - url: https://api.nome-ai.com/memories/v1
tags:
  - name: health
  - name: memory
  - name: context
  - name: deletion
paths:
  /health:
    get:
      tags: [health]
      summary: Health check
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Health"
  /memory/inbox:
    post:
      tags: [memory]
      summary: Save memory (minimal)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/MemoryInboxRequest"
            examples:
              basic:
                value:
                  user_id: "user_123"
                  text: "User likes light-roast coffee."
                  guide:
                    intent: "fact"
                    importance_hint: 0.7
                  timestamp: "2025-10-16T00:00:00Z"
      responses:
        "201":
          description: Stored
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MemoryInboxResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
  /context:
    post:
      tags: [context]
      summary: Retrieve context pack (minimal)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ContextRequest"
            examples:
              search:
                value:
                  user_id: "user_123"
                  query: "coffee preference"
                  targets: ["facts","decisions","episode"]
                  limits: { top_k: 4, tokens_budget: 1500 }
      responses:
        "200":
          description: Context items
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContextResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
  /delete/preview:
    post:
      tags: [deletion]
      summary: Preview deletion target count
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DeleteRequest"
      responses:
        "200":
          description: Preview
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DeletePreviewResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
  /delete/confirm:
    post:
      tags: [deletion]
      summary: Confirm deletion (immediate)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DeleteRequest"
      responses:
        "200":
          description: Completed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DeleteConfirmResponse"
        "400":
          $ref: "#/components/responses/BadRequest"

components:
  responses:
    BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
  schemas:
    Health:
      type: object
      properties:
        status: { type: string, example: "ok" }
        time: { type: string, format: date-time }
    MemoryInboxRequest:
      type: object
      required: [user_id, text]
      properties:
        user_id: { type: string }
        text: { type: string, minLength: 1 }
        guide:
          type: object
          properties:
            intent: { type: string, enum: [fact, decision, episode, emotion, reference] }
            importance_hint: { type: number, minimum: 0, maximum: 1 }
        timestamp: { type: string, format: date-time }
    MemoryInboxResponse:
      type: object
      properties:
        id: { type: string, example: "mem_abc123" }
        status: { type: string, example: "stored" }
        saved_at: { type: string, format: date-time }
    ContextRequest:
      type: object
      required: [user_id]
      properties:
        user_id: { type: string }
        query: { type: string }
        targets:
          type: array
          items: { type: string, enum: [facts, decisions, episode, emotion, reference] }
        limits:
          type: object
          properties:
            top_k: { type: integer, minimum: 1, maximum: 32, default: 4 }
            tokens_budget: { type: integer, minimum: 256, maximum: 8000, default: 1500 }
    ContextItem:
      type: object
      properties:
        id: { type: string }
        type: { type: string, enum: [fact, decision, episode, emotion, reference] }
        text: { type: string }
        timestamp: { type: string, format: date-time }
        score: { type: number }
    ContextResponse:
      type: object
      properties:
        items:
          type: array
          items: { $ref: "#/components/schemas/ContextItem" }
        usage:
          type: object
          properties:
            top_k: { type: integer }
            tokens_estimate: { type: integer }
    DeleteRequest:
      type: object
      required: [user_id]
      properties:
        user_id: { type: string }
    DeletePreviewResponse:
      type: object
      properties:
        user_id: { type: string }
        will_delete_count: { type: integer }
    DeleteConfirmResponse:
      type: object
      properties:
        user_id: { type: string }
        deleted_count: { type: integer }
        status: { type: string, example: "completed" }
    Error:
      type: object
      properties:
        error: { type: string }
        detail: { type: string }