Memories

Methods on this page are called as client.memories.<method>(...) on a Goodmem instance.

Class — ai.pairsys.goodmem.client.api.MemoriesAPI (extends internal MemoriesAPIBase).

import ai.pairsys.goodmem.client.Goodmem;

try (Goodmem client = Goodmem.builder()
        .baseUrl("http://localhost:8080")
        .apiKey("gm_...")
        .build()) {
    // client.memories.<method>(...)
}

Async variants

Every method listed below also exists on ai.pairsys.goodmem.client.api.AsyncMemoriesAPI (accessed via asyncClient.memories on an AsyncGoodmem) with the same parameter list, wrapped in CompletableFuture<T>. Paginated list methods return CompletableFuture<AsyncPage<T>>; streaming methods return CompletableFuture<RetrieveMemoryStream>. See the async client guide for composition patterns.

import ai.pairsys.goodmem.client.AsyncGoodmem;

try (AsyncGoodmem asyncClient = AsyncGoodmem.builder()
        .baseUrl("http://localhost:8080")
        .apiKey("gm_...")
        .build()) {
    asyncClient.memories.<method>(...)  // returns CompletableFuture<T>
}

Method Summary

Modifier and Type	Method	Description
`BatchMemoryResponse`	`batchCreate(JsonBatchMemoryCreationRequest)`	Create multiple memories in a batch
`BatchMemoryResponse`	`batchDelete(BatchMemoryDeletionRequest)`	Delete memories in batch
`BatchMemoryResponse`	`batchGet(BatchMemoryRetrievalRequest)`	Get multiple memories by ID
`byte[]`	`content(String)`	Download memory content
`Memory`	`create(JsonMemoryCreationRequest)`	Create a new memory
`Memory`	`create(String, Path)`	Create a new memory
`void`	`delete(String)`	Delete a memory
`Memory`	`get(String, MemoryGetOptions)`	Get a memory by ID
`Page<Memory>`	`list(String, MemoryListOptions)`	List memories in a space
`Page<MemoryPageImage>`	`pages(String, MemoryPageListOptions)`	List memory page images
`byte[]`	`pagesImage(String, String, MemoryPageImageOptions)`	Download memory page image content
`RetrieveMemoryStream`	`retrieve(RetrieveMemoryRequest)`	Advanced semantic memory retrieval with JSON
`RetrieveMemoryStream`	`retrieve(String, SpaceId...)`	Advanced semantic memory retrieval with JSON
`RetrieveMemoryStream`	`retrieve(String, String...)`	Advanced semantic memory retrieval with JSON

Method Detail

`batchCreate(JsonBatchMemoryCreationRequest)`

BatchMemoryResponse batchCreate(JsonBatchMemoryCreationRequest request)

Javadoc — batchCreate(JsonBatchMemoryCreationRequest)

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

HTTP — POST /v1/memories:batchCreate

Parameters

request (JsonBatchMemoryCreationRequest) — full request payload. The linked Javadoc lists every field and its Builder setter.

Returns — BatchMemoryResponse

Throws

GoodmemException — base type for every SDK error. A concrete HTTP-status subclass (ApiException, NotFoundException, BadRequestException, …) is thrown per response code. All unchecked (RuntimeException). See Errors.

Example

BatchMemoryResponse batchMemoryResponse = client.memories.batchCreate(JsonBatchMemoryCreationRequest.builder()
            // …set required fields…
            .build());

REST equivalent

curl -X POST 'http://localhost:8080/v1/memories:batchCreate' \
  -H "x-api-key: gm_..." \
  -H "Content-Type: application/json" \
  -d '{ /* JsonBatchMemoryCreationRequest fields, see Javadoc */ }'

`batchDelete(BatchMemoryDeletionRequest)`

BatchMemoryResponse batchDelete(BatchMemoryDeletionRequest request)

Javadoc — batchDelete(BatchMemoryDeletionRequest)

Deletes memories using selector entries. Each selector can target either a specific memory ID or a filtered subset scoped to a specific space.

HTTP — POST /v1/memories:batchDelete

Parameters

request (BatchMemoryDeletionRequest) — full request payload. The linked Javadoc lists every field and its Builder setter.

Returns — BatchMemoryResponse

Throws

GoodmemException — base type for every SDK error. A concrete HTTP-status subclass (ApiException, NotFoundException, BadRequestException, …) is thrown per response code. All unchecked (RuntimeException). See Errors.

Example

BatchMemoryResponse batchMemoryResponse = client.memories.batchDelete(BatchMemoryDeletionRequest.builder()
            // …set required fields…
            .build());

REST equivalent

curl -X POST 'http://localhost:8080/v1/memories:batchDelete' \
  -H "x-api-key: gm_..." \
  -H "Content-Type: application/json" \
  -d '{ /* BatchMemoryDeletionRequest fields, see Javadoc */ }'

`batchGet(BatchMemoryRetrievalRequest)`

BatchMemoryResponse batchGet(BatchMemoryRetrievalRequest request)

Javadoc — batchGet(BatchMemoryRetrievalRequest)

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

HTTP — POST /v1/memories:batchGet

Parameters

request (BatchMemoryRetrievalRequest) — full request payload. The linked Javadoc lists every field and its Builder setter.

Returns — BatchMemoryResponse

Throws

GoodmemException — base type for every SDK error. A concrete HTTP-status subclass (ApiException, NotFoundException, BadRequestException, …) is thrown per response code. All unchecked (RuntimeException). See Errors.

Example

BatchMemoryResponse batchMemoryResponse = client.memories.batchGet(BatchMemoryRetrievalRequest.builder()
            // …set required fields…
            .build());

REST equivalent

curl -X POST 'http://localhost:8080/v1/memories:batchGet' \
  -H "x-api-key: gm_..." \
  -H "Content-Type: application/json" \
  -d '{ /* BatchMemoryRetrievalRequest fields, see Javadoc */ }'

`content(String)`

byte[] content(String id)

Javadoc — content(String)

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.

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

Parameters

id (String) — The UUID of the memory to download

Returns — byte[]

Throws

GoodmemException — base type for every SDK error. A concrete HTTP-status subclass (ApiException, NotFoundException, BadRequestException, …) is thrown per response code. All unchecked (RuntimeException). See Errors.

Example

byte[] byte[] = client.memories.content("...");

REST equivalent

curl -X GET 'http://localhost:8080/v1/memories/{id}/content' \
  -H "x-api-key: gm_..."

`create(JsonMemoryCreationRequest)`

Memory create(JsonMemoryCreationRequest request)

Javadoc — create(JsonMemoryCreationRequest)

Create a memory from text content or base64-encoded binary content. Content must be provided via exactly one of originalContent or originalContentB64. When using originalContentB64, contentType is required (the server cannot infer MIME type from base64 bytes). originalContentRef is a metadata pointer (URL) attached to the memory; it does NOT supply content and may accompany originalContent/originalContentB64.

HTTP — POST /v1/memories

Parameters

request (JsonMemoryCreationRequest) — full request payload. The linked Javadoc lists every field and its Builder setter.

Returns — Memory

Throws

GoodmemException — base type for every SDK error. A concrete HTTP-status subclass (ApiException, NotFoundException, BadRequestException, …) is thrown per response code. All unchecked (RuntimeException). See Errors.

Example

Memory memory = client.memories.create(JsonMemoryCreationRequest.builder()
            // …set required fields…
            .build());

REST equivalent

curl -X POST 'http://localhost:8080/v1/memories' \
  -H "x-api-key: gm_..." \
  -H "Content-Type: application/json" \
  -d '{
    "spaceId": "your-space-id",
    "originalContent": "GoodMem stores and retrieves vectorized memories for RAG applications.",
    "metadata": {
      "source": "sdk-doc-test"
    }
  }'

`create(String, Path)`

Memory create(String spaceId, Path filePath)

Javadoc — create(String, Path)

Convenience overload: reads filePath from disk, base64-encodes the bytes, infers a content type via Files.probeContentType, and POSTs a JSON request. For large files consider streaming the bytes yourself rather than reading them fully into memory.

HTTP — POST /v1/memories

Parameters

spaceId (String) — ID of the space where this memory will be stored
filePath (java.nio.file.Path) — local file to upload. Read fully into memory, base64-encoded, and Files.probeContentType is used to infer contentType.

Returns — Memory

Throws

GoodmemException — base type for every SDK error. A concrete HTTP-status subclass (ApiException, NotFoundException, BadRequestException, …) is thrown per response code. All unchecked (RuntimeException). See Errors.

Example

Memory memory = client.memories.create("...", Path.of("/tmp/file.bin"));

REST equivalent

curl -X POST 'http://localhost:8080/v1/memories' \
  -H "x-api-key: gm_..."

`delete(String)`

void delete(String id)

Javadoc — delete(String)

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. Requires DELETE_MEMORY_OWN permission for memories in spaces you own (or DELETE_MEMORY_ANY for admin users to delete any memory). Side effects include permanent removal of the memory record and all associated chunk data.

HTTP — DELETE /v1/memories/{id}

Parameters

id (String) — The UUID of the memory to delete

Returns — None (HTTP 204).

Throws

GoodmemException — base type for every SDK error. A concrete HTTP-status subclass (ApiException, NotFoundException, BadRequestException, …) is thrown per response code. All unchecked (RuntimeException). See Errors.

Example

client.memories.delete("...");

REST equivalent

curl -X DELETE 'http://localhost:8080/v1/memories/{id}' \
  -H "x-api-key: gm_..."

`get(String, MemoryGetOptions)`

Memory get(String id, MemoryGetOptions options)

Javadoc — get(String, MemoryGetOptions)

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.

HTTP — GET /v1/memories/{id}

Parameters

id (String) — The UUID of the memory to retrieve
options (MemoryGetOptions, optional) — typed query parameters; pass null for an empty filter set. The linked Javadoc lists every field.

Returns — Memory

Throws

GoodmemException — base type for every SDK error. A concrete HTTP-status subclass (ApiException, NotFoundException, BadRequestException, …) is thrown per response code. All unchecked (RuntimeException). See Errors.

Example

Memory memory = client.memories.get("...", MemoryGetOptions.builder().build());

REST equivalent

curl -X GET 'http://localhost:8080/v1/memories/{id}' \
  -H "x-api-key: gm_..."

`list(String, MemoryListOptions)`

Page<Memory> list(String spaceId, MemoryListOptions options)

Javadoc — list(String, MemoryListOptions)

Lists memories within a given space. Results are paginated; pass the response's nextToken back as a query parameter to fetch subsequent pages.

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

Parameters

options (MemoryListOptions, optional) — typed query parameters; pass null for an empty filter set. The linked Javadoc lists every field.

Returns — Page<Memory>

Throws

GoodmemException — base type for every SDK error. A concrete HTTP-status subclass (ApiException, NotFoundException, BadRequestException, …) is thrown per response code. All unchecked (RuntimeException). See Errors.

Example

Page<Memory> page = client.memories.list(MemoryListOptions.builder().build());

REST equivalent

curl -X GET 'http://localhost:8080/v1/spaces/{spaceId}/memories' \
  -H "x-api-key: gm_..."

`pages(String, MemoryPageListOptions)`

Page<MemoryPageImage> pages(String id, MemoryPageListOptions options)

Javadoc — pages(String, MemoryPageListOptions)

Lists extracted page-image metadata for a memory with optional filters and pagination.

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

Parameters

id (String) — Memory UUID
options (MemoryPageListOptions, optional) — typed query parameters; pass null for an empty filter set. The linked Javadoc lists every field.

Returns — Page<MemoryPageImage>

Throws

GoodmemException — base type for every SDK error. A concrete HTTP-status subclass (ApiException, NotFoundException, BadRequestException, …) is thrown per response code. All unchecked (RuntimeException). See Errors.

Example

Page<MemoryPageImage> page = client.memories.pages("...", MemoryPageListOptions.builder().build());

REST equivalent

curl -X GET 'http://localhost:8080/v1/memories/{id}/pages' \
  -H "x-api-key: gm_..."

`pagesImage(String, String, MemoryPageImageOptions)`

byte[] pagesImage(String id, String pageIndex, MemoryPageImageOptions options)

Javadoc — pagesImage(String, String, MemoryPageImageOptions)

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.

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

Parameters

id (String) — Memory UUID
options (MemoryPageImageOptions, optional) — typed query parameters; pass null for an empty filter set. The linked Javadoc lists every field.

Returns — byte[]

Throws

GoodmemException — base type for every SDK error. A concrete HTTP-status subclass (ApiException, NotFoundException, BadRequestException, …) is thrown per response code. All unchecked (RuntimeException). See Errors.

Example

byte[] byte[] = client.memories.pagesImage("...", MemoryPageImageOptions.builder().build());

REST equivalent

curl -X GET 'http://localhost:8080/v1/memories/{id}/pages/{pageIndex}/image' \
  -H "x-api-key: gm_..."

`retrieve(RetrieveMemoryRequest)`

RetrieveMemoryStream retrieve(RetrieveMemoryRequest request)

Javadoc — retrieve(RetrieveMemoryRequest)

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

HTTP — POST /v1/memories:retrieve

Parameters

request (RetrieveMemoryRequest) — full request payload. The linked Javadoc lists every field and its Builder setter.

Returns — RetrieveMemoryStream

Throws

GoodmemException — base type for every SDK error. A concrete HTTP-status subclass (ApiException, NotFoundException, BadRequestException, …) is thrown per response code. All unchecked (RuntimeException). See Errors.

Example

RetrieveMemoryStream retrieveMemoryStream = client.memories.retrieve(RetrieveMemoryRequest.builder()
            // …set required fields…
            .build());

REST equivalent

curl -X POST 'http://localhost:8080/v1/memories:retrieve' \
  -H "x-api-key: gm_..." \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What is GoodMem?",
    "requestedSize": 5,
    "spaceKeys": [
      {
        "spaceId": "your-space-id"
      }
    ]
  }'

`retrieve(String, SpaceId...)`

RetrieveMemoryStream retrieve(String message, SpaceId... spaceIds)

Javadoc — retrieve(String, SpaceId...)

Convenience overload: retrieves from the listed spaces with no per-embedder weight overrides or filter. Mirrors Python's memories.retrieve(message=..., space_ids=[...]). For post-processor tuning (llmId, rerankerId, …) or per-space SpaceKey weights, use retrieve(RetrieveMemoryRequest) with a fluent RetrieveMemoryRequest.Builder instead.

HTTP — POST /v1/memories:retrieve

Parameters

message (String) — the natural-language query.
spaceIds (SpaceId...) — typed varargs of spaces to search. Each is wrapped into a SpaceKey with no per-embedder weights or filter. At least one is required; passing an empty array (or null) raises IllegalArgumentException.

Returns — RetrieveMemoryStream

Throws

GoodmemException — base type for every SDK error. A concrete HTTP-status subclass (ApiException, NotFoundException, BadRequestException, …) is thrown per response code. All unchecked (RuntimeException). See Errors.
IllegalArgumentException — if spaceIds is empty or null (at least one space is required).

Example

RetrieveMemoryStream retrieveMemoryStream = client.memories.retrieve("What do you know about ...?", SpaceId.from("00000000-0000-0000-0000-000000000000"));

REST equivalent

curl -X POST 'http://localhost:8080/v1/memories:retrieve' \
  -H "x-api-key: gm_..."

`retrieve(String, String...)`

RetrieveMemoryStream retrieve(String message, String... spaceIds)

Javadoc — retrieve(String, String...)

HTTP — POST /v1/memories:retrieve

Parameters

message (String) — the natural-language query.
spaceIds (String...) — varargs of UUID strings, parsed via SpaceId.from. Same behavior as the typed sibling; rejects empty arrays.

Returns — RetrieveMemoryStream

Throws

GoodmemException — base type for every SDK error. A concrete HTTP-status subclass (ApiException, NotFoundException, BadRequestException, …) is thrown per response code. All unchecked (RuntimeException). See Errors.
IllegalArgumentException — if spaceIds is empty or null (at least one space is required).

Example

RetrieveMemoryStream retrieveMemoryStream = client.memories.retrieve("What do you know about ...?", "00000000-0000-0000-0000-000000000000");

REST equivalent

curl -X POST 'http://localhost:8080/v1/memories:retrieve' \
  -H "x-api-key: gm_..."

Errors

Every method on this page may throw the standard HTTP-error class hierarchy rooted at GoodmemException:

BadRequestException (400), AuthenticationException (401), PermissionDeniedException (403), NotFoundException (404), ConflictException (409), UnprocessableEntityException (422), RateLimitException (429), InternalServerException (5xx), or the generic ApiException for any other 4xx/5xx. All are unchecked (RuntimeException). See Errors.

All error classes live in ai.pairsys.goodmem.client.errors and are unchecked (RuntimeException). Async siblings complete the returned CompletableFuture exceptionally with the same types, wrapped in CompletionException at await time. See Errors on the index for the full table.

Memories

On this page