> ## Documentation Index
> Fetch the complete documentation index at: https://oma-codex-339-workspace-permissions.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# List memories

> List memories through the OMA API.

<Info>Every request requires `?beta=true`.</Info>


## OpenAPI

````yaml /openapi/oma.en.json get /v1/memory_stores/{memory_store_id}/memories
openapi: 3.1.0
info:
  title: OMA API Reference
  version: 1.0.0
  description: Open Managed Agents application API reference.
servers:
  - url: http://localhost:38080
    description: Local OMA server
security:
  - omaApiKey: []
  - omaBearer: []
paths:
  /v1/memory_stores/{memory_store_id}/memories:
    get:
      summary: List memories
      operationId: BetaListMemories
      parameters:
        - name: beta
          in: query
          required: true
          description: Selects the beta API contract for this endpoint. Must be `true`.
          schema:
            type: boolean
            enum:
              - true
        - name: anthropic-version
          in: header
          required: false
          schema:
            type: string
        - name: anthropic-beta
          in: header
          required: false
          schema:
            type: string
            items:
              type: string
            x-stainless-override-schema:
              x-stainless-param: betas
              x-stainless-extend-default: true
              type: array
              description: Optional header to specify the beta version(s) you want to use.
              items:
                $ref: '#/components/schemas/AnthropicBeta'
            x-default: agent-memory-2026-07-22
        - name: memory_store_id
          in: path
          required: true
          schema:
            type: string
          description: Path parameter memory_store_id
        - name: path_prefix
          in: query
          required: false
          schema:
            type: string
          description: >-
            Optional path prefix filter. Must end with `/` (segment-aligned),
            e.g., `/notes/`. This value appears in request URLs. Do not include
            secrets or personally identifiable information.
        - name: depth
          in: query
          required: false
          schema:
            type: integer
            format: int32
          description: >-
            `0` (or omitted) returns all descendants below `path_prefix`
            (recursive). `1` returns immediate children only; deeper entries
            roll up as `memory_prefix` items. `depth=1` behaves like `ls`;
            omitting `depth` behaves like `find`.
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            format: int32
          description: >-
            Maximum number of items to return per page. Must be between 1 and
            100. Defaults to 20 when omitted. Capped at 20 when `view=full`.
            Both `memory` and `memory_prefix` items count toward the limit.
        - name: page
          in: query
          required: false
          schema:
            type: string
          description: >-
            Opaque pagination cursor (a `page_...` value). Pass the `next_page`
            value from a previous response to fetch the next page; omit for the
            first page.
        - name: view
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/BetaManagedAgentsMemoryView'
          description: >-
            Which projection of each `memory` to return. Defaults to `basic`
            (content omitted). `full` populates `content` on each item and caps
            `limit` at 20; use this as the bulk-read path for export and sync.
      responses:
        '200':
          description: Successful response (OK)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaManagedAgentsListMemoriesResult'
        '400':
          description: Invalid argument - The client specified an invalid argument
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaManagedAgentsErrorResponse'
        '401':
          description: >-
            Unauthenticated - The request does not have valid authentication
            credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaManagedAgentsErrorResponse'
        '403':
          description: >-
            Permission denied - The caller does not have permission to execute
            the specified operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaManagedAgentsErrorResponse'
        '404':
          description: Not found - Some requested entity was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaManagedAgentsErrorResponse'
        '408':
          description: >-
            Deadline exceeded - The deadline expired before the operation could
            complete
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaManagedAgentsErrorResponse'
        '409':
          description: Custom error status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaManagedAgentsErrorResponse'
        '412':
          description: >-
            Failed precondition - Operation was rejected because the system is
            not in required state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaManagedAgentsErrorResponse'
        '413':
          description: Out of range - Operation was attempted past the valid range
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaManagedAgentsErrorResponse'
        '429':
          description: >-
            Resource exhausted - Some resource has been exhausted (rate
            limiting)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaManagedAgentsErrorResponse'
        '431':
          description: Request header fields too large - Request metadata was too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaManagedAgentsErrorResponse'
        '499':
          description: Cancelled - The operation was cancelled by the client
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaManagedAgentsErrorResponse'
        '500':
          description: Internal - Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaManagedAgentsErrorResponse'
        '501':
          description: Unimplemented - The operation is not implemented or supported
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaManagedAgentsErrorResponse'
        '503':
          description: Unavailable - The service is currently unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaManagedAgentsErrorResponse'
        '504':
          description: Deadline exceeded - Upstream service did not respond in time
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaManagedAgentsErrorResponse'
components:
  schemas:
    BetaManagedAgentsMemoryView:
      type: string
      description: >-
        Selects which projection of a `memory` or `memory_version` the server
        returns. `basic` returns the object with `content` set to `null`; `full`
        populates `content`. When omitted, the default is endpoint-specific:
        retrieve operations default to `full`; list, create, and update
        operations default to `basic`. Listing with `view=full` caps `limit` at
        20.
      enum:
        - basic
        - full
    BetaManagedAgentsListMemoriesResult:
      description: Response payload for List memories.
      type: object
      additionalProperties: false
      properties:
        data:
          description: >-
            One page of results. Each item is either a `memory` object or, when
            `depth` was set, a `memory_prefix` rollup marker. Items are returned
            in a stable, server-defined order.
          type: array
          items:
            $ref: '#/components/schemas/BetaManagedAgentsMemoryListItem'
        next_page:
          description: >-
            Opaque cursor for the next page (a `page_...` value), or `null` if
            there are no more results. Pass as `page` on the next request.
          type: string
          nullable: true
    BetaManagedAgentsErrorResponse:
      type: object
      required:
        - type
        - error
      properties:
        type:
          type: string
          enum:
            - error
          description: Always "error" for error responses
        error:
          $ref: '#/components/schemas/BetaManagedAgentsError'
    BetaManagedAgentsMemoryListItem:
      description: >-
        One item in a List memories response: either a `memory` object or, when
        `depth` is set, a `memory_prefix` rollup marker.
      type: object
      discriminator:
        propertyName: type
        mapping:
          memory:
            $ref: '#/components/schemas/BetaManagedAgentsMemory'
          memory_prefix:
            $ref: '#/components/schemas/BetaManagedAgentsMemoryPrefix'
      oneOf:
        - $ref: '#/components/schemas/BetaManagedAgentsMemory'
        - $ref: '#/components/schemas/BetaManagedAgentsMemoryPrefix'
    BetaManagedAgentsError:
      discriminator:
        propertyName: type
        mapping:
          invalid_request_error:
            $ref: '#/components/schemas/BetaInvalidRequestError'
          authentication_error:
            $ref: '#/components/schemas/BetaAuthenticationError'
          billing_error:
            $ref: '#/components/schemas/BetaBillingError'
          permission_error:
            $ref: '#/components/schemas/BetaPermissionError'
          not_found_error:
            $ref: '#/components/schemas/BetaNotFoundError'
          rate_limit_error:
            $ref: '#/components/schemas/BetaRateLimitError'
          timeout_error:
            $ref: '#/components/schemas/BetaGatewayTimeoutError'
          api_error:
            $ref: '#/components/schemas/BetaAPIError'
          overloaded_error:
            $ref: '#/components/schemas/BetaOverloadedError'
          memory_precondition_failed_error:
            $ref: >-
              #/components/schemas/BetaManagedAgentsMemoryPreconditionFailedError
          memory_path_conflict_error:
            $ref: '#/components/schemas/BetaManagedAgentsMemoryPathConflictError'
          conflict_error:
            $ref: '#/components/schemas/BetaManagedAgentsConflictError'
      oneOf:
        - $ref: '#/components/schemas/BetaInvalidRequestError'
        - $ref: '#/components/schemas/BetaAuthenticationError'
        - $ref: '#/components/schemas/BetaBillingError'
        - $ref: '#/components/schemas/BetaPermissionError'
        - $ref: '#/components/schemas/BetaNotFoundError'
        - $ref: '#/components/schemas/BetaRateLimitError'
        - $ref: '#/components/schemas/BetaGatewayTimeoutError'
        - $ref: '#/components/schemas/BetaAPIError'
        - $ref: '#/components/schemas/BetaOverloadedError'
        - $ref: '#/components/schemas/BetaManagedAgentsMemoryPreconditionFailedError'
        - $ref: '#/components/schemas/BetaManagedAgentsMemoryPathConflictError'
        - $ref: '#/components/schemas/BetaManagedAgentsConflictError'
    BetaManagedAgentsMemory:
      description: >-
        A `memory` object: a single text document at a hierarchical path inside
        a memory store. The `content` field is populated when `view=full` and
        `null` when `view=basic`; the `content_size_bytes` and `content_sha256`
        fields are always populated so sync clients can diff without fetching
        content. Memories are addressed by their `mem_...` ID; the path is the
        create key and can be changed via update.
      type: object
      additionalProperties: false
      required:
        - type
        - id
        - memory_store_id
        - path
        - content_size_bytes
        - content_sha256
        - memory_version_id
        - created_at
        - updated_at
      properties:
        type:
          type: string
          enum:
            - memory
        id:
          description: >-
            Unique identifier for this memory (a `mem_...` value). Stable across
            renames; use this ID, not the path, to read, update, or delete the
            memory.
          type: string
        memory_store_id:
          description: >-
            ID of the memory store this memory belongs to (a `memstore_...`
            value).
          type: string
        path:
          description: >-
            Hierarchical path of the memory within the store, e.g.
            `/projects/foo/notes.md`. Always starts with `/`. Paths are
            case-sensitive and unique within a store. Maximum 1,024 bytes.
          type: string
        content:
          description: >-
            The memory's UTF-8 text content. Populated when `view=full`; `null`
            when `view=basic`. Maximum 100 kB (102,400 bytes).
          type: string
          nullable: true
        content_size_bytes:
          description: >-
            Size of `content` in bytes (the UTF-8 plaintext length). Always
            populated, regardless of `view`.
          type: integer
          format: int32
        content_sha256:
          description: >-
            Lowercase hex SHA-256 digest of the UTF-8 `content` bytes (64
            characters). The server applies no normalization, so clients can
            compute the same hash locally for staleness checks and as the value
            for a `content_sha256` precondition on update. Always populated,
            regardless of `view`.
          type: string
        memory_version_id:
          description: >-
            ID of the `memory_version` representing this memory's current
            content (a `memver_...` value). This is the authoritative head
            pointer; `memory_version` objects do not carry an `is_latest` flag,
            so compare against this field instead. Enumerate the full history
            via List memory versions.
          type: string
        created_at:
          description: When this memory was created, in RFC 3339 format.
          allOf:
            - $ref: '#/components/schemas/BetaTimestamp'
        updated_at:
          description: >-
            When this memory was last modified, in RFC 3339 format. Use this as
            a cheap freshness signal; for who made the change, look up the head
            version's `created_by` via List memory versions.
          allOf:
            - $ref: '#/components/schemas/BetaTimestamp'
    BetaManagedAgentsMemoryPrefix:
      description: >-
        A rolled-up directory marker returned by List memories when `depth` is
        set. Indicates that one or more memories exist deeper than the requested
        depth under this prefix. This is a list-time rollup, not a stored
        resource; it has no ID and no lifecycle. Each prefix counts toward the
        page `limit` and interleaves with `memory` items in path order.
      type: object
      additionalProperties: false
      required:
        - type
        - path
      properties:
        type:
          type: string
          enum:
            - memory_prefix
        path:
          description: >-
            The rolled-up path prefix, including a trailing `/` (e.g.
            `/projects/foo/`). Pass this value as `path_prefix` on a subsequent
            list call to drill into the directory.
          type: string
    BetaInvalidRequestError:
      properties:
        message:
          default: Invalid request
          title: Message
          type: string
        type:
          const: invalid_request_error
          default: invalid_request_error
          title: Type
          type: string
      required:
        - message
        - type
      title: InvalidRequestError
      type: object
    BetaAuthenticationError:
      properties:
        message:
          default: Authentication error
          title: Message
          type: string
        type:
          const: authentication_error
          default: authentication_error
          title: Type
          type: string
      required:
        - message
        - type
      title: AuthenticationError
      type: object
    BetaBillingError:
      properties:
        message:
          default: Billing error
          title: Message
          type: string
        type:
          const: billing_error
          default: billing_error
          title: Type
          type: string
      required:
        - message
        - type
      title: BillingError
      type: object
    BetaPermissionError:
      properties:
        message:
          default: Permission denied
          title: Message
          type: string
        type:
          const: permission_error
          default: permission_error
          title: Type
          type: string
      required:
        - message
        - type
      title: PermissionError
      type: object
    BetaNotFoundError:
      properties:
        message:
          default: Not found
          title: Message
          type: string
        type:
          const: not_found_error
          default: not_found_error
          title: Type
          type: string
      required:
        - message
        - type
      title: NotFoundError
      type: object
    BetaRateLimitError:
      properties:
        message:
          default: Rate limited
          title: Message
          type: string
        type:
          const: rate_limit_error
          default: rate_limit_error
          title: Type
          type: string
      required:
        - message
        - type
      title: RateLimitError
      type: object
    BetaGatewayTimeoutError:
      properties:
        message:
          default: Request timeout
          title: Message
          type: string
        type:
          const: timeout_error
          default: timeout_error
          title: Type
          type: string
      required:
        - message
        - type
      title: GatewayTimeoutError
      type: object
    BetaAPIError:
      properties:
        message:
          default: Internal server error
          title: Message
          type: string
        type:
          const: api_error
          default: api_error
          title: Type
          type: string
      required:
        - message
        - type
      title: APIError
      type: object
    BetaOverloadedError:
      properties:
        message:
          default: Overloaded
          title: Message
          type: string
        type:
          const: overloaded_error
          default: overloaded_error
          title: Type
          type: string
      required:
        - message
        - type
      title: OverloadedError
      type: object
    BetaManagedAgentsMemoryPreconditionFailedError:
      type: object
      additionalProperties: false
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - memory_precondition_failed_error
        message:
          type: string
    BetaManagedAgentsMemoryPathConflictError:
      type: object
      additionalProperties: false
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - memory_path_conflict_error
        message:
          type: string
        conflicting_path:
          type: string
        conflicting_memory_id:
          type: string
    BetaManagedAgentsConflictError:
      type: object
      additionalProperties: false
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - conflict_error
        message:
          type: string
    BetaTimestamp:
      description: A timestamp in RFC 3339 format
      type: string
      format: date-time
  securitySchemes:
    omaApiKey:
      type: apiKey
      in: header
      name: X-Api-Key
      description: OMA workspace API key.
      x-default: sk-ant-local-default
    omaBearer:
      type: http
      scheme: bearer
      description: OMA workspace API key sent as a bearer token.

````