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.13
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
  /v1/default/banks/{bank_id}/files/retain:
    post:
      description: |-
        Upload files (PDF, DOCX, etc.), convert them to markdown, and retain as memories.

        This endpoint handles file upload, conversion, and memory creation in a single operation.

        **Features:**
        - Supports PDF, DOCX, PPTX, XLSX, images (with OCR), audio (with transcription)
        - Automatic file-to-markdown conversion using pluggable parsers
        - Files stored in object storage (PostgreSQL by default, S3 for production)
        - Each file becomes a separate document with optional metadata/tags
        - Always processes asynchronously — returns operation IDs immediately

        **The system automatically:**
        1. Stores uploaded files in object storage
        2. Converts files to markdown
        3. Creates document records with file metadata
        4. Extracts facts and creates memory units (same as regular retain)

        Use the operations endpoint to monitor progress.

        **Request format:** multipart/form-data with:
        - `files`: One or more files to upload
        - `request`: JSON string with FileRetainRequest model (files_metadata)

        **Note:** File parser is configured server-side via `HINDSIGHT_API_FILE_PARSER` (default: markitdown).
      operationId: file_retain
      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:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_file_retain'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileRetainResponse'
          description: Successful Response
        "422":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Convert files to memories
      tags:
      - Files
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
    Body_file_retain:
      properties:
        files:
          description: Files to upload and convert
          items:
            format: binary
            type: string
          type: array
        request:
          description: JSON string with FileRetainRequest model
          title: Request
          type: string
      required:
      - files
      - request
      title: Body_file_retain
    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
        file_upload_api:
          description: Whether file upload/conversion API is enabled
          title: File Upload Api
          type: boolean
      required:
      - bank_config_api
      - file_upload_api
      - mcp
      - observations
      - worker
      title: FeaturesInfo
    FileRetainResponse:
      description: Response model for file upload endpoint.
      example:
        operation_ids:
        - 550e8400-e29b-41d4-a716-446655440000
        - 550e8400-e29b-41d4-a716-446655440001
        - 550e8400-e29b-41d4-a716-446655440002
      properties:
        operation_ids:
          description: "Operation IDs for tracking file conversion operations. Use\
            \ GET /v1/default/banks/{bank_id}/operations to list operations."
          items:
            type: string
          type: array
      required:
      - operation_ids
      title: FileRetainResponse
    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'
        source_facts:
          $ref: '#/components/schemas/SourceFactsIncludeOptions'
      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
        source_facts:
          additionalProperties:
            $ref: '#/components/schemas/RecallResult'
          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
        source_fact_ids:
          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
    SourceFactsIncludeOptions:
      description: Options for including source facts for observation-type results.
      properties:
        max_tokens:
          default: 4096
          description: Maximum tokens for source facts
          title: Max Tokens
          type: integer
      title: SourceFactsIncludeOptions
    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
          file_upload_api: true
          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