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
| Method | HTTP | Path |
|---|---|---|
batch_create | POST | /v1/memories:batchCreate |
batch_create_files | POST | /v1/memories:batchCreate |
batch_create_file | POST | /v1/memories:batchCreate |
batch_delete | POST | /v1/memories:batchDelete |
batch_get | POST | /v1/memories:batchGet |
content | GET | /v1/memories/{id}/content |
create | POST | /v1/memories |
create_file | POST | /v1/memories |
delete | DELETE | /v1/memories/{id} |
get | GET | /v1/memories/{id} |
list | GET | /v1/spaces/{spaceId}/memories |
list_pages | GET | /v1/spaces/{spaceId}/memories |
pages | GET | /v1/memories/{id}/pages |
pages_image | GET | /v1/memories/{id}/pages/{pageIndex}/image |
retrieve | POST | /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
BatchMemoryDeletionRequestBatchMemoryResponseBatchMemoryRetrievalRequestJsonBatchMemoryCreationRequestJsonMemoryCreationRequestListMemoryPageImagesResponseMemoriesContentOptionsMemoriesGetOptionsMemoriesListOptionsMemoriesPagesImageOptionsMemoriesPagesOptionsMemoriesRetrieveOptionsMemoryMemoryListResponseRetrieveMemoryEventRetrieveMemoryRequest
Trait implementations
Clone(derived)Copy(derived)Debug(derived)