mnemoverse-com Memory API

openapi: 3.2.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
security:
- apiKey: []
tags:
- name: Memory
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 write gate (novelty check) refuses a write whose novelty score against the nearest memory already stored in the same domain is below 0.1: a near-copy in meaning is refused, not only an exact repeat.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WriteRequest'
      responses:
        '200':
          description: Memory processed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WriteResponse'
      tags:
      - Memory
  /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 plus expansion through learned concept associations 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'
      tags:
      - Memory
  /memory/feedback:
    post:
      operationId: giveFeedback
      summary: Rate memory usefulness
      description: Report whether retrieved memories were helpful. Rating a recalled memory as helpful or misleading re-ranks what comes back next; nothing is erased. 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'
      tags:
      - Memory
  /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'
      tags:
      - Memory
components:
  schemas:
    WriteResponse:
      type: object
      properties:
        stored:
          type: boolean
          description: True if the memory passed the write gate (novelty check)
        atom_id:
          type: string
          format: uuid
          nullable: true
          description: ID of the stored memory, or null if filtered
        importance:
          type: number
          description: 'Novelty score (0 to 1): how different the write is from the nearest existing memory in the same domain'
        reason:
          type: string
          description: Why the memory was stored or filtered
    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
    ReadResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/MemoryItem'
        search_time_ms:
          type: number
    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: 500
          default: 10
          description: Requested number of results. Not a hard cap; association expansion can return more, and the relevance floor can return fewer
        domain:
          type: string
          description: Filter by domain namespace
        include_associations:
          type: boolean
          default: true
          description: Expand results via learned concept associations
    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
    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
    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
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-Api-Key
      description: Your Mnemoverse API key (starts with mk_live_)