# DO NOT EDIT — generated by _client_gen/convenience_emitter.py from convenience.json.
# Regenerate with: cd clients/v2 && python -c "from _client_gen.convenience_emitter import generate_convenience; generate_convenience()"

"""Memories API namespace — generated from convenience.json."""

from __future__ import annotations

from typing import Any, List, Literal, overload

from goodmem._api_base.memories import MemoriesAPIBase, AsyncMemoriesAPIBase


# --- Convenience imports ---
from goodmem._transforms import _transform_list_kwargs
from goodmem._overrides import (
    memories_create_sync,
    memories_create_async,
    MemoryCreationRequest,
    memories_batch_create_sync,
    memories_batch_create_async,
    memories_retrieve_sync,
    memories_retrieve_async,
)
from goodmem.models.batch_memory_response import BatchMemoryResponse
from goodmem.models.chunking_configuration import ChunkingConfiguration
from goodmem.models.context_item import ContextItem
from goodmem.models.hnsw_options import HnswOptions
from goodmem.models.memory import Memory
from goodmem.models.post_processor import PostProcessor
from goodmem.models.retrieve_memory_event import RetrieveMemoryEvent
from goodmem.models.sort_order import SortOrder
from goodmem.models.space_key import SpaceKey
from goodmem.pagination import AsyncPage, Page
from goodmem.streaming import AsyncRetrieveMemoryStream, RetrieveMemoryStream


class MemoriesAPI(MemoriesAPIBase):
    def batch_create(self, *, requests: list[MemoryCreationRequest]) -> BatchMemoryResponse:
        """Create multiple memories in a batch

        Creates multiple memories in a single operation, with individual success/failure results.

        Args:
            requests (list[MemoryCreationRequest]): Array of memory creation requests.

        Returns:
            BatchMemoryResponse
        """
        return memories_batch_create_sync(self, requests=requests)

    def create(self, *, space_id: str, chunking_config: ChunkingConfiguration | None = None, content_type: str | None = None, extract_page_images: bool | None = None, memory_id: str | None = None, metadata: dict[str, Any] | None = None, original_content: str | None = None, original_content_b64: str | None = None, original_content_ref: str | None = None, file_path: str | None = None) -> Memory:
        """Create a new memory

        Creates a new memory in a specified space and starts asynchronous processing. The memory begins in PENDING status while a background job performs chunking and embedding generation. IDEMPOTENCY: If memory_id is omitted, the server generates a new UUID and retries are not idempotent. If the client supplies a stable memory_id, the operation behaves as create-if-absent: the first request creates the memory and subsequent retries return HTTP 409 Conflict (ALREADY_EXISTS) rather than creating duplicates. Returns INVALID_ARGUMENT if space_id, original_content, or content_type is missing or invalid. Returns NOT_FOUND if the specified space does not exist. Requires CREATE_MEMORY_OWN permission for spaces you own (or CREATE_MEMORY_ANY for admin users to create in any space). Side effects include creating the memory record and enqueuing a background processing job.

        Args:
            space_id (str): ID of the space where this memory will be stored
            chunking_config (ChunkingConfiguration, optional): Chunking strategy for this memory (if not provided, uses space default)
            content_type (str, optional): MIME type of the content. Auto-inferred as `"text/plain"` for `original_content`, or from the file extension for `file_path`. Required when using `original_content_b64`.
            extract_page_images (bool, optional): Optional hint to extract page images for eligible document types (for example, PDFs)
            memory_id (str, optional): Optional client-provided UUID for the memory. If omitted, the server generates one. Returns ALREADY_EXISTS if the ID is already in use.
            metadata (dict[str, Any], optional): Metadata for the memory. Any JSON-serializable dict. Can be nested. Can be used for filtering in memory list operation. (e.g. `{"author": "John Doe", "tags": ["production", "urgent"]}`)
            original_content (str, optional): Original content as plain text. Mutually exclusive with `file_path` and `original_content_b64`.
            original_content_b64 (str, optional): Original content as base64-encoded binary data. Mutually exclusive with `file_path` and `original_content`.
            original_content_ref (str, optional): Reference to external content location. Functions as a metadata field. Does not make Goodmem download the content from the URL and use it to create memory.
            file_path (str, optional): Local file path — the SDK reads and uploads via multipart.

        Returns:
            Memory
        """
        _kw: dict[str, Any] = {"space_id": space_id}
        if chunking_config is not None: _kw["chunking_config"] = chunking_config
        if content_type is not None: _kw["content_type"] = content_type
        if extract_page_images is not None: _kw["extract_page_images"] = extract_page_images
        if memory_id is not None: _kw["memory_id"] = memory_id
        if metadata is not None: _kw["metadata"] = metadata
        if original_content is not None: _kw["original_content"] = original_content
        if original_content_b64 is not None: _kw["original_content_b64"] = original_content_b64
        if original_content_ref is not None: _kw["original_content_ref"] = original_content_ref
        return memories_create_sync(self, file_path=file_path, **_kw)

    def get(self, *, id: str, include_content: bool | None = None, include_processing_history: bool | None = None) -> Memory:
        """Get a memory by ID

        Retrieves a single memory by its ID. PERMISSION CLARIFICATION: With READ_MEMORY_OWN permission, access is granted if you own the parent space OR if the parent space is public (public_read=true). With READ_MEMORY_ANY permission, you can access any memory regardless of ownership. This is a read-only operation with no side effects and is safe to retry. Returns NOT_FOUND if the memory or its parent space does not exist.

        Args:
            id (str): The UUID of the memory to retrieve
            include_content (bool, optional, server default=False): Whether to include the original content in the response (defaults to false).
            include_processing_history (bool, optional, server default=False): Whether to include background job processing history in the response (defaults to false).

        Returns:
            Memory
        """
        _kw: dict[str, Any] = {"id": id}
        if include_content is not None: _kw["include_content"] = include_content
        if include_processing_history is not None: _kw["include_processing_history"] = include_processing_history
        return super().get(**_kw)

    def list(self, *, space_id: str, filter: str | None = None, include_content: bool | None = None, include_processing_history: bool | None = None, sort_by: str | None = None, sort_order: SortOrder | None = None, status_filter: str | None = None, page_size: int | None = None, max_items: int | None = None, next_token: str | None = None) -> Page[Memory]:
        """List memories in a space

        Lists all memories within a given space. Pagination is supported via max_results and next_token (opaque). next_token is a URL-safe Base64 string without padding; do not parse or construct it. This is a read-only operation with no side effects and is safe to retry. Requires LIST_MEMORY_OWN or LIST_MEMORY_ANY permission. Returns NOT_FOUND if the specified space does not exist.

        Args:
            space_id (str): The UUID of the space containing the memories
            filter (str, optional): Metadata filter expression for list results. See [Metadata Filters Guide](../../../../how-to/metadata-filters) and [Filter Expressions Reference](../../../filter-expressions) for usage.
            include_content (bool, optional, server default=False): Whether to include the original content in the response (defaults to false).
            include_processing_history (bool, optional, server default=False): Whether to include background job processing history in the response (defaults to false).
            sort_by (str, optional): Field to sort by (e.g., 'created_at').
            sort_order (SortOrder, optional): Sort direction (ASCENDING or DESCENDING).
            status_filter (str, optional): Filter memories by processing status (PENDING, PROCESSING, COMPLETED, FAILED).
            page_size (int, optional): Number of results per page (defaults to 50, clamped to [1, 500] by the server). A smaller value will reduce the latency of each page — so you get items faster each page, but increase the number of requests made to the server. Use `max_items` to cap total results.
            max_items (int, optional): Maximum total number of items to return across all pages. When set, iteration stops after this many items. If left unset, all pages will be fetched.
            next_token (str, optional): Opaque pagination token for the next page.

        Returns:
            Page[Memory]
        """
        _kw: dict[str, Any] = {"space_id": space_id}
        if filter is not None: _kw["filter"] = filter
        if include_content is not None: _kw["include_content"] = include_content
        if include_processing_history is not None: _kw["include_processing_history"] = include_processing_history
        if sort_by is not None: _kw["sort_by"] = sort_by
        if sort_order is not None: _kw["sort_order"] = sort_order
        if status_filter is not None: _kw["status_filter"] = status_filter
        if page_size is not None: _kw["page_size"] = page_size
        if max_items is not None: _kw["max_items"] = max_items
        if next_token is not None: _kw["next_token"] = next_token
        max_items_val = _transform_list_kwargs(_kw)
        page = super().list(**_kw)
        if max_items_val is not None:
            page._max_items = max_items_val
            page.data = page.data[:max_items_val]
        return page

    @overload
    def retrieve(self, *, message: str, chronological_resort: bool | None = None, context: list[ContextItem] | None = None, fetch_memory: bool | None = None, fetch_memory_content: bool | None = None, gen_token_budget: int | None = None, hnsw: HnswOptions | None = None, llm_id: str | None = None, llm_temp: float | None = None, max_results: int | None = None, post_processor: PostProcessor | None = None, prompt: str | None = None, relevance_threshold: float | None = None, requested_size: int | None = None, reranker_id: str | None = None, space_ids: list[str] | None = None, space_keys: list[SpaceKey] | None = None, sys_prompt: str | None = None, stream: Literal[True] = ...) -> RetrieveMemoryStream: ...
    @overload
    def retrieve(self, *, message: str, chronological_resort: bool | None = None, context: list[ContextItem] | None = None, fetch_memory: bool | None = None, fetch_memory_content: bool | None = None, gen_token_budget: int | None = None, hnsw: HnswOptions | None = None, llm_id: str | None = None, llm_temp: float | None = None, max_results: int | None = None, post_processor: PostProcessor | None = None, prompt: str | None = None, relevance_threshold: float | None = None, requested_size: int | None = None, reranker_id: str | None = None, space_ids: list[str] | None = None, space_keys: list[SpaceKey] | None = None, sys_prompt: str | None = None, stream: Literal[False]) -> List[RetrieveMemoryEvent]: ...
    def retrieve(self, *, message: str, chronological_resort: bool | None = None, context: list[ContextItem] | None = None, fetch_memory: bool | None = None, fetch_memory_content: bool | None = None, gen_token_budget: int | None = None, hnsw: HnswOptions | None = None, llm_id: str | None = None, llm_temp: float | None = None, max_results: int | None = None, post_processor: PostProcessor | None = None, prompt: str | None = None, relevance_threshold: float | None = None, requested_size: int | None = None, reranker_id: str | None = None, space_ids: list[str] | None = None, space_keys: list[SpaceKey] | None = None, sys_prompt: str | None = None, stream: bool = True) -> RetrieveMemoryStream | List[RetrieveMemoryEvent]:
        """Advanced semantic memory retrieval with JSON

        Streams semantic retrieval results with full feature support including context items and embedder weight overrides, per-space filters, and request-level HNSW tuning. Supports SSE (text/event-stream) and NDJSON (application/x-ndjson) formats.

        Args:
            message (str): Primary query/message for semantic search.
            chronological_resort (bool, optional): Re-sort retrieved memories chronologically after semantic ranking. Defaults to true on the server. Only applies when `llm_id` or `reranker_id` is set.
            context (list[ContextItem], optional): Optional context items (text or binary) to provide additional context for the search.
            fetch_memory (bool, optional, server default=True): If `True`, memory definition events are streamed. Set to `False` to skip them.
            fetch_memory_content (bool, optional, server default=False): If `True`, includes the raw content of each memory in the response. Only applicable when `fetch_memory` is `True`.
            gen_token_budget (int, optional): Token budget for LLM post-processing. Must be positive. If the token budget is insufficient, the server will return an error. Defaults to 512 on the server. Only applies when `llm_id` is set.
            hnsw (HnswOptions, optional): Optional request-level HNSW tuning overrides. Advanced usage; available on POST retrieve.
            llm_id (str, optional): The ID of the LLM to process the retrieved memories, e.g., RAG. Assembles the nested `PostProcessor` structure automatically. If unset, no LLM will be used. Setting `llm_id` or `reranker_id` activates post-processing; the remaining post-processor params below (`llm_temp`, `gen_token_budget`, etc.) only take effect when at least one is set.
            llm_temp (float, optional): LLM temperature for post-processing. Valid range is 0.0-2.0. Defaults to 0.3 on the server. Only applies when `llm_id` is set.
            max_results (int, optional): Maximum number of retrieved memories to return. Must be positive. Defaults to 10 on the server. Only applies when `llm_id` or `reranker_id` is set.
            post_processor (PostProcessor, optional): Optional post-processor configuration to transform retrieval results.
            prompt (str, optional): Custom prompt for LLM post-processing. If unset, the server's default prompt is used. Only applies when `llm_id` is set.
            relevance_threshold (float, optional): Minimum relevance score for retrieved memories. Only applies when `reranker_id` is set.
            requested_size (int, optional): Maximum number of memories to retrieve.
            reranker_id (str, optional): The ID of the reranker to process the retrieved memories. If unset, no reranker will be used.
            space_ids (list[str], optional): A list of space UUID strings, converted to the `space_keys` structure the API requires.
            space_keys (list[SpaceKey], optional): Full space configuration for retrieval — a list of `SpaceKey` dicts, each with a required `space_id` and optional `embedder_weights` (per-embedder weight overrides) and `filter` (metadata filter expression). Use this instead of `space_ids` when you need per-space weight tuning or filtering.
            sys_prompt (str, optional): System prompt for LLM post-processing. If unset, the server's default system prompt is used. Only applies when `llm_id` is set.
            stream (bool, optional, default=True): If True (default), return a streaming iterator; if False, collect all events into a list.

        Returns:
            RetrieveMemoryStream | List[RetrieveMemoryEvent]
        """
        _kw: dict[str, Any] = {"message": message}
        if chronological_resort is not None: _kw["chronological_resort"] = chronological_resort
        if context is not None: _kw["context"] = context
        if fetch_memory is not None: _kw["fetch_memory"] = fetch_memory
        if fetch_memory_content is not None: _kw["fetch_memory_content"] = fetch_memory_content
        if gen_token_budget is not None: _kw["gen_token_budget"] = gen_token_budget
        if hnsw is not None: _kw["hnsw"] = hnsw
        if llm_id is not None: _kw["llm_id"] = llm_id
        if llm_temp is not None: _kw["llm_temp"] = llm_temp
        if max_results is not None: _kw["max_results"] = max_results
        if post_processor is not None: _kw["post_processor"] = post_processor
        if prompt is not None: _kw["prompt"] = prompt
        if relevance_threshold is not None: _kw["relevance_threshold"] = relevance_threshold
        if requested_size is not None: _kw["requested_size"] = requested_size
        if reranker_id is not None: _kw["reranker_id"] = reranker_id
        if space_ids is not None: _kw["space_ids"] = space_ids
        if space_keys is not None: _kw["space_keys"] = space_keys
        if sys_prompt is not None: _kw["sys_prompt"] = sys_prompt
        return memories_retrieve_sync(self, stream=stream, **_kw)



class AsyncMemoriesAPI(AsyncMemoriesAPIBase):
    async def batch_create(self, *, requests: list[MemoryCreationRequest]) -> BatchMemoryResponse:
        """Create multiple memories in a batch

        Creates multiple memories in a single operation, with individual success/failure results.

        Args:
            requests (list[MemoryCreationRequest]): Array of memory creation requests.

        Returns:
            BatchMemoryResponse
        """
        return await memories_batch_create_async(self, requests=requests)

    async def create(self, *, space_id: str, chunking_config: ChunkingConfiguration | None = None, content_type: str | None = None, extract_page_images: bool | None = None, memory_id: str | None = None, metadata: dict[str, Any] | None = None, original_content: str | None = None, original_content_b64: str | None = None, original_content_ref: str | None = None, file_path: str | None = None) -> Memory:
        """Create a new memory

        Creates a new memory in a specified space and starts asynchronous processing. The memory begins in PENDING status while a background job performs chunking and embedding generation. IDEMPOTENCY: If memory_id is omitted, the server generates a new UUID and retries are not idempotent. If the client supplies a stable memory_id, the operation behaves as create-if-absent: the first request creates the memory and subsequent retries return HTTP 409 Conflict (ALREADY_EXISTS) rather than creating duplicates. Returns INVALID_ARGUMENT if space_id, original_content, or content_type is missing or invalid. Returns NOT_FOUND if the specified space does not exist. Requires CREATE_MEMORY_OWN permission for spaces you own (or CREATE_MEMORY_ANY for admin users to create in any space). Side effects include creating the memory record and enqueuing a background processing job.

        Args:
            space_id (str): ID of the space where this memory will be stored
            chunking_config (ChunkingConfiguration, optional): Chunking strategy for this memory (if not provided, uses space default)
            content_type (str, optional): MIME type of the content. Auto-inferred as `"text/plain"` for `original_content`, or from the file extension for `file_path`. Required when using `original_content_b64`.
            extract_page_images (bool, optional): Optional hint to extract page images for eligible document types (for example, PDFs)
            memory_id (str, optional): Optional client-provided UUID for the memory. If omitted, the server generates one. Returns ALREADY_EXISTS if the ID is already in use.
            metadata (dict[str, Any], optional): Metadata for the memory. Any JSON-serializable dict. Can be nested. Can be used for filtering in memory list operation. (e.g. `{"author": "John Doe", "tags": ["production", "urgent"]}`)
            original_content (str, optional): Original content as plain text. Mutually exclusive with `file_path` and `original_content_b64`.
            original_content_b64 (str, optional): Original content as base64-encoded binary data. Mutually exclusive with `file_path` and `original_content`.
            original_content_ref (str, optional): Reference to external content location. Functions as a metadata field. Does not make Goodmem download the content from the URL and use it to create memory.
            file_path (str, optional): Local file path — the SDK reads and uploads via multipart.

        Returns:
            Memory
        """
        _kw: dict[str, Any] = {"space_id": space_id}
        if chunking_config is not None: _kw["chunking_config"] = chunking_config
        if content_type is not None: _kw["content_type"] = content_type
        if extract_page_images is not None: _kw["extract_page_images"] = extract_page_images
        if memory_id is not None: _kw["memory_id"] = memory_id
        if metadata is not None: _kw["metadata"] = metadata
        if original_content is not None: _kw["original_content"] = original_content
        if original_content_b64 is not None: _kw["original_content_b64"] = original_content_b64
        if original_content_ref is not None: _kw["original_content_ref"] = original_content_ref
        return await memories_create_async(self, file_path=file_path, **_kw)

    async def get(self, *, id: str, include_content: bool | None = None, include_processing_history: bool | None = None) -> Memory:
        """Get a memory by ID

        Retrieves a single memory by its ID. PERMISSION CLARIFICATION: With READ_MEMORY_OWN permission, access is granted if you own the parent space OR if the parent space is public (public_read=true). With READ_MEMORY_ANY permission, you can access any memory regardless of ownership. This is a read-only operation with no side effects and is safe to retry. Returns NOT_FOUND if the memory or its parent space does not exist.

        Args:
            id (str): The UUID of the memory to retrieve
            include_content (bool, optional, server default=False): Whether to include the original content in the response (defaults to false).
            include_processing_history (bool, optional, server default=False): Whether to include background job processing history in the response (defaults to false).

        Returns:
            Memory
        """
        _kw: dict[str, Any] = {"id": id}
        if include_content is not None: _kw["include_content"] = include_content
        if include_processing_history is not None: _kw["include_processing_history"] = include_processing_history
        return await super().get(**_kw)

    async def list(self, *, space_id: str, filter: str | None = None, include_content: bool | None = None, include_processing_history: bool | None = None, sort_by: str | None = None, sort_order: SortOrder | None = None, status_filter: str | None = None, page_size: int | None = None, max_items: int | None = None, next_token: str | None = None) -> AsyncPage[Memory]:
        """List memories in a space

        Lists all memories within a given space. Pagination is supported via max_results and next_token (opaque). next_token is a URL-safe Base64 string without padding; do not parse or construct it. This is a read-only operation with no side effects and is safe to retry. Requires LIST_MEMORY_OWN or LIST_MEMORY_ANY permission. Returns NOT_FOUND if the specified space does not exist.

        Args:
            space_id (str): The UUID of the space containing the memories
            filter (str, optional): Metadata filter expression for list results. See [Metadata Filters Guide](../../../../how-to/metadata-filters) and [Filter Expressions Reference](../../../filter-expressions) for usage.
            include_content (bool, optional, server default=False): Whether to include the original content in the response (defaults to false).
            include_processing_history (bool, optional, server default=False): Whether to include background job processing history in the response (defaults to false).
            sort_by (str, optional): Field to sort by (e.g., 'created_at').
            sort_order (SortOrder, optional): Sort direction (ASCENDING or DESCENDING).
            status_filter (str, optional): Filter memories by processing status (PENDING, PROCESSING, COMPLETED, FAILED).
            page_size (int, optional): Number of results per page (defaults to 50, clamped to [1, 500] by the server). A smaller value will reduce the latency of each page — so you get items faster each page, but increase the number of requests made to the server. Use `max_items` to cap total results.
            max_items (int, optional): Maximum total number of items to return across all pages. When set, iteration stops after this many items. If left unset, all pages will be fetched.
            next_token (str, optional): Opaque pagination token for the next page.

        Returns:
            AsyncPage[Memory]
        """
        _kw: dict[str, Any] = {"space_id": space_id}
        if filter is not None: _kw["filter"] = filter
        if include_content is not None: _kw["include_content"] = include_content
        if include_processing_history is not None: _kw["include_processing_history"] = include_processing_history
        if sort_by is not None: _kw["sort_by"] = sort_by
        if sort_order is not None: _kw["sort_order"] = sort_order
        if status_filter is not None: _kw["status_filter"] = status_filter
        if page_size is not None: _kw["page_size"] = page_size
        if max_items is not None: _kw["max_items"] = max_items
        if next_token is not None: _kw["next_token"] = next_token
        max_items_val = _transform_list_kwargs(_kw)
        page = await super().list(**_kw)
        if max_items_val is not None:
            page._max_items = max_items_val
            page.data = page.data[:max_items_val]
        return page

    @overload
    async def retrieve(self, *, message: str, chronological_resort: bool | None = None, context: list[ContextItem] | None = None, fetch_memory: bool | None = None, fetch_memory_content: bool | None = None, gen_token_budget: int | None = None, hnsw: HnswOptions | None = None, llm_id: str | None = None, llm_temp: float | None = None, max_results: int | None = None, post_processor: PostProcessor | None = None, prompt: str | None = None, relevance_threshold: float | None = None, requested_size: int | None = None, reranker_id: str | None = None, space_ids: list[str] | None = None, space_keys: list[SpaceKey] | None = None, sys_prompt: str | None = None, stream: Literal[True] = ...) -> AsyncRetrieveMemoryStream: ...
    @overload
    async def retrieve(self, *, message: str, chronological_resort: bool | None = None, context: list[ContextItem] | None = None, fetch_memory: bool | None = None, fetch_memory_content: bool | None = None, gen_token_budget: int | None = None, hnsw: HnswOptions | None = None, llm_id: str | None = None, llm_temp: float | None = None, max_results: int | None = None, post_processor: PostProcessor | None = None, prompt: str | None = None, relevance_threshold: float | None = None, requested_size: int | None = None, reranker_id: str | None = None, space_ids: list[str] | None = None, space_keys: list[SpaceKey] | None = None, sys_prompt: str | None = None, stream: Literal[False]) -> List[RetrieveMemoryEvent]: ...
    async def retrieve(self, *, message: str, chronological_resort: bool | None = None, context: list[ContextItem] | None = None, fetch_memory: bool | None = None, fetch_memory_content: bool | None = None, gen_token_budget: int | None = None, hnsw: HnswOptions | None = None, llm_id: str | None = None, llm_temp: float | None = None, max_results: int | None = None, post_processor: PostProcessor | None = None, prompt: str | None = None, relevance_threshold: float | None = None, requested_size: int | None = None, reranker_id: str | None = None, space_ids: list[str] | None = None, space_keys: list[SpaceKey] | None = None, sys_prompt: str | None = None, stream: bool = True) -> AsyncRetrieveMemoryStream | List[RetrieveMemoryEvent]:
        """Advanced semantic memory retrieval with JSON

        Streams semantic retrieval results with full feature support including context items and embedder weight overrides, per-space filters, and request-level HNSW tuning. Supports SSE (text/event-stream) and NDJSON (application/x-ndjson) formats.

        Args:
            message (str): Primary query/message for semantic search.
            chronological_resort (bool, optional): Re-sort retrieved memories chronologically after semantic ranking. Defaults to true on the server. Only applies when `llm_id` or `reranker_id` is set.
            context (list[ContextItem], optional): Optional context items (text or binary) to provide additional context for the search.
            fetch_memory (bool, optional, server default=True): If `True`, memory definition events are streamed. Set to `False` to skip them.
            fetch_memory_content (bool, optional, server default=False): If `True`, includes the raw content of each memory in the response. Only applicable when `fetch_memory` is `True`.
            gen_token_budget (int, optional): Token budget for LLM post-processing. Must be positive. If the token budget is insufficient, the server will return an error. Defaults to 512 on the server. Only applies when `llm_id` is set.
            hnsw (HnswOptions, optional): Optional request-level HNSW tuning overrides. Advanced usage; available on POST retrieve.
            llm_id (str, optional): The ID of the LLM to process the retrieved memories, e.g., RAG. Assembles the nested `PostProcessor` structure automatically. If unset, no LLM will be used. Setting `llm_id` or `reranker_id` activates post-processing; the remaining post-processor params below (`llm_temp`, `gen_token_budget`, etc.) only take effect when at least one is set.
            llm_temp (float, optional): LLM temperature for post-processing. Valid range is 0.0-2.0. Defaults to 0.3 on the server. Only applies when `llm_id` is set.
            max_results (int, optional): Maximum number of retrieved memories to return. Must be positive. Defaults to 10 on the server. Only applies when `llm_id` or `reranker_id` is set.
            post_processor (PostProcessor, optional): Optional post-processor configuration to transform retrieval results.
            prompt (str, optional): Custom prompt for LLM post-processing. If unset, the server's default prompt is used. Only applies when `llm_id` is set.
            relevance_threshold (float, optional): Minimum relevance score for retrieved memories. Only applies when `reranker_id` is set.
            requested_size (int, optional): Maximum number of memories to retrieve.
            reranker_id (str, optional): The ID of the reranker to process the retrieved memories. If unset, no reranker will be used.
            space_ids (list[str], optional): A list of space UUID strings, converted to the `space_keys` structure the API requires.
            space_keys (list[SpaceKey], optional): Full space configuration for retrieval — a list of `SpaceKey` dicts, each with a required `space_id` and optional `embedder_weights` (per-embedder weight overrides) and `filter` (metadata filter expression). Use this instead of `space_ids` when you need per-space weight tuning or filtering.
            sys_prompt (str, optional): System prompt for LLM post-processing. If unset, the server's default system prompt is used. Only applies when `llm_id` is set.
            stream (bool, optional, default=True): If True (default), return a streaming iterator; if False, collect all events into a list.

        Returns:
            AsyncRetrieveMemoryStream | List[RetrieveMemoryEvent]
        """
        _kw: dict[str, Any] = {"message": message}
        if chronological_resort is not None: _kw["chronological_resort"] = chronological_resort
        if context is not None: _kw["context"] = context
        if fetch_memory is not None: _kw["fetch_memory"] = fetch_memory
        if fetch_memory_content is not None: _kw["fetch_memory_content"] = fetch_memory_content
        if gen_token_budget is not None: _kw["gen_token_budget"] = gen_token_budget
        if hnsw is not None: _kw["hnsw"] = hnsw
        if llm_id is not None: _kw["llm_id"] = llm_id
        if llm_temp is not None: _kw["llm_temp"] = llm_temp
        if max_results is not None: _kw["max_results"] = max_results
        if post_processor is not None: _kw["post_processor"] = post_processor
        if prompt is not None: _kw["prompt"] = prompt
        if relevance_threshold is not None: _kw["relevance_threshold"] = relevance_threshold
        if requested_size is not None: _kw["requested_size"] = requested_size
        if reranker_id is not None: _kw["reranker_id"] = reranker_id
        if space_ids is not None: _kw["space_ids"] = space_ids
        if space_keys is not None: _kw["space_keys"] = space_keys
        if sys_prompt is not None: _kw["sys_prompt"] = sys_prompt
        return await memories_retrieve_async(self, stream=stream, **_kw)

