Memories

Methods on this page are called as client.memories.<method>(...) where client is either a synchronous Goodmem or asynchronous AsyncGoodmem instance initialized below:

from goodmem import Goodmem
client = Goodmem(base_url='http://localhost:8080', api_key='gm_...')

from goodmem import AsyncGoodmem
client = AsyncGoodmem(base_url='http://localhost:8080', api_key='gm_...')

Create a new memoryCopy Anchor Link

memories.create(*, space_id: str, chunking_config: ChunkingConfiguration = None, content_type: str = None, extract_page_images: bool = None, file_path: str = None, memory_id: str = None, metadata: dict[str, Any] = None, original_content: str = None, original_content_b64: str = None, original_content_ref: str = None) → Memory

Create a memory from text content, base64-encoded content, or a local file. Content must be provided via exactly one of file_path, original_content, or original_content_b64. original_content_ref is a metadata pointer (URL) attached to the memory; it does NOT supply content and may accompany the chosen content source.

Parameters:

• space_id (str, format: uuid) — 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 (the server cannot infer MIME type from base64 bytes). NOT required for original_content_ref — ref is a metadata pointer, not a content source.
• extract_page_images (bool, optional) — Optional hint to extract page images for eligible document types (for example, PDFs)
• file_path (str, optional) — Path to a local file to upload. Mutually exclusive with original_content and original_content_b64.
• memory_id (str, format: uuid, 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.

Returns:

Memory — Returns the memory.

Raises:

• ConflictError — The resource already exists or conflicts with existing state.
• APIError — Any other non-2xx HTTP response (base class; exposes status_code and body).

Examples

Example 1:

memory = client.memories.create(
    space_id="your-space-id",
    original_content=(
        "GoodMem stores and retrieves vectorized memories "
        "for RAG applications."
    ),
    metadata={"source": "sdk-doc-test"},
)

Example 2:

# file_path = "path/to/your/file.txt"
memory = client.memories.create(
    space_id="your-space-id",
    file_path=file_path,
)

Example 3:

import base64

content_b64 = base64.b64encode(b"Base64-encoded content.").decode()
memory = client.memories.create(
    space_id="your-space-id",
    original_content_b64=content_b64,
    content_type="text/plain",
)

Retrieve MemoriesCopy Anchor Link

memories.retrieve(*, message: str, chronological_resort: bool = None, context: list[ContextItem] = None, fetch_memory: bool = None, fetch_memory_content: bool = None, gen_token_budget: int = None, hnsw: HnswOptions = None, llm_id: str = None, llm_temp: float = None, logging: LoggingOptions = None, max_results: int = None, output_budget: TokenBudget = None, post_processor: PostProcessor = None, prompt: str = None, relevance_threshold: float = None, requested_size: int = None, reranker_id: str = None, space_ids: list[str] = None, space_keys: list[SpaceKey] = None, stream: bool = True, sys_prompt: str = None) → RetrieveMemoryStream | list[RetrieveMemoryEvent]

Performs a streaming semantic search across one or more memory spaces and returns matching chunks ranked by relevance as well as LLM-postprocessed results (like summarization, question-answering, etc.).

Parameters:

• message (str) — Primary query/message for semantic search.
• chronological_resort (bool, optional) — A convenience shorthand for post_processor.config.chronological_resort. Re-sort memories chronologically after semantic ranking. Defaults to false on the server. Only applies when llm_id or reranker_id is set. Cannot be used together with post_processor.
• 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) — A convenience shorthand for post_processor.config.gen_token_budget. LLM token budget. Uses the first positive value: output_budget.tokens, gen_token_budget, LLM default_sampling_params.max_tokens, then 512. Must be positive. If the token budget is insufficient, the server will return an error. Only applies when llm_id is set. Cannot be used together with post_processor.
• hnsw (HnswOptions, optional) — Optional request-level HNSW tuning overrides. Advanced usage; available on POST retrieve.
• llm_id (str, optional) — A convenience shorthand for post_processor.config.llm_id. 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. Cannot be used together with post_processor.
• llm_temp (float, optional) — A convenience shorthand for post_processor.config.llm_temp. 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. Cannot be used together with post_processor.
• logging (LoggingOptions, optional) — Optional durable request logging block for POST retrieve requests. Set logging.enabled=true to opt in, or supply flat scalar logging.caller_attributes to attach if caller opt-in or an admin policy logs the request.
• max_results (int, optional) — A convenience shorthand for post_processor.config.max_results. Result cap; defaults to positive requested_size, otherwise 10. Must be positive. Only applies when llm_id or reranker_id is set. Cannot be used together with post_processor.
• output_budget (TokenBudget, optional) — Optional soft cap for generated retrieve replies. When set to a positive token count, chat post-processing uses this value as the LLM completion-token budget.
• post_processor (PostProcessor, optional) — Optional post-processor configuration to transform retrieval results. Can also be set via the convenience shorthands llm_id, reranker_id, llm_temp, gen_token_budget, relevance_threshold, max_results, prompt, sys_prompt, and chronological_resort. Use either post_processor or the shorthands, not both.
• prompt (str, optional) — A convenience shorthand for post_processor.config.prompt. Custom prompt for LLM post-processing. If unset, the server's default prompt is used. Only applies when llm_id is set. Cannot be used together with post_processor.
• relevance_threshold (float, optional) — A convenience shorthand for post_processor.config.relevance_threshold. Minimum relevance score for retrieved memories. Only applies when reranker_id is set. Cannot be used together with post_processor.
• requested_size (int, format: int32, optional, server default=20) — Maximum number of memories to retrieve. Zero or omitted uses 20; negative values are invalid.
• reranker_id (str, optional) — A convenience shorthand for post_processor.config.reranker_id. The ID of the reranker to process the retrieved memories. If unset, no reranker will be used. Cannot be used together with post_processor.
• space_ids (list[str], optional) — A convenience shorthand for space_keys. A list of space UUID strings, converted to the space_keys structure the API requires. Exactly one of space_ids and space_keys must be provided.
• 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. Can also be set via the convenience shorthand space_ids. Exactly one of space_ids and space_keys must be provided.
• stream (bool, optional, SDK default=True) — If True (default), returns a RetrieveMemoryStream context manager that yields events as they arrive from the server. If False, collects all events and returns a plain list[RetrieveMemoryEvent].
• sys_prompt (str, optional) — A convenience shorthand for post_processor.config.sys_prompt. System prompt for LLM post-processing. If unset, the server's default system prompt is used. Only applies when llm_id is set. Cannot be used together with post_processor.

Returns:

Raises:

• APIError — Any other non-2xx HTTP response (base class; exposes status_code and body).

Examples

Example 1:

events = client.memories.retrieve(
    message="What is GoodMem?",
    space_ids=["your-space-id"],
    requested_size=5,
    stream=False,
)
for event in events:
    if event.retrieved_item:
        chunk = event.retrieved_item.chunk
        print(chunk.chunk.chunk_text[:80], chunk.relevance_score)

Example 2:

with client.memories.retrieve(
    message="What is GoodMem?",
    space_ids=["your-space-id"],
    requested_size=5,
) as stream:
    for event in stream:
        if event.retrieved_item:
            chunk = event.retrieved_item.chunk
            print(chunk.chunk.chunk_text[:80], chunk.relevance_score)

Example 3:

events = client.memories.retrieve(
    message="What is GoodMem?",
    space_ids=["your-space-id"],
    requested_size=5,
    logging=LoggingOptions(
        enabled=True,
        caller_attributes={
            "test_case": "integration_logging_opt_in",
            "attempt": 1,
        },
    ),
    stream=False,
)

Get a memory by IDCopy Anchor Link

memories.get(*, id: str, include_content: bool = None, include_processing_history: bool = None) → Memory

Retrieves a single memory by its ID.

AUTHORIZATION: Requires READ_MEMORY on the requested memory; authority may be granted directly or through DIRECT_MEMBERS_OF its containing space. 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.

Parameters:

• 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 — Returns the memory.

Raises:

• PermissionDeniedError — The caller lacks the permission the operation requires.
• NotFoundError — The requested resource does not exist.
• APIError — Any other non-2xx HTTP response (base class; exposes status_code and body).

Example

memory = client.memories.get(id="your-memory-id")
print(memory.processing_status)

Download memory contentCopy Anchor Link

memories.content(*, id: str, accept_encoding: str = None, if_match: str = None, range: str = None) → bytes

Returns the original binary payload for a memory. The response uses the memory's stored content type when available. Returns 404 when the memory does not have inline content; clients can check original_content_ref from the metadata endpoint to locate external content. Requires READ_MEMORY on the requested memory; authority may be granted through DIRECT_MEMBERS_OF its containing space. Supports one byte Range (206); invalid or unsatisfiable ranges return 416. For safe resume, send the original strong ETag in If-Match; a mismatch returns 412.

HEAD returns headers without reading source bytes. Full text-like responses may use streaming gzip, which omits Content-Length. Range responses use identity encoding. A failure after delivery starts terminates the transfer.

Parameters:

• id (str) — The UUID of the memory to download
• accept_encoding (str, optional) — Use identity for resumable byte ranges; gzip is available for full text-like responses
• if_match (str, optional) — Saved strong ETag, including quotes. A mismatch returns 412 before any source bytes are sent
• range (str, optional) — Single byte range, for example bytes=1048576- or bytes=-1024

Returns:

Raises:

• PermissionDeniedError — The caller lacks the permission the operation requires.
• APIError — Any other non-2xx HTTP response (base class; exposes status_code and body).

Example

content = client.memories.content(id="your-memory-id")
print(content[:80])

List memory page imagesCopy Anchor Link

memories.pages(*, id: str, content_type: str = None, dpi: int = None, end_page_index: int = None, max_results: int = None, next_token: str = None, start_page_index: int = None) → Page[MemoryPageImage]

Lists extracted page-image metadata for a memory with optional filters and pagination. Requires READ_MEMORY on the containing memory; authority may be granted through DIRECT_MEMBERS_OF its containing space.

Parameters:

• id (str) — Memory UUID
• content_type (str, optional) — Optional rendition filter for page-image MIME type, such as image/png.
• dpi (int, format: int32, optional) — Optional rendition filter for page-image DPI.
• end_page_index (int, format: int32, optional) — Optional upper bound for returned page indices, inclusive.
• max_results (int, format: int32, optional) — Maximum number of results per page.
• next_token (str, optional) — Opaque pagination token for the next page. Do not parse or construct it.
• start_page_index (int, format: int32, optional) — Optional lower bound for returned page indices, inclusive.

Returns:

Raises:

• PermissionDeniedError — The caller lacks the permission the operation requires.
• APIError — Any other non-2xx HTTP response (base class; exposes status_code and body).

Example

page_images = list(client.memories.pages(id="your-page-img-memory-id"))
for pi in page_images:
    print(pi.page_index, pi.content_type)

Download memory page image contentCopy Anchor Link

memories.pages_image(*, id: str, page_index: int, accept_encoding: str = None, content_type: str = None, dpi: int = None, if_match: str = None, range: str = None) → bytes

Downloads inline bytes for one page image. The page index is required. The optional dpi and content type query parameters act as rendition filters; if omitted, the server returns the unique rendition for that page or rejects ambiguous matches. Requires READ_MEMORY on the containing memory; authority may be granted through DIRECT_MEMBERS_OF its containing space.

Parameters:

• id (str) — Memory UUID
• page_index (int, format: int32) — 0-based page index
• accept_encoding (str, optional) — Use identity to receive a strong ETag for conditional downloads
• content_type (str, optional) — Optional rendition filter. MIME type of the desired page image, such as image/png.
• dpi (int, format: int32, optional) — Optional rendition filter. If omitted, the unique page-image rendition for the page is returned; if multiple renditions exist, specify dpi and/or content_type.
• if_match (str, optional) — Saved strong ETag, including quotes. A mismatch returns 412
• range (str, optional) — Single byte range, for example bytes=1024-

Returns:

Raises:

• PermissionDeniedError — The caller lacks the permission the operation requires.
• APIError — Any other non-2xx HTTP response (base class; exposes status_code and body).

Example

image_bytes = client.memories.pages_image(
    id="your-page-img-memory-id",
    page_index=0,
)
print(f"Downloaded {len(image_bytes)} bytes")

List memories in a spaceCopy Anchor Link

memories.list(*, space_id: str, filter: str = None, include_content: bool = None, include_processing_history: bool = None, max_items: int = None, next_token: str = None, page_size: int = None, sort_by: str = None, sort_order: SortOrder = None, status_filter: str = None) → Page[Memory]

Lists memories within a given space. Results are paginated — the returned Page eagerly fetches the first page. Access .data for items and .next_token to resume. Use for mem in page to auto-paginate all pages, page_size to control items per API call, and max_items to cap total results.

Parameters:

• space_id (str) — The UUID of the space containing the memories
• filter (str, optional) — Metadata filter expression for list results. See Metadata Filters Guide and Filter Expressions Reference 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).
• 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. URL-safe Base64 without padding; do not parse or construct it.
• page_size (int, format: int32, optional, server default=50) — 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.
• 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).

Returns:

Raises:

• APIError — Any other non-2xx HTTP response (base class; exposes status_code and body).

Examples

Example 1:

for mem in client.memories.list(space_id="your-space-id"):
    print(mem.memory_id, mem.processing_status)

Example 2:

# Get first page
page = client.memories.list(space_id="your-space-id", page_size=1)
saved_token = page.next_token

# Resume from saved token later
if saved_token:
    for mem in client.memories.list(
        space_id="your-space-id", next_token=saved_token
    ):
        print(mem.memory_id)

Delete a memoryCopy Anchor Link

memories.delete(*, id: str) → None

Permanently deletes a memory and its associated chunks. This operation cannot be undone and immediately removes the memory record from the database.

IDEMPOTENCY: This operation is safe to retry - may return NOT_FOUND if the memory was already deleted or never existed.

AUTHORIZATION: Requires DELETE_MEMORY on the requested memory; authority may be granted through DIRECT_MEMBERS_OF its containing space. Side effects include permanent removal of the memory record and all associated chunk data.

Parameters:

• id (str) — The UUID of the memory to delete

Returns:

Raises:

• PermissionDeniedError — The caller lacks the permission the operation requires.
• NotFoundError — The requested resource does not exist.
• APIError — Any other non-2xx HTTP response (base class; exposes status_code and body).

Example

client.memories.delete(id="your-memory-id")

Create multiple memories in a batchCopy Anchor Link

memories.batch_create(*, requests: list[MemoryCreationRequest]) → BatchMemoryResponse

Create multiple memories in a single batch. Each item in requests follows the same per-call shape as memories.create: provide exactly one of original_content or original_content_b64; original_content_b64 requires content_type (auto-inferred to text/plain for plain-text original_content); original_content_ref is a metadata pointer that may accompany the content source. Per-item failures are reported individually and do NOT abort the batch.

Parameters:

• requests (list[MemoryCreationRequest]) — List of memory creation requests. Import via from goodmem.api.memories import MemoryCreationRequest. Unlike the raw JsonMemoryCreationRequest, content_type is optional and auto-inferred for text content.

Returns:

BatchMemoryResponse — Returns per-item results for the batch operation.

Raises:

• APIError — Any other non-2xx HTTP response (base class; exposes status_code and body).

Example

from goodmem.api.memories import MemoryCreationRequest
result = client.memories.batch_create(requests=[
    MemoryCreationRequest(
        space_id="your-space-id",
        original_content="Batch memory one.",
    ),
    MemoryCreationRequest(
        space_id="your-space-id",
        original_content="Batch memory two.",
    ),
])

Get multiple memories by IDCopy Anchor Link

memories.batch_get(*, memory_ids: list[str], include_content: bool = None, include_processing_history: bool = None) → BatchMemoryResponse

Retrieves multiple memories in a single operation, with individual success/failure results. Each item requires READ_MEMORY on the requested memory; authority may be granted through DIRECT_MEMBERS_OF its containing space.

Parameters:

• memory_ids (list[str]) — Array of memory IDs to retrieve
• include_content (bool, optional, server default=False) — Whether to include the original content in the response
• include_processing_history (bool, optional, server default=False) — Whether to include background job processing history for each memory

Returns:

BatchMemoryResponse — Returns per-item results for the batch operation.

Raises:

• PermissionDeniedError — The caller lacks the permission the operation requires.
• APIError — Any other non-2xx HTTP response (base class; exposes status_code and body).

Example

result = client.memories.batch_get(memory_ids=["your-memory-id-1", "your-memory-id-2"])
for r in result.results:
    print(r.memory.memory_id, r.memory.processing_status)

Delete memories in batchCopy Anchor Link

memories.batch_delete(*, requests: list[BatchDeleteMemorySelectorRequest]) → BatchMemoryResponse

Deletes memories using selector entries. Each selector can target either a specific memory ID or a filtered subset scoped to a specific space. Each selected memory requires DELETE_MEMORY; authority may be granted through DIRECT_MEMBERS_OF its containing space.

Parameters:

• requests (list[BatchDeleteMemorySelectorRequest]) — Array of delete selectors

Returns:

BatchMemoryResponse — Returns per-item results for the batch operation.

Raises:

• PermissionDeniedError — The caller lacks the permission the operation requires.
• APIError — Any other non-2xx HTTP response (base class; exposes status_code and body).

Example

result = client.memories.batch_delete(
    requests=[{"memory_id": mid} for mid in ["your-memory-id-1", "your-memory-id-2"]],
)
for r in result.results:
    print(r.success)

Async usage: client.memories exposes the same methods on AsyncGoodmem; use await / async for as needed.

Data ModelsCopy Anchor Link

All data models are pydantic v2 models. Fields are shown with their Python attribute names; JSON responses use camelCase aliases (e.g., owner_id → ownerId).

MemoryCopy Anchor Link

Memory object containing stored content and metadata

• memory_id (str) — Unique identifier of the memory
• space_id (str) — ID of the space containing this memory
• original_content (bytes, optional) — Original content (only included if requested)
• original_content_length (int, optional) — Size in bytes of the inline original content
• original_content_sha256 (str, optional) — SHA-256 digest of the inline original content, hex encoded
• original_content_ref (str, optional) — Reference to external content location
• content_type (str) — MIME type of the content
• processing_status (Optional[Literal['UNSPECIFIED', 'PENDING', 'PROCESSING', 'COMPLETED', 'FAILED']]) — Processing status of the memory
• page_image_status (Optional[Literal['UNSPECIFIED', 'PENDING', 'PROCESSING', 'COMPLETED', 'FAILED']]) — Processing status of page-image extraction for this memory
• page_image_count (int) — Number of extracted page-image renditions linked to this memory
• metadata (dict[str, Any], optional) — Additional metadata for the memory. A top-level textual title may have been used as a document-title hint when its chunks were embedded; changing it does not automatically re-embed existing chunks.
• created_at (int) — Timestamp when the memory was created (milliseconds since epoch)
• updated_at (int) — Timestamp when the memory was last updated (milliseconds since epoch)
• created_by_id (str) — Exact principal or API-key audit actor that created this memory
• updated_by_id (str) — Exact principal or API-key audit actor that last updated this memory
• chunking_config (ChunkingConfiguration, optional) — Chunking strategy used for this memory
• processing_history (ProcessingHistory, optional) — Background job processing history associated with this memory

ProcessingHistoryCopy Anchor Link

Background job execution history associated with a memory

• latest_job (BackgroundJobSummary, optional) — Summary of the most recent background job
• attempts (list[BackgroundJobAttempt], optional) — Attempt-level telemetry captured for the latest job

BackgroundJobSummaryCopy Anchor Link

Summary of the most recent background job execution for a resource

• job_id (int) — Database identifier of the background job
• job_type (str) — Logical job type dispatched by the background job framework
• status (Optional[Literal['BACKGROUND_JOB_STATUS_UNSPECIFIED', 'BACKGROUND_JOB_PENDING', 'BACKGROUND_JOB_RUNNING', 'BACKGROUND_JOB_SUCCEEDED', 'BACKGROUND_JOB_FAILED', 'BACKGROUND_JOB_CANCELED']]) — Current status of the background job
• attempts (int) — Number of attempts started so far
• max_attempts (int) — Maximum number of attempts allowed for this job
• run_at (int, optional) — Timestamp when the job becomes eligible to run (milliseconds since epoch)
• lease_until (int, optional) — Lease expiration timestamp if the job is currently running (milliseconds since epoch)
• locked_by (str, optional) — Identifier of the worker currently holding the lease, if any
• last_error (str, optional) — Most recent short error message if the job failed
• updated_at (int, optional) — Timestamp when the job row was last updated (milliseconds since epoch)
• failure_stage (Literal['DOCUMENT_PROCESSING_STAGE_LOADING_MEMORY', 'DOCUMENT_PROCESSING_STAGE_PREPARING_DOCUMENT', 'DOCUMENT_PROCESSING_STAGE_EXTRACTING_CONTENT', 'DOCUMENT_PROCESSING_STAGE_STORING_CHUNKS', 'DOCUMENT_PROCESSING_STAGE_GENERATING_EMBEDDINGS', 'DOCUMENT_PROCESSING_STAGE_STORING_EMBEDDINGS', 'DOCUMENT_PROCESSING_STAGE_GENERATING_PAGE_IMAGES', 'DOCUMENT_PROCESSING_STAGE_STORING_PAGE_IMAGES', 'DOCUMENT_PROCESSING_STAGE_FINALIZING_MEMORY'], optional) — Stage of the newest attempt's failure for this memory. Omitted for unknown or legacy failures, failures on another memory in the job, and a newer running or successful attempt. Does not imply retry exhaustion. Use job_id as the support reference.

BackgroundJobAttemptCopy Anchor Link

Telemetry captured for a single execution attempt of a background job

• attempt_id (int) — Identifier of the attempt
• job_id (int) — Identifier of the job that owns this attempt
• started_at (int, optional) — Attempt start timestamp (milliseconds since epoch)
• finished_at (int, optional) — Attempt completion timestamp (milliseconds since epoch)
• ok (bool, optional) — Indicates whether the attempt succeeded (null if still running)
• worker_id (str, optional) — Identifier of the worker processing the attempt
• status_message (str, optional) — Latest status message reported by the worker
• progress_current (int) — Current progress counter value
• progress_total (int, optional) — Total progress target when known
• progress_unit (str, optional) — Unit label associated with the progress counters
• progress_updated_at (int, optional) — Timestamp when progress was last updated (milliseconds since epoch)
• error_message (str, optional) — Short error message recorded when the attempt failed
• error_stacktrace (str, optional) — Stack trace captured when the attempt failed, if available
• failure_stage (Literal['DOCUMENT_PROCESSING_STAGE_LOADING_MEMORY', 'DOCUMENT_PROCESSING_STAGE_PREPARING_DOCUMENT', 'DOCUMENT_PROCESSING_STAGE_EXTRACTING_CONTENT', 'DOCUMENT_PROCESSING_STAGE_STORING_CHUNKS', 'DOCUMENT_PROCESSING_STAGE_GENERATING_EMBEDDINGS', 'DOCUMENT_PROCESSING_STAGE_STORING_EMBEDDINGS', 'DOCUMENT_PROCESSING_STAGE_GENERATING_PAGE_IMAGES', 'DOCUMENT_PROCESSING_STAGE_STORING_PAGE_IMAGES', 'DOCUMENT_PROCESSING_STAGE_FINALIZING_MEMORY'], optional) — Stage of this attempt's failure for this memory. Omitted when unknown or when another memory in the same job failed. This is not the current progress stage and does not imply retry exhaustion. Use job_id as the support reference.

ContextItemCopy Anchor Link

Context item with either text or binary content.

• text (str, optional) — Text content for this context item.
• binary (BinaryContent, optional) — Binary content for this context item.

BinaryContentCopy Anchor Link

Binary content with MIME type for context items.

• content_type (str) — MIME type of the binary content.
• data (str) — Base64-encoded binary data.

SpaceKeyCopy Anchor Link

Space configuration for retrieval operations with optional embedder weight overrides.

• space_id (str) — The UUID for the space to search.
• embedder_weights (list[EmbedderWeight], optional) — Optional per-embedder weight overrides for this space. If not specified, database defaults are used.
• filter (str, optional) — Optional filter expression that must evaluate to true for memories in this space.

EmbedderWeightCopy Anchor Link

Per-embedder weight override for retrieval operations.

• embedder_id (str) — The UUID for the embedder.
• weight (float) — The weight to apply to this embedder's results. Can be positive, negative, or zero.

TokenBudgetCopy Anchor Link

Soft token budget hint for retrieve request processing.

• tokens (int) — Token count for the budget. Must be positive.

HnswOptionsCopy Anchor Link

Optional request-level overrides for pgvector HNSW search settings. Unset fields inherit server defaults.

• ef_search (int, optional) — HNSW candidate list size (1..1000).
• iterative_scan (HnswIterativeScan, optional) — HNSW iterative scan mode. Use POST retrieve for this advanced tuning control.
• max_scan_tuples (int, optional) — Maximum tuples to scan during iterative filtering (1..2147483647).
• scan_mem_multiplier (float, optional) — Multiplier on work_mem for iterative scanning (1.0..1000.0).

HnswIterativeScanCopy Anchor Link

String enum: "ITERATIVE_SCAN_UNSPECIFIED" · "ITERATIVE_SCAN_OFF" · "ITERATIVE_SCAN_RELAXED_ORDER" · "ITERATIVE_SCAN_STRICT_ORDER"

PostProcessorCopy Anchor Link

Post-processor configuration for transforming retrieval results. Custom processors are discovered from installed extensions and must be referenced by their fully qualified factory class name. See https://docs.goodmem.ai/docs/reference/post-processors/chat-post-processor/ for the built-in ChatPostProcessor configuration.

• name (str) — Fully qualified factory class name of the post-processor to apply.
• config (dict[str, Any], optional) — Configuration parameters for the post-processor. Fields depend on the selected processor; see the linked documentation for the built-in ChatPostProcessor schema.

LoggingOptionsCopy Anchor Link

LoggingOptions

• enabled (bool, optional) — Opts this request in to durable server-side request logging. False or omitted does not opt out of admin policy logging.
• caller_attributes (dict[str, Any], optional) — Optional flat scalar attributes attached if this request is persisted by caller opt-in or admin policy logging. Supported value types are string, integer, floating-point, and boolean. At most 32 entries are accepted.

RetrieveMemoryEventCopy Anchor Link

Streaming event from memory retrieval operation

• result_set_boundary (ResultSetBoundary, optional) — Result set boundary marker (BEGIN/END)
• abstract_reply (AbstractReply, optional) — Generated abstractive reply
• retrieved_item (RetrievedItem, optional) — A retrieved memory or chunk
• memory_definition (Memory, optional) — Memory object to add to client's memories array
• status (GoodMemStatus, optional) — Warning or non-fatal status with granular codes (operation continues)

ResultSetBoundaryCopy Anchor Link

Boundary marker for logical result sets in streaming memory retrieval

• result_set_id (str) — Unique identifier for this result set (UUID)
• kind (Optional[Literal['BEGIN', 'END']]) — Type of boundary marker
• stage_name (str) — Free-form label describing the pipeline stage
• expected_items (int, optional) — Hint for progress tracking - expected number of items in this result set

AbstractReplyCopy Anchor Link

Generated abstractive reply with relevance information

• text (str) — Generated abstractive reply text
• relevance_score (float) — Relevance score for this reply (0.0 to 1.0)
• result_set_id (str, optional) — Optional result set ID linking this abstract to a specific result set

RetrievedItemCopy Anchor Link

A retrieved result that can be either a Memory or MemoryChunk

• memory (Memory, optional) — Complete memory object (if retrieved)
• chunk (ChunkReference, optional) — Reference to a memory chunk (if retrieved)

ChunkReferenceCopy Anchor Link

Reference to a memory chunk with pointer to its parent memory

• result_set_id (str) — Result set ID that produced this chunk
• chunk (MemoryChunkResponse) — The memory chunk data
• memory_index (int) — Index of the chunk's memory in the client's memories array
• relevance_score (float) — Relevance score for this chunk (0.0 to 1.0)

MemoryChunkResponseCopy Anchor Link

Memory chunk information

• chunk_id (str) — Unique identifier of the memory chunk
• memory_id (str) — ID of the memory this chunk belongs to
• chunk_sequence_number (int) — Sequence number of this chunk within the memory
• chunk_text (str) — The text content of this chunk
• vector_status (Optional[Literal['UNSPECIFIED', 'PENDING', 'PROCESSING', 'COMPLETED', 'FAILED']]) — Status of vector processing for this chunk
• start_offset (int, optional) — Start offset of this chunk in the original content
• end_offset (int, optional) — End offset of this chunk in the original content
• metadata (dict[str, Any], optional) — Additional metadata for the memory chunk
• created_at (int) — Creation timestamp (milliseconds since epoch)
• updated_at (int) — Last update timestamp (milliseconds since epoch)
• created_by_id (str) — Exact principal or API-key audit actor that created the chunk
• updated_by_id (str) — Exact principal or API-key audit actor that last updated the chunk

RetrieveMemoryStreamCopy Anchor Link

A synchronous context-manager / iterator that streams RetrieveMemoryEvent objects from the server as they arrive over an HTTP streaming response (NDJSON or SSE). Use it with a with statement; iterate over the stream inside the block.

• event (RetrieveMemoryEvent) — Each iteration yields one event from the server.

MemoryPageImageCopy Anchor Link

Metadata for one memory page-image rendition

• memory_id (str) — Memory UUID
• page_index (int) — 0-based page index
• dpi (int) — Render DPI
• content_type (str) — Image MIME type
• image_content_length (int, optional) — Image byte length
• image_content_sha256 (str, optional) — Hex-encoded SHA-256 digest of image content
• created_at (int) — Creation timestamp (milliseconds since epoch)
• updated_at (int) — Last update timestamp (milliseconds since epoch)
• created_by_id (str) — Exact principal or API-key audit actor that created this rendition
• updated_by_id (str) — Exact principal or API-key audit actor that last updated this rendition

JsonMemoryCreationRequestCopy Anchor Link

Request body for creating a new Memory. A Memory represents content stored in a space.

• 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.
• space_id (str) — ID of the space where this memory will be stored
• original_content (str, optional) — Original content as plain text (use either this or original_content_b64)
• original_content_b64 (str, optional) — Original content as base64-encoded binary data (use either this or original_content)
• original_content_ref (str, optional) — Reference to external content location
• content_type (str) — MIME type of the content
• metadata (dict[str, Any], optional) — Additional metadata for the memory. A top-level textual title is an optional document-title hint for embedding providers that support one; blank or non-string titles are ignored. Later metadata edits do not automatically re-embed existing chunks.
• chunking_config (ChunkingConfiguration, optional) — Chunking strategy for this memory (if not provided, uses space default)
• extract_page_images (bool, optional) — Optional hint to extract page images for eligible document types (for example, PDFs)
• file_field (str, optional) — Optional multipart file field name to bind binary content; required when multiple files are uploaded in a batch multipart request.

BatchMemoryResponseCopy Anchor Link

Response containing per-item results for a batch memories operation

• results (list[BatchMemoryResult]) — Array of per-item results
• total_deleted (int, optional) — Total number of memories deleted across all selectors

BatchMemoryResultCopy Anchor Link

Individual item result for a batch memories operation

• success (bool) — Whether this individual operation succeeded
• memory_id (str, optional) — Memory ID associated with this result (present for batch_get errors and batch_delete results)
• memory (Memory, optional) — Created or retrieved memory (present when the operation returns a memory on success)
• error (ErrorDetail, optional) — Error details when success is false
• request_index (int, optional) — 0-based index into the original batch request selectors
• deleted_count (int, optional) — Number of rows deleted by this selector

ErrorDetailCopy Anchor Link

Structured error details for an individual batch operation result

• code (int) — Numeric error code (typically an HTTP or gRPC-derived status code)
• message (str) — Human-readable error message

BatchDeleteMemorySelectorRequestCopy Anchor Link

A single delete selector: either memory_id or filter_selector

• memory_id (str, optional) — Deletes one specific memory by UUID
• filter_selector (FilteredDeleteMemorySelectorRequest, optional) — Deletes a filtered set of memories within a specific space

FilteredDeleteMemorySelectorRequestCopy Anchor Link

Filtered selector scoped to a specific space

• space_id (str) — Space ID scope for the filtered delete
• status_filter (Literal['PENDING', 'PROCESSING', 'COMPLETED', 'FAILED'], optional) — Optional processing status filter (PENDING, PROCESSING, COMPLETED, FAILED)
• filter (str, optional) — Optional metadata filter expression