fleet-memory/hindsight-clients/go/api/openapi.yaml

openapi: 3.1.0
info:
  contact:
    name: Memory System
  description: HTTP API for Hindsight
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  title: Hindsight HTTP API
  version: 0.4.11
servers:
- url: /
paths:
  /health:
    get:
      description: Checks the health of the API and database connection
      operationId: health_endpoint_health_get
      responses:
        "200":
          content:
            application/json:
              schema: {}
          description: Successful Response
      summary: Health check endpoint
      tags:
      - Monitoring
  /version:
    get:
      description: Returns API version information and enabled feature flags. Use
        this to check which capabilities are available in this deployment.
      operationId: get_version
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VersionResponse'
          description: Successful Response
      summary: Get API version and feature flags
      tags:
      - Monitoring
  /metrics:
    get:
      description: Exports metrics in Prometheus format for scraping
      operationId: metrics_endpoint_metrics_get
      responses:
        "200":
          content:
            application/json:
              schema: {}
          description: Successful Response
      summary: Prometheus metrics endpoint
      tags:
      - Monitoring
  /v1/default/banks/{bank_id}/graph:
    get:
      description: "Retrieve graph data for visualization, optionally filtered by\
        \ type (world/experience/opinion)."
      operationId: get_graph
      parameters:
      - explode: false
        in: path
        name: bank_id
        required: true
        schema:
          title: Bank Id
          type: string
        style: simple
      - explode: true
        in: query
        name: type
        required: false
        schema:
          nullable: true
          type: string
        style: form
      - explode: true
        in: query
        name: limit
        required: false
        schema:
          default: 1000
          title: Limit
          type: integer
        style: form
      - explode: false
        in: header
        name: authorization
        required: false
        schema:
          nullable: true
          type: string
        style: simple
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphDataResponse'
          description: Successful Response
        "422":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Get memory graph data
      tags:
      - Memory
  /v1/default/banks/{bank_id}/memories/list:
    get:
      description: "List memory units with pagination and optional full-text search.\
        \ Supports filtering by type. Results are sorted by most recent first (mentioned_at\
        \ DESC, then created_at DESC)."
      operationId: list_memories
      parameters:
      - explode: false
        in: path
        name: bank_id
        required: true
        schema:
          title: Bank Id
          type: string
        style: simple
      - explode: true
        in: query
        name: type
        required: false
        schema:
          nullable: true
          type: string
        style: form
      - explode: true
        in: query
        name: q
        required: false
        schema:
          nullable: true
          type: string
        style: form
      - explode: true
        in: query
        name: limit
        required: false
        schema:
          default: 100
          title: Limit
          type: integer
        style: form
      - explode: true
        in: query
        name: offset
        required: false
        schema:
          default: 0
          title: Offset
          type: integer
        style: form
      - explode: false
        in: header
        name: authorization
        required: false
        schema:
          nullable: true
          type: string
        style: simple
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListMemoryUnitsResponse'
          description: Successful Response
        "422":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: List memory units
      tags:
      - Memory
  /v1/default/banks/{bank_id}/memories/{memory_id}:
    get:
      description: Get a single memory unit by ID with all its metadata including
        entities and tags.
      operationId: get_memory
      parameters:
      - explode: false
        in: path
        name: bank_id
        required: true
        schema:
          title: Bank Id
          type: string
        style: simple
      - explode: false
        in: path
        name: memory_id
        required: true
        schema:
          title: Memory Id
          type: string
        style: simple
      - explode: false
        in: header
        name: authorization
        required: false
        schema:
          nullable: true
          type: string
        style: simple
      responses:
        "200":
          content:
            application/json:
              schema: {}
          description: Successful Response
        "422":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Get memory unit
      tags:
      - Memory
  /v1/default/banks/{bank_id}/memories/recall:
    post:
      description: |-
        Recall memory using semantic similarity and spreading activation.

        The type parameter is optional and must be one of:
        - `world`: General knowledge about people, places, events, and things that happen
        - `experience`: Memories about experience, conversations, actions taken, and tasks performed        
      operationId: recall_memories
      parameters:
      - explode: false
        in: path
        name: bank_id
        required: true
        schema:
          title: Bank Id
          type: string
        style: simple
      - explode: false
        in: header
        name: authorization
        required: false
        schema:
          nullable: true
          type: string
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RecallRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecallResponse'
          description: Successful Response
        "422":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Recall memory
      tags:
      - Memory
  /v1/default/banks/{bank_id}/reflect:
    post:
      description: |-
        Reflect and formulate an answer using bank identity, world facts, and opinions.

        This endpoint:
        1. Retrieves experience (conversations and events)
        2. Retrieves world facts relevant to the query
        3. Retrieves existing opinions (bank's perspectives)
        4. Uses LLM to formulate a contextual answer
        5. Returns plain text answer and the facts used        
      operationId: reflect
      parameters:
      - explode: false
        in: path
        name: bank_id
        required: true
        schema:
          title: Bank Id
          type: string
        style: simple
      - explode: false
        in: header
        name: authorization
        required: false
        schema:
          nullable: true
          type: string
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReflectRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReflectResponse'
          description: Successful Response
        "422":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Reflect and generate answer
      tags:
      - Memory
  /v1/default/banks:
    get:
      description: Get a list of all agents with their profiles
      operationId: list_banks
      parameters:
      - explode: false
        in: header
        name: authorization
        required: false
        schema:
          nullable: true
          type: string
        style: simple
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankListResponse'
          description: Successful Response
        "422":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: List all memory banks
      tags:
      - Banks
  /v1/default/banks/{bank_id}/stats:
    get:
      description: Get statistics about nodes and links for a specific agent
      operationId: get_agent_stats
      parameters:
      - explode: false
        in: path
        name: bank_id
        required: true
        schema:
          title: Bank Id
          type: string
        style: simple
      - explode: false
        in: header
        name: authorization
        required: false
        schema:
          nullable: true
          type: string
        style: simple
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankStatsResponse'
          description: Successful Response
        "422":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Get statistics for memory bank
      tags:
      - Banks
  /v1/default/banks/{bank_id}/entities:
    get:
      description: "List all entities (people, organizations, etc.) known by the bank,\
        \ ordered by mention count. Supports pagination."
      operationId: list_entities
      parameters:
      - explode: false
        in: path
        name: bank_id
        required: true
        schema:
          title: Bank Id
          type: string
        style: simple
      - description: Maximum number of entities to return
        explode: true
        in: query
        name: limit
        required: false
        schema:
          default: 100
          description: Maximum number of entities to return
          title: Limit
          type: integer
        style: form
      - description: Offset for pagination
        explode: true
        in: query
        name: offset
        required: false
        schema:
          default: 0
          description: Offset for pagination
          title: Offset
          type: integer
        style: form
      - explode: false
        in: header
        name: authorization
        required: false
        schema:
          nullable: true
          type: string
        style: simple
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityListResponse'
          description: Successful Response
        "422":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: List entities
      tags:
      - Entities
  /v1/default/banks/{bank_id}/entities/{entity_id}:
    get:
      description: Get detailed information about an entity including observations
        (mental model).
      operationId: get_entity
      parameters:
      - explode: false
        in: path
        name: bank_id
        required: true
        schema:
          title: Bank Id
          type: string
        style: simple
      - explode: false
        in: path
        name: entity_id
        required: true
        schema:
          title: Entity Id
          type: string
        style: simple
      - explode: false
        in: header
        name: authorization
        required: false
        schema:
          nullable: true
          type: string
        style: simple
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityDetailResponse'
          description: Successful Response
        "422":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Get entity details
      tags:
      - Entities
  /v1/default/banks/{bank_id}/entities/{entity_id}/regenerate:
    post:
      deprecated: true
      description: This endpoint is deprecated. Entity observations have been replaced
        by mental models.
      operationId: regenerate_entity_observations
      parameters:
      - explode: false
        in: path
        name: bank_id
        required: true
        schema:
          title: Bank Id
          type: string
        style: simple
      - explode: false
        in: path
        name: entity_id
        required: true
        schema:
          title: Entity Id
          type: string
        style: simple
      - explode: false
        in: header
        name: authorization
        required: false
        schema:
          nullable: true
          type: string
        style: simple
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityDetailResponse'
          description: Successful Response
        "422":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Regenerate entity observations (deprecated)
      tags:
      - Entities
  /v1/default/banks/{bank_id}/mental-models:
    get:
      description: List user-curated living documents that stay current.
      operationId: list_mental_models
      parameters:
      - explode: false
        in: path
        name: bank_id
        required: true
        schema:
          title: Bank Id
          type: string
        style: simple
      - description: Filter by tags
        explode: true
        in: query
        name: tags
        required: false
        schema:
          items:
            type: string
          nullable: true
          type: array
        style: form
      - description: How to match tags
        explode: true
        in: query
        name: tags_match
        required: false
        schema:
          default: any
          description: How to match tags
          enum:
          - any
          - all
          - exact
          title: Tags Match
          type: string
        style: form
      - explode: true
        in: query
        name: limit
        required: false
        schema:
          default: 100
          maximum: 1000
          minimum: 1
          title: Limit
          type: integer
        style: form
      - explode: true
        in: query
        name: offset
        required: false
        schema:
          default: 0
          minimum: 0
          title: Offset
          type: integer
        style: form
      - explode: false
        in: header
        name: authorization
        required: false
        schema:
          nullable: true
          type: string
        style: simple
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MentalModelListResponse'
          description: Successful Response
        "422":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: List mental models
      tags:
      - Mental Models
    post:
      description: Create a mental model by running reflect with the source query
        in the background. Returns an operation ID to track progress. The content
        is auto-generated by the reflect endpoint. Use the operations endpoint to
        check completion status.
      operationId: create_mental_model
      parameters:
      - explode: false
        in: path
        name: bank_id
        required: true
        schema:
          title: Bank Id
          type: string
        style: simple
      - explode: false
        in: header
        name: authorization
        required: false
        schema:
          nullable: true
          type: string
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateMentalModelRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateMentalModelResponse'
          description: Successful Response
        "422":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Create mental model
      tags:
      - Mental Models
  /v1/default/banks/{bank_id}/mental-models/{mental_model_id}:
    delete:
      description: Delete a mental model.
      operationId: delete_mental_model
      parameters:
      - explode: false
        in: path
        name: bank_id
        required: true
        schema:
          title: Bank Id
          type: string
        style: simple
      - explode: false
        in: path
        name: mental_model_id
        required: true
        schema:
          title: Mental Model Id
          type: string
        style: simple
      - explode: false
        in: header
        name: authorization
        required: false
        schema:
          nullable: true
          type: string
        style: simple
      responses:
        "200":
          content:
            application/json:
              schema: {}
          description: Successful Response
        "422":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Delete mental model
      tags:
      - Mental Models
    get:
      description: Get a specific mental model by ID.
      operationId: get_mental_model
      parameters:
      - explode: false
        in: path
        name: bank_id
        required: true
        schema:
          title: Bank Id
          type: string
        style: simple
      - explode: false
        in: path
        name: mental_model_id
        required: true
        schema:
          title: Mental Model Id
          type: string
        style: simple
      - explode: false
        in: header
        name: authorization
        required: false
        schema:
          nullable: true
          type: string
        style: simple
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MentalModelResponse'
          description: Successful Response
        "422":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Get mental model
      tags:
      - Mental Models
    patch:
      description: Update a mental model's name and/or source query.
      operationId: update_mental_model
      parameters:
      - explode: false
        in: path
        name: bank_id
        required: true
        schema:
          title: Bank Id
          type: string
        style: simple
      - explode: false
        in: path
        name: mental_model_id
        required: true
        schema:
          title: Mental Model Id
          type: string
        style: simple
      - explode: false
        in: header
        name: authorization
        required: false
        schema:
          nullable: true
          type: string
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateMentalModelRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MentalModelResponse'
          description: Successful Response
        "422":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Update mental model
      tags:
      - Mental Models
  /v1/default/banks/{bank_id}/mental-models/{mental_model_id}/refresh:
    post:
      description: Submit an async task to re-run the source query through reflect
        and update the content.
      operationId: refresh_mental_model
      parameters:
      - explode: false
        in: path
        name: bank_id
        required: true
        schema:
          title: Bank Id
          type: string
        style: simple
      - explode: false
        in: path
        name: mental_model_id
        required: true
        schema:
          title: Mental Model Id
          type: string
        style: simple
      - explode: false
        in: header
        name: authorization
        required: false
        schema:
          nullable: true
          type: string
        style: simple
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncOperationSubmitResponse'
          description: Successful Response
        "422":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Refresh mental model
      tags:
      - Mental Models
  /v1/default/banks/{bank_id}/directives:
    get:
      description: List hard rules that are injected into prompts.
      operationId: list_directives
      parameters:
      - explode: false
        in: path
        name: bank_id
        required: true
        schema:
          title: Bank Id
          type: string
        style: simple
      - description: Filter by tags
        explode: true
        in: query
        name: tags
        required: false
        schema:
          items:
            type: string
          nullable: true
          type: array
        style: form
      - description: How to match tags
        explode: true
        in: query
        name: tags_match
        required: false
        schema:
          default: any
          description: How to match tags
          enum:
          - any
          - all
          - exact
          title: Tags Match
          type: string
        style: form
      - description: Only return active directives
        explode: true
        in: query
        name: active_only
        required: false
        schema:
          default: true
          description: Only return active directives
          title: Active Only
          type: boolean
        style: form
      - explode: true
        in: query
        name: limit
        required: false
        schema:
          default: 100
          maximum: 1000
          minimum: 1
          title: Limit
          type: integer
        style: form
      - explode: true
        in: query
        name: offset
        required: false
        schema:
          default: 0
          minimum: 0
          title: Offset
          type: integer
        style: form
      - explode: false
        in: header
        name: authorization
        required: false
        schema:
          nullable: true
          type: string
        style: simple
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DirectiveListResponse'
          description: Successful Response
        "422":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: List directives
      tags:
      - Directives
    post:
      description: Create a hard rule that will be injected into prompts.
      operationId: create_directive
      parameters:
      - explode: false
        in: path
        name: bank_id
        required: true
        schema:
          title: Bank Id
          type: string
        style: simple
      - explode: false
        in: header
        name: authorization
        required: false
        schema:
          nullable: true
          type: string
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDirectiveRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DirectiveResponse'
          description: Successful Response
        "422":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Create directive
      tags:
      - Directives
  /v1/default/banks/{bank_id}/directives/{directive_id}:
    delete:
      description: Delete a directive.
      operationId: delete_directive
      parameters:
      - explode: false
        in: path
        name: bank_id
        required: true
        schema:
          title: Bank Id
          type: string
        style: simple
      - explode: false
        in: path
        name: directive_id
        required: true
        schema:
          title: Directive Id
          type: string
        style: simple
      - explode: false
        in: header
        name: authorization
        required: false
        schema:
          nullable: true
          type: string
        style: simple
      responses:
        "200":
          content:
            application/json:
              schema: {}
          description: Successful Response
        "422":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Delete directive
      tags:
      - Directives
    get:
      description: Get a specific directive by ID.
      operationId: get_directive
      parameters:
      - explode: false
        in: path
        name: bank_id
        required: true
        schema:
          title: Bank Id
          type: string
        style: simple
      - explode: false
        in: path
        name: directive_id
        required: true
        schema:
          title: Directive Id
          type: string
        style: simple
      - explode: false
        in: header
        name: authorization
        required: false
        schema:
          nullable: true
          type: string
        style: simple
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DirectiveResponse'
          description: Successful Response
        "422":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Get directive
      tags:
      - Directives
    patch:
      description: Update a directive's properties.
      operationId: update_directive
      parameters:
      - explode: false
        in: path
        name: bank_id
        required: true
        schema:
          title: Bank Id
          type: string
        style: simple
      - explode: false
        in: path
        name: directive_id
        required: true
        schema:
          title: Directive Id
          type: string
        style: simple
      - explode: false
        in: header
        name: authorization
        required: false
        schema:
          nullable: true
          type: string
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateDirectiveRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DirectiveResponse'
          description: Successful Response
        "422":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Update directive
      tags:
      - Directives
  /v1/default/banks/{bank_id}/documents:
    get:
      description: List documents with pagination and optional search. Documents are
        the source content from which memory units are extracted.
      operationId: list_documents
      parameters:
      - explode: false
        in: path
        name: bank_id
        required: true
        schema:
          title: Bank Id
          type: string
        style: simple
      - explode: true
        in: query
        name: q
        required: false
        schema:
          nullable: true
          type: string
        style: form
      - explode: true
        in: query
        name: limit
        required: false
        schema:
          default: 100
          title: Limit
          type: integer
        style: form
      - explode: true
        in: query
        name: offset
        required: false
        schema:
          default: 0
          title: Offset
          type: integer
        style: form
      - explode: false
        in: header
        name: authorization
        required: false
        schema:
          nullable: true
          type: string
        style: simple
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListDocumentsResponse'
          description: Successful Response
        "422":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: List documents
      tags:
      - Documents
  /v1/default/banks/{bank_id}/documents/{document_id}:
    delete:
      description: |-
        Delete a document and all its associated memory units and links.

        This will cascade delete:
        - The document itself
        - All memory units extracted from this document
        - All links (temporal, semantic, entity) associated with those memory units

        This operation cannot be undone.        
      operationId: delete_document
      parameters:
      - explode: false
        in: path
        name: bank_id
        required: true
        schema:
          title: Bank Id
          type: string
        style: simple
      - explode: false
        in: path
        name: document_id
        required: true
        schema:
          title: Document Id
          type: string
        style: simple
      - explode: false
        in: header
        name: authorization
        required: false
        schema:
          nullable: true
          type: string
        style: simple
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteDocumentResponse'
          description: Successful Response
        "422":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Delete a document
      tags:
      - Documents
    get:
      description: Get a specific document including its original text
      operationId: get_document
      parameters:
      - explode: false
        in: path
        name: bank_id
        required: true
        schema:
          title: Bank Id
          type: string
        style: simple
      - explode: false
        in: path
        name: document_id
        required: true
        schema:
          title: Document Id
          type: string
        style: simple
      - explode: false
        in: header
        name: authorization
        required: false
        schema:
          nullable: true
          type: string
        style: simple
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentResponse'
          description: Successful Response
        "422":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Get document details
      tags:
      - Documents
  /v1/default/banks/{bank_id}/tags:
    get:
      description: "List all unique tags in a memory bank with usage counts. Supports\
        \ wildcard search using '*' (e.g., 'user:*', '*-fred', 'tag*-2'). Case-insensitive."
      operationId: list_tags
      parameters:
      - explode: false
        in: path
        name: bank_id
        required: true
        schema:
          title: Bank Id
          type: string
        style: simple
      - description: "Wildcard pattern to filter tags (e.g., 'user:*' for user:alice,\
          \ '*-admin' for role-admin). Use '*' as wildcard. Case-insensitive."
        explode: true
        in: query
        name: q
        required: false
        schema:
          nullable: true
          type: string
        style: form
      - description: Maximum number of tags to return
        explode: true
        in: query
        name: limit
        required: false
        schema:
          default: 100
          description: Maximum number of tags to return
          title: Limit
          type: integer
        style: form
      - description: Offset for pagination
        explode: true
        in: query
        name: offset
        required: false
        schema:
          default: 0
          description: Offset for pagination
          title: Offset
          type: integer
        style: form
      - explode: false
        in: header
        name: authorization
        required: false
        schema:
          nullable: true
          type: string
        style: simple
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListTagsResponse'
          description: Successful Response
        "422":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: List tags
      tags:
      - Memory
  /v1/default/chunks/{chunk_id}:
    get:
      description: Get a specific chunk by its ID
      operationId: get_chunk
      parameters:
      - explode: false
        in: path
        name: chunk_id
        required: true
        schema:
          title: Chunk Id
          type: string
        style: simple
      - explode: false
        in: header
        name: authorization
        required: false
        schema:
          nullable: true
          type: string
        style: simple
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChunkResponse'
          description: Successful Response
        "422":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Get chunk details
      tags:
      - Documents
  /v1/default/banks/{bank_id}/operations:
    get:
      description: "Get a list of async operations for a specific agent, with optional\
        \ filtering by status. Results are sorted by most recent first."
      operationId: list_operations
      parameters:
      - explode: false
        in: path
        name: bank_id
        required: true
        schema:
          title: Bank Id
          type: string
        style: simple
      - description: "Filter by status: pending, completed, or failed"
        explode: true
        in: query
        name: status
        required: false
        schema:
          nullable: true
          type: string
        style: form
      - description: Maximum number of operations to return
        explode: true
        in: query
        name: limit
        required: false
        schema:
          default: 20
          description: Maximum number of operations to return
          maximum: 100
          minimum: 1
          title: Limit
          type: integer
        style: form
      - description: Number of operations to skip
        explode: true
        in: query
        name: offset
        required: false
        schema:
          default: 0
          description: Number of operations to skip
          minimum: 0
          title: Offset
          type: integer
        style: form
      - explode: false
        in: header
        name: authorization
        required: false
        schema:
          nullable: true
          type: string
        style: simple
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationsListResponse'
          description: Successful Response
        "422":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: List async operations
      tags:
      - Operations
  /v1/default/banks/{bank_id}/operations/{operation_id}:
    delete:
      description: Cancel a pending async operation by removing it from the queue
      operationId: cancel_operation
      parameters:
      - explode: false
        in: path
        name: bank_id
        required: true
        schema:
          title: Bank Id
          type: string
        style: simple
      - explode: false
        in: path
        name: operation_id
        required: true
        schema:
          title: Operation Id
          type: string
        style: simple
      - explode: false
        in: header
        name: authorization
        required: false
        schema:
          nullable: true
          type: string
        style: simple
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CancelOperationResponse'
          description: Successful Response
        "422":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Cancel a pending async operation
      tags:
      - Operations
    get:
      description: "Get the status of a specific async operation. Returns 'pending',\
        \ 'completed', or 'failed'. Completed operations are removed from storage,\
        \ so 'completed' means the operation finished successfully."
      operationId: get_operation_status
      parameters:
      - explode: false
        in: path
        name: bank_id
        required: true
        schema:
          title: Bank Id
          type: string
        style: simple
      - explode: false
        in: path
        name: operation_id
        required: true
        schema:
          title: Operation Id
          type: string
        style: simple
      - explode: false
        in: header
        name: authorization
        required: false
        schema:
          nullable: true
          type: string
        style: simple
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationStatusResponse'
          description: Successful Response
        "422":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Get operation status
      tags:
      - Operations
  /v1/default/banks/{bank_id}/profile:
    get:
      description: Get disposition traits and mission for a memory bank. Auto-creates
        agent with defaults if not exists.
      operationId: get_bank_profile
      parameters:
      - explode: false
        in: path
        name: bank_id
        required: true
        schema:
          title: Bank Id
          type: string
        style: simple
      - explode: false
        in: header
        name: authorization
        required: false
        schema:
          nullable: true
          type: string
        style: simple
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankProfileResponse'
          description: Successful Response
        "422":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Get memory bank profile
      tags:
      - Banks
    put:
      description: "Update bank's disposition traits (skepticism, literalism, empathy)"
      operationId: update_bank_disposition
      parameters:
      - explode: false
        in: path
        name: bank_id
        required: true
        schema:
          title: Bank Id
          type: string
        style: simple
      - explode: false
        in: header
        name: authorization
        required: false
        schema:
          nullable: true
          type: string
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateDispositionRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankProfileResponse'
          description: Successful Response
        "422":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Update memory bank disposition
      tags:
      - Banks
  /v1/default/banks/{bank_id}/background:
    post:
      deprecated: true
      description: "Deprecated: Use PUT /mission instead. This endpoint now updates\
        \ the mission field."
      operationId: add_bank_background
      parameters:
      - explode: false
        in: path
        name: bank_id
        required: true
        schema:
          title: Bank Id
          type: string
        style: simple
      - explode: false
        in: header
        name: authorization
        required: false
        schema:
          nullable: true
          type: string
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddBackgroundRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BackgroundResponse'
          description: Successful Response
        "422":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Add/merge memory bank background (deprecated)
      tags:
      - Banks
  /v1/default/banks/{bank_id}:
    delete:
      description: "Delete an entire memory bank including all memories, entities,\
        \ documents, and the bank profile itself. This is a destructive operation\
        \ that cannot be undone."
      operationId: delete_bank
      parameters:
      - explode: false
        in: path
        name: bank_id
        required: true
        schema:
          title: Bank Id
          type: string
        style: simple
      - explode: false
        in: header
        name: authorization
        required: false
        schema:
          nullable: true
          type: string
        style: simple
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteResponse'
          description: Successful Response
        "422":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Delete memory bank
      tags:
      - Banks
    patch:
      description: Partially update an agent's profile. Only provided fields will
        be updated.
      operationId: update_bank
      parameters:
      - explode: false
        in: path
        name: bank_id
        required: true
        schema:
          title: Bank Id
          type: string
        style: simple
      - explode: false
        in: header
        name: authorization
        required: false
        schema:
          nullable: true
          type: string
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBankRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankProfileResponse'
          description: Successful Response
        "422":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Partial update memory bank
      tags:
      - Banks
    put:
      description: Create a new agent or update existing agent with disposition and
        mission. Auto-fills missing fields with defaults.
      operationId: create_or_update_bank
      parameters:
      - explode: false
        in: path
        name: bank_id
        required: true
        schema:
          title: Bank Id
          type: string
        style: simple
      - explode: false
        in: header
        name: authorization
        required: false
        schema:
          nullable: true
          type: string
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBankRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankProfileResponse'
          description: Successful Response
        "422":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Create or update memory bank
      tags:
      - Banks
  /v1/default/banks/{bank_id}/observations:
    delete:
      description: Delete all observations for a memory bank. This is useful for resetting
        the consolidated knowledge.
      operationId: clear_observations
      parameters:
      - explode: false
        in: path
        name: bank_id
        required: true
        schema:
          title: Bank Id
          type: string
        style: simple
      - explode: false
        in: header
        name: authorization
        required: false
        schema:
          nullable: true
          type: string
        style: simple
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteResponse'
          description: Successful Response
        "422":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Clear all observations
      tags:
      - Banks
  /v1/default/banks/{bank_id}/config:
    delete:
      description: Reset bank configuration to defaults by removing all bank-specific
        overrides. The bank will then use global and tenant-level configuration only.
      operationId: reset_bank_config
      parameters:
      - explode: false
        in: path
        name: bank_id
        required: true
        schema:
          title: Bank Id
          type: string
        style: simple
      - explode: false
        in: header
        name: authorization
        required: false
        schema:
          nullable: true
          type: string
        style: simple
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankConfigResponse'
          description: Successful Response
        "422":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Reset bank configuration
      tags:
      - Banks
    get:
      description: Get fully resolved configuration for a bank including all hierarchical
        overrides (global → tenant → bank). The 'config' field contains all resolved
        config values. The 'overrides' field shows only bank-specific overrides.
      operationId: get_bank_config
      parameters:
      - explode: false
        in: path
        name: bank_id
        required: true
        schema:
          title: Bank Id
          type: string
        style: simple
      - explode: false
        in: header
        name: authorization
        required: false
        schema:
          nullable: true
          type: string
        style: simple
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankConfigResponse'
          description: Successful Response
        "422":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Get bank configuration
      tags:
      - Banks
    patch:
      description: "Update configuration overrides for a bank. Only hierarchical fields\
        \ can be overridden (LLM settings, retention parameters, etc.). Keys can be\
        \ provided in Python field format (llm_provider) or environment variable format\
        \ (HINDSIGHT_API_LLM_PROVIDER)."
      operationId: update_bank_config
      parameters:
      - explode: false
        in: path
        name: bank_id
        required: true
        schema:
          title: Bank Id
          type: string
        style: simple
      - explode: false
        in: header
        name: authorization
        required: false
        schema:
          nullable: true
          type: string
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BankConfigUpdate'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankConfigResponse'
          description: Successful Response
        "422":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Update bank configuration
      tags:
      - Banks
  /v1/default/banks/{bank_id}/consolidate:
    post:
      description: Run memory consolidation to create/update observations from recent
        memories.
      operationId: trigger_consolidation
      parameters:
      - explode: false
        in: path
        name: bank_id
        required: true
        schema:
          title: Bank Id
          type: string
        style: simple
      - explode: false
        in: header
        name: authorization
        required: false
        schema:
          nullable: true
          type: string
        style: simple
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsolidationResponse'
          description: Successful Response
        "422":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Trigger consolidation
      tags:
      - Banks
  /v1/default/banks/{bank_id}/memories:
    delete:
      description: "Delete memory units for a memory bank. Optionally filter by type\
        \ (world, experience, opinion) to delete only specific types. This is a destructive\
        \ operation that cannot be undone. The bank profile (disposition and background)\
        \ will be preserved."
      operationId: clear_bank_memories
      parameters:
      - explode: false
        in: path
        name: bank_id
        required: true
        schema:
          title: Bank Id
          type: string
        style: simple
      - description: "Optional fact type filter (world, experience, opinion)"
        explode: true
        in: query
        name: type
        required: false
        schema:
          nullable: true
          type: string
        style: form
      - explode: false
        in: header
        name: authorization
        required: false
        schema:
          nullable: true
          type: string
        style: simple
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteResponse'
          description: Successful Response
        "422":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Clear memory bank memories
      tags:
      - Memory
    post:
      description: |-
        Retain memory items with automatic fact extraction.

        This is the main endpoint for storing memories. It supports both synchronous and asynchronous processing via the `async` parameter.

        **Features:**
        - Efficient batch processing
        - Automatic fact extraction from natural language
        - Entity recognition and linking
        - Document tracking with automatic upsert (when document_id is provided)
        - Temporal and semantic linking
        - Optional asynchronous processing

        **The system automatically:**
        1. Extracts semantic facts from the content
        2. Generates embeddings
        3. Deduplicates similar facts
        4. Creates temporal, semantic, and entity links
        5. Tracks document metadata

        **When `async=true`:** Returns immediately after queuing. Use the operations endpoint to monitor progress.

        **When `async=false` (default):** Waits for processing to complete.

        **Note:** If a memory item has a `document_id` that already exists, the old document and its memory units will be deleted before creating new ones (upsert behavior).        
      operationId: retain_memories
      parameters:
      - explode: false
        in: path
        name: bank_id
        required: true
        schema:
          title: Bank Id
          type: string
        style: simple
      - explode: false
        in: header
        name: authorization
        required: false
        schema:
          nullable: true
          type: string
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RetainRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetainResponse'
          description: Successful Response
        "422":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Retain memories
      tags:
      - Memory
components:
  schemas:
    AddBackgroundRequest:
      description: "Request model for adding/merging background information. Deprecated:\
        \ use SetMissionRequest instead."
      example:
        content: I was born in Texas
        update_disposition: true
      properties:
        content:
          description: New background information to add or merge
          title: Content
          type: string
        update_disposition:
          default: true
          description: Deprecated - disposition is no longer auto-inferred from mission
          title: Update Disposition
          type: boolean
      required:
      - content
      title: AddBackgroundRequest
    AsyncOperationSubmitResponse:
      description: Response model for submitting an async operation.
      example:
        operation_id: 550e8400-e29b-41d4-a716-446655440000
        status: queued
      properties:
        operation_id:
          title: Operation Id
          type: string
        status:
          title: Status
          type: string
      required:
      - operation_id
      - status
      title: AsyncOperationSubmitResponse
    BackgroundResponse:
      description: "Response model for background update. Deprecated: use MissionResponse\
        \ instead."
      example:
        mission: I was born in Texas. I am a software engineer with 10 years of experience.
      properties:
        mission:
          title: Mission
          type: string
        background:
          nullable: true
          type: string
        disposition:
          $ref: '#/components/schemas/DispositionTraits'
      required:
      - mission
      title: BackgroundResponse
    BankConfigResponse:
      description: Response model for bank configuration.
      example:
        bank_id: my-bank
        config:
          llm_model: gpt-4
          llm_provider: openai
          retain_extraction_mode: verbose
        overrides:
          llm_model: gpt-4
          retain_extraction_mode: verbose
      properties:
        bank_id:
          description: Bank identifier
          title: Bank Id
          type: string
        config:
          additionalProperties: {}
          description: Fully resolved configuration with all hierarchical overrides
            applied (Python field names)
          title: Config
        overrides:
          additionalProperties: {}
          description: Bank-specific configuration overrides only (Python field names)
          title: Overrides
      required:
      - bank_id
      - config
      - overrides
      title: BankConfigResponse
    BankConfigUpdate:
      description: Request model for updating bank configuration.
      example:
        updates:
          llm_model: claude-sonnet-4-5
          retain_custom_instructions: Extract technical details carefully
          retain_extraction_mode: verbose
      properties:
        updates:
          additionalProperties: {}
          description: Configuration overrides. Keys can be in Python field format
            (llm_provider) or environment variable format (HINDSIGHT_API_LLM_PROVIDER).
            Only hierarchical fields can be overridden per-bank.
          title: Updates
      required:
      - updates
      title: BankConfigUpdate
    BankListItem:
      description: Bank list item with profile summary.
      properties:
        bank_id:
          title: Bank Id
          type: string
        name:
          nullable: true
          type: string
        disposition:
          $ref: '#/components/schemas/DispositionTraits'
        mission:
          nullable: true
          type: string
        created_at:
          nullable: true
          type: string
        updated_at:
          nullable: true
          type: string
      required:
      - bank_id
      - disposition
      title: BankListItem
    BankListResponse:
      description: Response model for listing all banks.
      example:
        banks:
        - bank_id: user123
          created_at: 2024-01-15T10:30:00Z
          disposition:
            empathy: 3
            literalism: 3
            skepticism: 3
          mission: I am a software engineer helping my team ship quality code
          name: Alice
          updated_at: 2024-01-16T14:20:00Z
      properties:
        banks:
          items:
            $ref: '#/components/schemas/BankListItem'
          type: array
      required:
      - banks
      title: BankListResponse
    BankProfileResponse:
      description: Response model for bank profile.
      example:
        bank_id: user123
        disposition:
          empathy: 3
          literalism: 3
          skepticism: 3
        mission: I am a software engineer helping my team stay organized and ship
          quality code
        name: Alice
      properties:
        bank_id:
          title: Bank Id
          type: string
        name:
          title: Name
          type: string
        disposition:
          $ref: '#/components/schemas/DispositionTraits'
        mission:
          description: The agent's mission - who they are and what they're trying
            to accomplish
          title: Mission
          type: string
        background:
          nullable: true
          type: string
      required:
      - bank_id
      - disposition
      - mission
      - name
      title: BankProfileResponse
    BankStatsResponse:
      description: Response model for bank statistics endpoint.
      example:
        bank_id: user123
        failed_operations: 0
        last_consolidated_at: 2024-01-15T10:30:00Z
        links_breakdown:
          fact:
            entity: 40
            semantic: 60
            temporal: 100
        links_by_fact_type:
          fact: 200
          observation: 40
          preference: 60
        links_by_link_type:
          entity: 50
          semantic: 100
          temporal: 150
        nodes_by_fact_type:
          fact: 100
          observation: 20
          preference: 30
        pending_consolidation: 0
        pending_operations: 2
        total_documents: 10
        total_links: 300
        total_nodes: 150
        total_observations: 45
      properties:
        bank_id:
          title: Bank Id
          type: string
        total_nodes:
          title: Total Nodes
          type: integer
        total_links:
          title: Total Links
          type: integer
        total_documents:
          title: Total Documents
          type: integer
        nodes_by_fact_type:
          additionalProperties:
            type: integer
          title: Nodes By Fact Type
        links_by_link_type:
          additionalProperties:
            type: integer
          title: Links By Link Type
        links_by_fact_type:
          additionalProperties:
            type: integer
          title: Links By Fact Type
        links_breakdown:
          additionalProperties:
            additionalProperties:
              type: integer
          title: Links Breakdown
        pending_operations:
          title: Pending Operations
          type: integer
        failed_operations:
          title: Failed Operations
          type: integer
        last_consolidated_at:
          nullable: true
          type: string
        pending_consolidation:
          default: 0
          description: Number of memories not yet processed into observations
          title: Pending Consolidation
          type: integer
        total_observations:
          default: 0
          description: Total number of observations
          title: Total Observations
          type: integer
      required:
      - bank_id
      - failed_operations
      - links_breakdown
      - links_by_fact_type
      - links_by_link_type
      - nodes_by_fact_type
      - pending_operations
      - total_documents
      - total_links
      - total_nodes
      title: BankStatsResponse
    Budget:
      description: Budget levels for recall/reflect operations.
      enum:
      - low
      - mid
      - high
      title: Budget
      type: string
    CancelOperationResponse:
      description: Response model for cancel operation endpoint.
      example:
        message: Operation 550e8400-e29b-41d4-a716-446655440000 cancelled
        operation_id: 550e8400-e29b-41d4-a716-446655440000
        success: true
      properties:
        success:
          title: Success
          type: boolean
        message:
          title: Message
          type: string
        operation_id:
          title: Operation Id
          type: string
      required:
      - message
      - operation_id
      - success
      title: CancelOperationResponse
    ChildOperationStatus:
      description: Status of a child operation (for batch operations).
      properties:
        operation_id:
          title: Operation Id
          type: string
        status:
          title: Status
          type: string
        sub_batch_index:
          nullable: true
          type: integer
        items_count:
          nullable: true
          type: integer
        error_message:
          nullable: true
          type: string
      required:
      - operation_id
      - status
      title: ChildOperationStatus
    ChunkData:
      description: Chunk data for a single chunk.
      properties:
        id:
          title: Id
          type: string
        text:
          title: Text
          type: string
        chunk_index:
          title: Chunk Index
          type: integer
        truncated:
          default: false
          description: Whether the chunk text was truncated due to token limits
          title: Truncated
          type: boolean
      required:
      - chunk_index
      - id
      - text
      title: ChunkData
    ChunkIncludeOptions:
      description: Options for including chunks in recall results.
      properties:
        max_tokens:
          default: 8192
          description: Maximum tokens for chunks (chunks may be truncated)
          title: Max Tokens
          type: integer
      title: ChunkIncludeOptions
    ChunkResponse:
      description: Response model for get chunk endpoint.
      example:
        bank_id: user123
        chunk_id: user123_session_1_0
        chunk_index: 0
        chunk_text: This is the first chunk of the document...
        created_at: 2024-01-15T10:30:00Z
        document_id: session_1
      properties:
        chunk_id:
          title: Chunk Id
          type: string
        document_id:
          title: Document Id
          type: string
        bank_id:
          title: Bank Id
          type: string
        chunk_index:
          title: Chunk Index
          type: integer
        chunk_text:
          title: Chunk Text
          type: string
        created_at:
          title: Created At
          type: string
      required:
      - bank_id
      - chunk_id
      - chunk_index
      - chunk_text
      - created_at
      - document_id
      title: ChunkResponse
    ConsolidationResponse:
      description: Response model for consolidation trigger endpoint.
      example:
        deduplicated: false
        operation_id: operation_id
      properties:
        operation_id:
          description: ID of the async consolidation operation
          title: Operation Id
          type: string
        deduplicated:
          default: false
          description: True if an existing pending task was reused
          title: Deduplicated
          type: boolean
      required:
      - operation_id
      title: ConsolidationResponse
    CreateBankRequest:
      description: Request model for creating/updating a bank.
      example:
        disposition:
          empathy: 3
          literalism: 3
          skepticism: 3
        mission: I am a PM helping my engineering team stay organized
        name: Alice
      properties:
        name:
          nullable: true
          type: string
        disposition:
          $ref: '#/components/schemas/DispositionTraits'
        mission:
          nullable: true
          type: string
        background:
          nullable: true
          type: string
      title: CreateBankRequest
    CreateDirectiveRequest:
      description: Request model for creating a directive.
      example:
        is_active: true
        name: name
        priority: 0
        content: content
        tags:
        - tags
        - tags
      properties:
        name:
          description: Human-readable name for the directive
          title: Name
          type: string
        content:
          description: The directive text to inject into prompts
          title: Content
          type: string
        priority:
          default: 0
          description: Higher priority directives are injected first
          title: Priority
          type: integer
        is_active:
          default: true
          description: Whether this directive is active
          title: Is Active
          type: boolean
        tags:
          default: []
          description: Tags for filtering
          items:
            type: string
          type: array
      required:
      - content
      - name
      title: CreateDirectiveRequest
    CreateMentalModelRequest:
      description: Request model for creating a mental model.
      example:
        id: team-communication
        max_tokens: 2048
        name: Team Communication Preferences
        source_query: How does the team prefer to communicate?
        tags:
        - team
        trigger:
          refresh_after_consolidation: false
      properties:
        id:
          nullable: true
          type: string
        name:
          description: Human-readable name for the mental model
          title: Name
          type: string
        source_query:
          description: The query to run to generate content
          title: Source Query
          type: string
        tags:
          default: []
          description: Tags for scoped visibility
          items:
            type: string
          type: array
        max_tokens:
          default: 2048
          description: Maximum tokens for generated content
          maximum: 8192.0
          minimum: 256.0
          title: Max Tokens
          type: integer
        trigger:
          $ref: '#/components/schemas/MentalModelTrigger'
      required:
      - name
      - source_query
      title: CreateMentalModelRequest
    CreateMentalModelResponse:
      description: Response model for mental model creation.
      example:
        operation_id: operation_id
        mental_model_id: mental_model_id
      properties:
        mental_model_id:
          nullable: true
          type: string
        operation_id:
          description: Operation ID to track refresh progress
          title: Operation Id
          type: string
      required:
      - operation_id
      title: CreateMentalModelResponse
    DeleteDocumentResponse:
      description: Response model for delete document endpoint.
      example:
        document_id: session_1
        memory_units_deleted: 5
        message: Document 'session_1' and 5 associated memory units deleted successfully
        success: true
      properties:
        success:
          title: Success
          type: boolean
        message:
          title: Message
          type: string
        document_id:
          title: Document Id
          type: string
        memory_units_deleted:
          title: Memory Units Deleted
          type: integer
      required:
      - document_id
      - memory_units_deleted
      - message
      - success
      title: DeleteDocumentResponse
    DeleteResponse:
      description: Response model for delete operations.
      example:
        deleted_count: 10
        message: Deleted successfully
        success: true
      properties:
        success:
          title: Success
          type: boolean
        message:
          nullable: true
          type: string
        deleted_count:
          nullable: true
          type: integer
      required:
      - success
      title: DeleteResponse
    DirectiveListResponse:
      description: Response model for listing directives.
      example:
        items:
        - is_active: true
          updated_at: updated_at
          bank_id: bank_id
          name: name
          created_at: created_at
          id: id
          priority: 0
          content: content
          tags:
          - tags
          - tags
        - is_active: true
          updated_at: updated_at
          bank_id: bank_id
          name: name
          created_at: created_at
          id: id
          priority: 0
          content: content
          tags:
          - tags
          - tags
      properties:
        items:
          items:
            $ref: '#/components/schemas/DirectiveResponse'
          type: array
      required:
      - items
      title: DirectiveListResponse
    DirectiveResponse:
      description: Response model for a directive.
      example:
        is_active: true
        updated_at: updated_at
        bank_id: bank_id
        name: name
        created_at: created_at
        id: id
        priority: 0
        content: content
        tags:
        - tags
        - tags
      properties:
        id:
          title: Id
          type: string
        bank_id:
          title: Bank Id
          type: string
        name:
          title: Name
          type: string
        content:
          title: Content
          type: string
        priority:
          default: 0
          title: Priority
          type: integer
        is_active:
          default: true
          title: Is Active
          type: boolean
        tags:
          default: []
          items:
            type: string
          type: array
        created_at:
          nullable: true
          type: string
        updated_at:
          nullable: true
          type: string
      required:
      - bank_id
      - content
      - id
      - name
      title: DirectiveResponse
    DispositionTraits:
      description: Disposition traits that influence how memories are formed and interpreted.
      example:
        empathy: 3
        literalism: 3
        skepticism: 3
      properties:
        skepticism:
          description: "How skeptical vs trusting (1=trusting, 5=skeptical)"
          maximum: 5.0
          minimum: 1.0
          title: Skepticism
          type: integer
        literalism:
          description: "How literally to interpret information (1=flexible, 5=literal)"
          maximum: 5.0
          minimum: 1.0
          title: Literalism
          type: integer
        empathy:
          description: "How much to consider emotional context (1=detached, 5=empathetic)"
          maximum: 5.0
          minimum: 1.0
          title: Empathy
          type: integer
      required:
      - empathy
      - literalism
      - skepticism
      title: DispositionTraits
    DocumentResponse:
      description: Response model for get document endpoint.
      example:
        bank_id: user123
        content_hash: abc123
        created_at: 2024-01-15T10:30:00Z
        id: session_1
        memory_unit_count: 15
        original_text: Full document text here...
        tags:
        - user_a
        - session_123
        updated_at: 2024-01-15T10:30:00Z
      properties:
        id:
          title: Id
          type: string
        bank_id:
          title: Bank Id
          type: string
        original_text:
          title: Original Text
          type: string
        content_hash:
          nullable: true
          type: string
        created_at:
          title: Created At
          type: string
        updated_at:
          title: Updated At
          type: string
        memory_unit_count:
          title: Memory Unit Count
          type: integer
        tags:
          default: []
          description: Tags associated with this document
          items:
            type: string
          type: array
      required:
      - bank_id
      - content_hash
      - created_at
      - id
      - memory_unit_count
      - original_text
      - updated_at
      title: DocumentResponse
    EntityDetailResponse:
      description: Response model for entity detail endpoint.
      example:
        canonical_name: John
        first_seen: 2024-01-15T10:30:00Z
        id: 123e4567-e89b-12d3-a456-426614174000
        last_seen: 2024-02-01T14:00:00Z
        mention_count: 15
        observations:
        - mentioned_at: 2024-01-15T10:30:00Z
          text: John works at Google
      properties:
        id:
          title: Id
          type: string
        canonical_name:
          title: Canonical Name
          type: string
        mention_count:
          title: Mention Count
          type: integer
        first_seen:
          nullable: true
          type: string
        last_seen:
          nullable: true
          type: string
        metadata:
          additionalProperties: {}
          nullable: true
        observations:
          items:
            $ref: '#/components/schemas/EntityObservationResponse'
          type: array
      required:
      - canonical_name
      - id
      - mention_count
      - observations
      title: EntityDetailResponse
    EntityIncludeOptions:
      description: Options for including entity observations in recall results.
      properties:
        max_tokens:
          default: 500
          description: Maximum tokens for entity observations
          title: Max Tokens
          type: integer
      title: EntityIncludeOptions
    EntityInput:
      description: Entity to associate with retained content.
      properties:
        text:
          description: The entity name/text
          title: Text
          type: string
        type:
          nullable: true
          type: string
      required:
      - text
      title: EntityInput
    EntityListItem:
      description: Entity list item with summary.
      example:
        canonical_name: John
        first_seen: 2024-01-15T10:30:00Z
        id: 123e4567-e89b-12d3-a456-426614174000
        last_seen: 2024-02-01T14:00:00Z
        mention_count: 15
      properties:
        id:
          title: Id
          type: string
        canonical_name:
          title: Canonical Name
          type: string
        mention_count:
          title: Mention Count
          type: integer
        first_seen:
          nullable: true
          type: string
        last_seen:
          nullable: true
          type: string
        metadata:
          additionalProperties: {}
          nullable: true
      required:
      - canonical_name
      - id
      - mention_count
      title: EntityListItem
    EntityListResponse:
      description: Response model for entity list endpoint.
      example:
        items:
        - canonical_name: John
          first_seen: 2024-01-15T10:30:00Z
          id: 123e4567-e89b-12d3-a456-426614174000
          last_seen: 2024-02-01T14:00:00Z
          mention_count: 15
        limit: 100
        offset: 0
        total: 150
      properties:
        items:
          items:
            $ref: '#/components/schemas/EntityListItem'
          type: array
        total:
          title: Total
          type: integer
        limit:
          title: Limit
          type: integer
        offset:
          title: Offset
          type: integer
      required:
      - items
      - limit
      - offset
      - total
      title: EntityListResponse
    EntityObservationResponse:
      description: An observation about an entity.
      properties:
        text:
          title: Text
          type: string
        mentioned_at:
          nullable: true
          type: string
      required:
      - text
      title: EntityObservationResponse
    EntityStateResponse:
      description: Current mental model of an entity.
      properties:
        entity_id:
          title: Entity Id
          type: string
        canonical_name:
          title: Canonical Name
          type: string
        observations:
          items:
            $ref: '#/components/schemas/EntityObservationResponse'
          type: array
      required:
      - canonical_name
      - entity_id
      - observations
      title: EntityStateResponse
    FactsIncludeOptions:
      description: Options for including facts (based_on) in reflect results.
      properties: {}
      title: FactsIncludeOptions
      type: object
    FeaturesInfo:
      description: Feature flags indicating which capabilities are enabled.
      properties:
        observations:
          description: Whether observations (auto-consolidation) are enabled
          title: Observations
          type: boolean
        mcp:
          description: Whether MCP (Model Context Protocol) server is enabled
          title: Mcp
          type: boolean
        worker:
          description: Whether the background worker is enabled
          title: Worker
          type: boolean
        bank_config_api:
          description: Whether per-bank configuration API is enabled
          title: Bank Config Api
          type: boolean
      required:
      - bank_config_api
      - mcp
      - observations
      - worker
      title: FeaturesInfo
    GraphDataResponse:
      description: Response model for graph data endpoint.
      example:
        edges:
        - from: "1"
          to: "2"
          type: semantic
          weight: 0.8
        limit: 1000
        nodes:
        - id: "1"
          label: Alice works at Google
          type: world
        - id: "2"
          label: Bob went hiking
          type: world
        table_rows:
        - context: Work info
          date: 2024-01-15 10:30
          entities: "Alice (PERSON), Google (ORGANIZATION)"
          id: abc12345...
          text: Alice works at Google
        total_units: 2
      properties:
        nodes:
          items:
            additionalProperties: {}
          type: array
        edges:
          items:
            additionalProperties: {}
          type: array
        table_rows:
          items:
            additionalProperties: {}
          type: array
        total_units:
          title: Total Units
          type: integer
        limit:
          title: Limit
          type: integer
      required:
      - edges
      - limit
      - nodes
      - table_rows
      - total_units
      title: GraphDataResponse
    HTTPValidationError:
      example:
        detail:
        - msg: msg
          loc:
          - ValidationError_loc_inner
          - ValidationError_loc_inner
          type: type
        - msg: msg
          loc:
          - ValidationError_loc_inner
          - ValidationError_loc_inner
          type: type
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
      title: HTTPValidationError
    IncludeOptions:
      description: Options for including additional data in recall results.
      properties:
        entities:
          $ref: '#/components/schemas/EntityIncludeOptions'
        chunks:
          $ref: '#/components/schemas/ChunkIncludeOptions'
      title: IncludeOptions
    ListDocumentsResponse:
      description: Response model for list documents endpoint.
      example:
        items:
        - bank_id: user123
          content_hash: abc123
          created_at: 2024-01-15T10:30:00Z
          id: session_1
          memory_unit_count: 15
          tags:
          - user_a
          - session_123
          text_length: 5420
          updated_at: 2024-01-15T10:30:00Z
        limit: 100
        offset: 0
        total: 50
      properties:
        items:
          items:
            additionalProperties: {}
          type: array
        total:
          title: Total
          type: integer
        limit:
          title: Limit
          type: integer
        offset:
          title: Offset
          type: integer
      required:
      - items
      - limit
      - offset
      - total
      title: ListDocumentsResponse
    ListMemoryUnitsResponse:
      description: Response model for list memory units endpoint.
      example:
        items:
        - context: Work conversation
          date: 2024-01-15T10:30:00Z
          entities: "Alice (PERSON), Google (ORGANIZATION)"
          id: 550e8400-e29b-41d4-a716-446655440000
          text: Alice works at Google on the AI team
          type: world
        limit: 100
        offset: 0
        total: 150
      properties:
        items:
          items:
            additionalProperties: {}
          type: array
        total:
          title: Total
          type: integer
        limit:
          title: Limit
          type: integer
        offset:
          title: Offset
          type: integer
      required:
      - items
      - limit
      - offset
      - total
      title: ListMemoryUnitsResponse
    ListTagsResponse:
      description: Response model for list tags endpoint.
      example:
        items:
        - count: 42
          tag: user:alice
        - count: 15
          tag: user:bob
        - count: 8
          tag: session:abc123
        limit: 100
        offset: 0
        total: 25
      properties:
        items:
          items:
            $ref: '#/components/schemas/TagItem'
          type: array
        total:
          title: Total
          type: integer
        limit:
          title: Limit
          type: integer
        offset:
          title: Offset
          type: integer
      required:
      - items
      - limit
      - offset
      - total
      title: ListTagsResponse
    MemoryItem:
      description: Single memory item for retain.
      example:
        content: Alice mentioned she's working on a new ML model
        context: team meeting
        document_id: meeting_notes_2024_01_15
        entities:
        - text: Alice
        - text: ML model
          type: CONCEPT
        metadata:
          channel: engineering
          source: slack
        tags:
        - user_a
        - user_b
        timestamp: 2024-01-15T10:30:00Z
      properties:
        content:
          title: Content
          type: string
        timestamp:
          format: date-time
          nullable: true
          type: string
        context:
          nullable: true
          type: string
        metadata:
          additionalProperties:
            type: string
          nullable: true
        document_id:
          nullable: true
          type: string
        entities:
          items:
            $ref: '#/components/schemas/EntityInput'
          nullable: true
          type: array
        tags:
          items:
            type: string
          nullable: true
          type: array
      required:
      - content
      title: MemoryItem
    MentalModelListResponse:
      description: Response model for listing mental models.
      example:
        items:
        - source_query: source_query
          max_tokens: 0
          bank_id: bank_id
          reflect_response:
            key: ""
          name: name
          created_at: created_at
          id: id
          trigger:
            refresh_after_consolidation: false
          last_refreshed_at: last_refreshed_at
          content: content
          tags:
          - tags
          - tags
        - source_query: source_query
          max_tokens: 0
          bank_id: bank_id
          reflect_response:
            key: ""
          name: name
          created_at: created_at
          id: id
          trigger:
            refresh_after_consolidation: false
          last_refreshed_at: last_refreshed_at
          content: content
          tags:
          - tags
          - tags
      properties:
        items:
          items:
            $ref: '#/components/schemas/MentalModelResponse'
          type: array
      required:
      - items
      title: MentalModelListResponse
    MentalModelResponse:
      description: Response model for a mental model (stored reflect response).
      example:
        source_query: source_query
        max_tokens: 0
        bank_id: bank_id
        reflect_response:
          key: ""
        name: name
        created_at: created_at
        id: id
        trigger:
          refresh_after_consolidation: false
        last_refreshed_at: last_refreshed_at
        content: content
        tags:
        - tags
        - tags
      properties:
        id:
          title: Id
          type: string
        bank_id:
          title: Bank Id
          type: string
        name:
          title: Name
          type: string
        source_query:
          title: Source Query
          type: string
        content:
          description: The mental model content as well-formatted markdown (auto-generated
            from reflect endpoint)
          title: Content
          type: string
        tags:
          default: []
          items:
            type: string
          type: array
        max_tokens:
          default: 2048
          title: Max Tokens
          type: integer
        trigger:
          $ref: '#/components/schemas/MentalModelTrigger'
        last_refreshed_at:
          nullable: true
          type: string
        created_at:
          nullable: true
          type: string
        reflect_response:
          additionalProperties: {}
          nullable: true
      required:
      - bank_id
      - content
      - id
      - name
      - source_query
      title: MentalModelResponse
    MentalModelTrigger:
      description: Trigger settings for a mental model.
      example:
        refresh_after_consolidation: false
      properties:
        refresh_after_consolidation:
          default: false
          description: "If true, refresh this mental model after observations consolidation\
            \ (real-time mode)"
          title: Refresh After Consolidation
          type: boolean
      title: MentalModelTrigger
    OperationResponse:
      description: Response model for a single async operation.
      example:
        created_at: 2024-01-15T10:30:00Z
        id: 550e8400-e29b-41d4-a716-446655440000
        items_count: 5
        status: pending
        task_type: retain
      properties:
        id:
          title: Id
          type: string
        task_type:
          title: Task Type
          type: string
        items_count:
          title: Items Count
          type: integer
        document_id:
          nullable: true
          type: string
        created_at:
          title: Created At
          type: string
        status:
          title: Status
          type: string
        error_message:
          nullable: true
          type: string
      required:
      - created_at
      - error_message
      - id
      - items_count
      - status
      - task_type
      title: OperationResponse
    OperationStatusResponse:
      description: Response model for getting a single operation status.
      example:
        completed_at: 2024-01-15T10:31:30Z
        created_at: 2024-01-15T10:30:00Z
        operation_id: 550e8400-e29b-41d4-a716-446655440000
        operation_type: refresh_mental_models
        status: completed
        updated_at: 2024-01-15T10:31:30Z
      properties:
        operation_id:
          title: Operation Id
          type: string
        status:
          enum:
          - pending
          - completed
          - failed
          - not_found
          title: Status
          type: string
        operation_type:
          nullable: true
          type: string
        created_at:
          nullable: true
          type: string
        updated_at:
          nullable: true
          type: string
        completed_at:
          nullable: true
          type: string
        error_message:
          nullable: true
          type: string
        result_metadata:
          additionalProperties: {}
          nullable: true
        child_operations:
          items:
            $ref: '#/components/schemas/ChildOperationStatus'
          nullable: true
          type: array
      required:
      - operation_id
      - status
      title: OperationStatusResponse
    OperationsListResponse:
      description: Response model for list operations endpoint.
      example:
        bank_id: user123
        limit: 20
        offset: 0
        operations:
        - created_at: 2024-01-15T10:30:00Z
          id: 550e8400-e29b-41d4-a716-446655440000
          status: pending
          task_type: retain
        total: 150
      properties:
        bank_id:
          title: Bank Id
          type: string
        total:
          title: Total
          type: integer
        limit:
          title: Limit
          type: integer
        offset:
          title: Offset
          type: integer
        operations:
          items:
            $ref: '#/components/schemas/OperationResponse'
          type: array
      required:
      - bank_id
      - limit
      - offset
      - operations
      - total
      title: OperationsListResponse
    RecallRequest:
      description: Request model for recall endpoint.
      example:
        budget: mid
        include:
          entities:
            max_tokens: 500
        max_tokens: 4096
        query: What did Alice say about machine learning?
        query_timestamp: 2023-05-30T23:40:00
        tags:
        - user_a
        tags_match: any
        trace: true
        types:
        - world
        - experience
      properties:
        query:
          title: Query
          type: string
        types:
          items:
            type: string
          nullable: true
          type: array
        budget:
          $ref: '#/components/schemas/Budget'
        max_tokens:
          default: 4096
          title: Max Tokens
          type: integer
        trace:
          default: false
          title: Trace
          type: boolean
        query_timestamp:
          nullable: true
          type: string
        include:
          $ref: '#/components/schemas/IncludeOptions'
        tags:
          items:
            type: string
          nullable: true
          type: array
        tags_match:
          default: any
          description: "How to match tags: 'any' (OR, includes untagged), 'all' (AND,\
            \ includes untagged), 'any_strict' (OR, excludes untagged), 'all_strict'\
            \ (AND, excludes untagged)."
          enum:
          - any
          - all
          - any_strict
          - all_strict
          title: Tags Match
          type: string
      required:
      - query
      title: RecallRequest
    RecallResponse:
      description: Response model for recall endpoints.
      example:
        chunks:
          "456e7890-e12b-34d5-a678-901234567890":
            chunk_index: 0
            id: 456e7890-e12b-34d5-a678-901234567890
            text: Alice works at Google on the AI team. She's been there for 3 years...
        entities:
          Alice:
            canonical_name: Alice
            entity_id: 123e4567-e89b-12d3-a456-426614174001
            observations:
            - mentioned_at: 2024-01-15T10:30:00Z
              text: Alice works at Google on the AI team
        results:
        - chunk_id: 456e7890-e12b-34d5-a678-901234567890
          context: work info
          entities:
          - Alice
          - Google
          id: 123e4567-e89b-12d3-a456-426614174000
          occurred_end: 2024-01-15T10:30:00Z
          occurred_start: 2024-01-15T10:30:00Z
          text: Alice works at Google on the AI team
          type: world
        trace:
          num_results: 1
          query: What did Alice say about machine learning?
          time_seconds: 0.123
      properties:
        results:
          items:
            $ref: '#/components/schemas/RecallResult'
          type: array
        trace:
          additionalProperties: {}
          nullable: true
        entities:
          additionalProperties:
            $ref: '#/components/schemas/EntityStateResponse'
          nullable: true
        chunks:
          additionalProperties:
            $ref: '#/components/schemas/ChunkData'
          nullable: true
      required:
      - results
      title: RecallResponse
    RecallResult:
      description: Single recall result item.
      example:
        chunk_id: 456e7890-e12b-34d5-a678-901234567890
        context: work info
        document_id: session_abc123
        entities:
        - Alice
        - Google
        id: 123e4567-e89b-12d3-a456-426614174000
        mentioned_at: 2024-01-15T10:30:00Z
        metadata:
          source: slack
        occurred_end: 2024-01-15T10:30:00Z
        occurred_start: 2024-01-15T10:30:00Z
        tags:
        - user_a
        - user_b
        text: Alice works at Google on the AI team
        type: world
      properties:
        id:
          title: Id
          type: string
        text:
          title: Text
          type: string
        type:
          nullable: true
          type: string
        entities:
          items:
            type: string
          nullable: true
          type: array
        context:
          nullable: true
          type: string
        occurred_start:
          nullable: true
          type: string
        occurred_end:
          nullable: true
          type: string
        mentioned_at:
          nullable: true
          type: string
        document_id:
          nullable: true
          type: string
        metadata:
          additionalProperties:
            type: string
          nullable: true
        chunk_id:
          nullable: true
          type: string
        tags:
          items:
            type: string
          nullable: true
          type: array
      required:
      - id
      - text
      title: RecallResult
    ReflectBasedOn:
      description: "Evidence the response is based on: memories, mental models, and\
        \ directives."
      properties:
        memories:
          default: []
          description: Memory facts used to generate the response
          items:
            $ref: '#/components/schemas/ReflectFact'
          type: array
        mental_models:
          default: []
          description: Mental models used during reflection
          items:
            $ref: '#/components/schemas/ReflectMentalModel'
          type: array
        directives:
          default: []
          description: Directives applied during reflection
          items:
            $ref: '#/components/schemas/ReflectDirective'
          type: array
      title: ReflectBasedOn
    ReflectDirective:
      description: A directive applied during reflect.
      properties:
        id:
          description: Directive ID
          title: Id
          type: string
        name:
          description: Directive name
          title: Name
          type: string
        content:
          description: Directive content
          title: Content
          type: string
      required:
      - content
      - id
      - name
      title: ReflectDirective
    ReflectFact:
      description: A fact used in think response.
      example:
        context: healthcare discussion
        id: 123e4567-e89b-12d3-a456-426614174000
        occurred_end: 2024-01-15T10:30:00Z
        occurred_start: 2024-01-15T10:30:00Z
        text: AI is used in healthcare
        type: world
      properties:
        id:
          nullable: true
          type: string
        text:
          description: "Fact text. When type='observation', this contains markdown-formatted\
            \ consolidated knowledge"
          title: Text
          type: string
        type:
          nullable: true
          type: string
        context:
          nullable: true
          type: string
        occurred_start:
          nullable: true
          type: string
        occurred_end:
          nullable: true
          type: string
      required:
      - text
      title: ReflectFact
    ReflectIncludeOptions:
      description: Options for including additional data in reflect results.
      properties:
        facts:
          description: Options for including facts (based_on) in reflect results.
          properties: {}
          title: FactsIncludeOptions
          type: object
        tool_calls:
          $ref: '#/components/schemas/ToolCallsIncludeOptions'
      title: ReflectIncludeOptions
    ReflectLLMCall:
      description: An LLM call made during reflect agent execution.
      properties:
        scope:
          description: "Call scope: agent_1, agent_2, final, etc."
          title: Scope
          type: string
        duration_ms:
          description: Execution time in milliseconds
          title: Duration Ms
          type: integer
      required:
      - duration_ms
      - scope
      title: ReflectLLMCall
    ReflectMentalModel:
      description: A mental model used during reflect.
      properties:
        id:
          description: Mental model ID
          title: Id
          type: string
        text:
          description: Mental model content
          title: Text
          type: string
        context:
          nullable: true
          type: string
      required:
      - id
      - text
      title: ReflectMentalModel
    ReflectRequest:
      description: Request model for reflect endpoint.
      example:
        budget: low
        include:
          facts: {}
        max_tokens: 4096
        query: What do you think about artificial intelligence?
        response_schema:
          properties:
            summary:
              type: string
            key_points:
              items:
                type: string
              type: array
          required:
          - summary
          - key_points
          type: object
        tags:
        - user_a
        tags_match: any
      properties:
        query:
          title: Query
          type: string
        budget:
          $ref: '#/components/schemas/Budget'
        context:
          nullable: true
          type: string
        max_tokens:
          default: 4096
          description: Maximum tokens for the response
          title: Max Tokens
          type: integer
        include:
          $ref: '#/components/schemas/ReflectIncludeOptions'
        response_schema:
          additionalProperties: {}
          nullable: true
        tags:
          items:
            type: string
          nullable: true
          type: array
        tags_match:
          default: any
          description: "How to match tags: 'any' (OR, includes untagged), 'all' (AND,\
            \ includes untagged), 'any_strict' (OR, excludes untagged), 'all_strict'\
            \ (AND, excludes untagged)."
          enum:
          - any
          - all
          - any_strict
          - all_strict
          title: Tags Match
          type: string
      required:
      - query
      title: ReflectRequest
    ReflectResponse:
      description: Response model for think endpoint.
      example:
        based_on:
          memories:
          - id: "123"
            text: AI is used in healthcare
            type: world
          - id: "456"
            text: I discussed AI applications last week
            type: experience
        structured_output:
          key_points:
          - Used in healthcare
          - Discussed recently
          summary: AI is transformative
        text: |-
          ## AI Overview

          Based on my understanding, AI is a **transformative technology**:

          - Used extensively in healthcare
          - Discussed in recent conversations
          - Continues to evolve rapidly          
        trace:
          llm_calls:
          - duration_ms: 1200
            scope: agent_1
          observations:
          - id: obs-1
            name: AI Technology
            subtype: structural
            type: concept
          tool_calls:
          - duration_ms: 150
            input:
              query: AI
            tool: recall
        usage:
          input_tokens: 1500
          output_tokens: 500
          total_tokens: 2000
      properties:
        text:
          description: "The reflect response as well-formatted markdown (headers,\
            \ lists, bold/italic, code blocks, etc.)"
          title: Text
          type: string
        based_on:
          $ref: '#/components/schemas/ReflectBasedOn'
        structured_output:
          additionalProperties: {}
          nullable: true
        usage:
          $ref: '#/components/schemas/TokenUsage'
        trace:
          $ref: '#/components/schemas/ReflectTrace'
      required:
      - text
      title: ReflectResponse
    ReflectToolCall:
      description: A tool call made during reflect agent execution.
      properties:
        tool:
          description: "Tool name: lookup, recall, learn, expand"
          title: Tool
          type: string
        input:
          additionalProperties: {}
          description: Tool input parameters
          title: Input
        output:
          additionalProperties: {}
          nullable: true
        duration_ms:
          description: Execution time in milliseconds
          title: Duration Ms
          type: integer
        iteration:
          default: 0
          description: Iteration number (1-based) when this tool was called
          title: Iteration
          type: integer
      required:
      - duration_ms
      - input
      - tool
      title: ReflectToolCall
    ReflectTrace:
      description: Execution trace of LLM and tool calls during reflection.
      properties:
        tool_calls:
          default: []
          description: Tool calls made during reflection
          items:
            $ref: '#/components/schemas/ReflectToolCall'
          type: array
        llm_calls:
          default: []
          description: LLM calls made during reflection
          items:
            $ref: '#/components/schemas/ReflectLLMCall'
          type: array
      title: ReflectTrace
    RetainRequest:
      description: Request model for retain endpoint.
      example:
        async: false
        document_tags:
        - user_a
        - user_b
        items:
        - content: Alice works at Google
          context: work
          document_id: conversation_123
        - content: Bob went hiking yesterday
          document_id: conversation_123
          timestamp: 2024-01-15T10:00:00Z
      properties:
        items:
          items:
            $ref: '#/components/schemas/MemoryItem'
          type: array
        async:
          default: false
          description: "If true, process asynchronously in background. If false, wait\
            \ for completion (default: false)"
          title: Async
          type: boolean
        document_tags:
          items:
            type: string
          nullable: true
          type: array
      required:
      - items
      title: RetainRequest
    RetainResponse:
      description: Response model for retain endpoint.
      example:
        async: false
        bank_id: user123
        items_count: 2
        success: true
        usage:
          input_tokens: 500
          output_tokens: 100
          total_tokens: 600
      properties:
        success:
          title: Success
          type: boolean
        bank_id:
          title: Bank Id
          type: string
        items_count:
          title: Items Count
          type: integer
        async:
          description: Whether the operation was processed asynchronously
          title: Async
          type: boolean
        operation_id:
          nullable: true
          type: string
        usage:
          $ref: '#/components/schemas/TokenUsage'
      required:
      - async
      - bank_id
      - items_count
      - success
      title: RetainResponse
    TagItem:
      description: Single tag with usage count.
      properties:
        tag:
          description: The tag value
          title: Tag
          type: string
        count:
          description: Number of memories with this tag
          title: Count
          type: integer
      required:
      - count
      - tag
      title: TagItem
    TokenUsage:
      description: |-
        Token usage metrics for LLM calls.

        Tracks input/output tokens for a single request to enable
        per-request cost tracking and monitoring.        
      example:
        input_tokens: 1500
        output_tokens: 500
        total_tokens: 2000
      properties:
        input_tokens:
          default: 0
          description: Number of input/prompt tokens consumed
          title: Input Tokens
          type: integer
        output_tokens:
          default: 0
          description: Number of output/completion tokens generated
          title: Output Tokens
          type: integer
        total_tokens:
          default: 0
          description: Total tokens (input + output)
          title: Total Tokens
          type: integer
      title: TokenUsage
    ToolCallsIncludeOptions:
      description: Options for including tool calls in reflect results.
      properties:
        output:
          default: true
          description: Include tool outputs in the trace. Set to false to only include
            inputs (smaller payload).
          title: Output
          type: boolean
      title: ToolCallsIncludeOptions
    UpdateDirectiveRequest:
      description: Request model for updating a directive.
      example:
        is_active: true
        name: name
        priority: 0
        content: content
        tags:
        - tags
        - tags
      properties:
        name:
          nullable: true
          type: string
        content:
          nullable: true
          type: string
        priority:
          nullable: true
          type: integer
        is_active:
          nullable: true
          type: boolean
        tags:
          items:
            type: string
          nullable: true
          type: array
      title: UpdateDirectiveRequest
    UpdateDispositionRequest:
      description: Request model for updating disposition traits.
      example:
        disposition:
          empathy: 3
          literalism: 3
          skepticism: 3
      properties:
        disposition:
          $ref: '#/components/schemas/DispositionTraits'
      required:
      - disposition
      title: UpdateDispositionRequest
    UpdateMentalModelRequest:
      description: Request model for updating a mental model.
      example:
        max_tokens: 4096
        name: Updated Team Communication Preferences
        source_query: How does the team prefer to communicate?
        tags:
        - team
        - communication
        trigger:
          refresh_after_consolidation: true
      properties:
        name:
          nullable: true
          type: string
        source_query:
          nullable: true
          type: string
        max_tokens:
          maximum: 8192.0
          minimum: 256.0
          nullable: true
          type: integer
        tags:
          items:
            type: string
          nullable: true
          type: array
        trigger:
          $ref: '#/components/schemas/MentalModelTrigger'
      title: UpdateMentalModelRequest
    ValidationError:
      example:
        msg: msg
        loc:
        - ValidationError_loc_inner
        - ValidationError_loc_inner
        type: type
      properties:
        loc:
          items:
            $ref: '#/components/schemas/ValidationError_loc_inner'
          type: array
        msg:
          title: Message
          type: string
        type:
          title: Error Type
          type: string
      required:
      - loc
      - msg
      - type
      title: ValidationError
    VersionResponse:
      description: Response model for the version/info endpoint.
      example:
        api_version: 0.4.0
        features:
          bank_config_api: false
          mcp: true
          observations: false
          worker: true
      properties:
        api_version:
          description: API version string
          title: Api Version
          type: string
        features:
          $ref: '#/components/schemas/FeaturesInfo'
      required:
      - api_version
      - features
      title: VersionResponse
    ValidationError_loc_inner:
      anyOf:
      - type: string
      - type: integer