GoodMemGoodMem
ReferenceClient SDKsRust

Memories

Rust memories API reference: typed methods, request options, return values, and resource models.

goodmem::api::Memories

Access this service with client.memories().

pub struct Memories<'a> {
    /* private fields */
}

Methods

MethodHTTPPath
batch_createPOST/v1/memories:batchCreate
batch_create_filesPOST/v1/memories:batchCreate
batch_create_filePOST/v1/memories:batchCreate
batch_deletePOST/v1/memories:batchDelete
batch_getPOST/v1/memories:batchGet
contentGET/v1/memories/{id}/content
createPOST/v1/memories
create_filePOST/v1/memories
deleteDELETE/v1/memories/{id}
getGET/v1/memories/{id}
listGET/v1/spaces/{spaceId}/memories
list_pagesGET/v1/spaces/{spaceId}/memories
pagesGET/v1/memories/{id}/pages
pages_imageGET/v1/memories/{id}/pages/{pageIndex}/image
retrievePOST/v1/memories:retrieve

Errors and cancellation

Calls return Result<T>. See Error for validation, HTTP, transport, decoding, and timeout failures. Stream items can also return errors after the call succeeds.

Pagination helpers fetch pages when polled. Drop a page or event stream to cancel further work.

Implementations

impl Memories<'_>

batch_create

pub async fn batch_create( &self, body: &JsonBatchMemoryCreationRequest, ) -> Result<BatchMemoryResponse>

Create multiple memories in a batch

Creates multiple memories in a single operation, with individual success/failure results. Each item requires CREATE_MEMORY on its containing space; authorization failures are reported in the corresponding item result.

Errors include local validation, HTTP failures, and malformed responses.

HTTP: POST /v1/memories:batchCreate

batch_create_files

pub async fn batch_create_files( &self, metadata: &JsonBatchMemoryCreationRequest, files: Vec<UploadFile>, ) -> Result<BatchMemoryResponse>

Upload a batch through memories.batch_create with one named file part per request. Each request's file_field must match a distinct file's field_name. A one-request, one-file batch may omit file_field. Inline content fields must be absent from every request.

Creates multiple memories in a single operation, with individual success/failure results. Each item requires CREATE_MEMORY on its containing space; authorization failures are reported in the corresponding item result.

HTTP: POST /v1/memories:batchCreate

batch_create_file

pub async fn batch_create_file( &self, metadata: &JsonBatchMemoryCreationRequest, filename: &str, content_type: &str, data: Vec<u8>, ) -> Result<BatchMemoryResponse>

Upload a file through memories.batch_create. Content fields must be absent from metadata.

Creates multiple memories in a single operation, with individual success/failure results. Each item requires CREATE_MEMORY on its containing space; authorization failures are reported in the corresponding item result.

HTTP: POST /v1/memories:batchCreate

batch_delete

pub async fn batch_delete( &self, body: &BatchMemoryDeletionRequest, ) -> Result<BatchMemoryResponse>

Delete memories in batch

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.

Errors include local validation, HTTP failures, and malformed responses.

HTTP: POST /v1/memories:batchDelete

batch_get

pub async fn batch_get( &self, body: &BatchMemoryRetrievalRequest, ) -> Result<BatchMemoryResponse>

Get multiple memories by ID

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.

Errors include local validation, HTTP failures, and malformed responses.

HTTP: POST /v1/memories:batchGet

content

pub async fn content( &self, id: impl std::fmt::Display, options: &MemoriesContentOptions, ) -> Result<Download>

Download memory content

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 originalContentRef 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.

Errors include local validation, HTTP failures, and malformed responses.

HTTP: GET /v1/memories/{id}/content

create

pub async fn create(&self, body: &JsonMemoryCreationRequest) -> Result<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 memoryId is omitted, the server generates a new UUID and retries are not idempotent. If the client supplies a stable memoryId, 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.

AUTHORIZATION: Requires CREATE_MEMORY on the containing space. Side effects include creating the memory record and enqueuing a background processing job.

Errors include local validation, HTTP failures, and malformed responses.

HTTP: POST /v1/memories

create_file

pub async fn create_file( &self, metadata: &JsonMemoryCreationRequest, filename: &str, content_type: &str, data: Vec<u8>, ) -> Result<Memory>

Upload a file through memories.create. Content fields must be absent from metadata. The part name uses trimmed file_field, defaulting to file when absent or blank.

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 memoryId is omitted, the server generates a new UUID and retries are not idempotent. If the client supplies a stable memoryId, 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.

AUTHORIZATION: Requires CREATE_MEMORY on the containing space. Side effects include creating the memory record and enqueuing a background processing job.

HTTP: POST /v1/memories

delete

pub async fn delete(&self, id: impl std::fmt::Display) -> Result<()>

Delete a memory

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.

Errors include local validation, HTTP failures, and malformed responses.

HTTP: DELETE /v1/memories/{id}

get

pub async fn get( &self, id: impl std::fmt::Display, options: &MemoriesGetOptions, ) -> Result<Memory>

Get a memory by ID

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.

Errors include local validation, HTTP failures, and malformed responses.

HTTP: GET /v1/memories/{id}

list

pub async fn list( &self, space_id: impl std::fmt::Display, options: &MemoriesListOptions, ) -> Result<MemoryListResponse>

List memories in a space

Lists all memories within a given space. Pagination is supported via maxResults and nextToken (opaque). nextToken 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.

AUTHORIZATION: Requires LIST_MEMORY on the exact containing space. Each returned memory must also satisfy READ_MEMORY, either directly or through DIRECT_MEMBERS_OF that space. Both predicates are evaluated in PostgreSQL. Returns NOT_FOUND if the specified space does not exist.

Errors include local validation, HTTP failures, and malformed responses.

HTTP: GET /v1/spaces/{spaceId}/memories

list_pages

pub fn list_pages( &self, space_id: impl std::fmt::Display, options: &MemoriesListOptions, ) -> Result<EventStream<MemoryListResponse>>

Lazily fetch pages for memories.list. Drop the stream to cancel.

Lists all memories within a given space. Pagination is supported via maxResults and nextToken (opaque). nextToken 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.

AUTHORIZATION: Requires LIST_MEMORY on the exact containing space. Each returned memory must also satisfy READ_MEMORY, either directly or through DIRECT_MEMBERS_OF that space. Both predicates are evaluated in PostgreSQL. Returns NOT_FOUND if the specified space does not exist.

HTTP: GET /v1/spaces/{spaceId}/memories

pages

pub async fn pages( &self, id: impl std::fmt::Display, options: &MemoriesPagesOptions, ) -> Result<ListMemoryPageImagesResponse>

List memory page images

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.

Errors include local validation, HTTP failures, and malformed responses.

HTTP: GET /v1/memories/{id}/pages

pages_image

pub async fn pages_image( &self, id: impl std::fmt::Display, page_index: impl std::fmt::Display, options: &MemoriesPagesImageOptions, ) -> Result<Download>

Download memory page image content

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.

Errors include local validation, HTTP failures, and malformed responses.

HTTP: GET /v1/memories/{id}/pages/{pageIndex}/image

retrieve

pub async fn retrieve( &self, body: &RetrieveMemoryRequest, options: &MemoriesRetrieveOptions, ) -> Result<EventStream<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. When executable extensions are disabled at startup, custom post-processors return HTTP 412 after request-shape validation and before streaming starts; built-in chat processing remains available.

AUTHORIZATION: Every requested space must grant LIST_MEMORY on that exact space and READ_MEMORY through DIRECT_MEMBERS_OF the space before retrieval begins.

Errors include local validation, HTTP failures, and malformed responses.

HTTP: POST /v1/memories:retrieve

Types

Trait implementations

  • Clone (derived)
  • Copy (derived)
  • Debug (derived)

On this page