Memories

Memory CRUD, retrieval, and batch operations.

Methods on this page are called through client.memories.

client.memories.batchCreate

client.memories.batchCreate(request: JsonBatchMemoryCreationRequest, requestOptions?: RequestOptions): Promise<BatchMemoryResponseShape>

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

Parameters

Returns: Promise<BatchMemoryResponseShape>

Example

const batchCreate = await client.memories.batchCreate({
  requests: [
    { spaceId: "your-space-id", originalContent: "First memory" },
    { spaceId: "your-space-id", originalContent: "Second memory" },
  ],
});
console.log(batchCreate.results.length);

client.memories.batchDelete

client.memories.batchDelete(request: BatchMemoryDeletionRequest, requestOptions?: RequestOptions): Promise<BatchMemoryResponseShape>

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.

HTTP: POST /v1/memories:batchDelete

Parameters

Returns: Promise<BatchMemoryResponseShape>

Example

await client.memories.batchDelete({
  requests: [
    { memoryId: "your-memory-id-1" },
    { memoryId: "your-memory-id-2" },
  ],
});

client.memories.batchGet

client.memories.batchGet(request: BatchMemoryRetrievalRequest, requestOptions?: RequestOptions): Promise<BatchMemoryResponseShape>

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.

HTTP: POST /v1/memories:batchGet

Parameters

Returns: Promise<BatchMemoryResponseShape>

Example

const batchGet = await client.memories.batchGet({
  memoryIds: ["your-memory-id-1", "your-memory-id-2"],
  includeContent: false,
});
console.log(batchGet.results.length);

client.memories.content

client.memories.content(id: string, requestOptions?: RequestOptions): Promise<Uint8Array>

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.

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

Parameters

Returns: Promise<Uint8Array>

Example

const content = await client.memories.content("your-memory-id");
console.log(new TextDecoder().decode(content));

client.memories.create

client.memories.create(request: JsonMemoryCreationRequest, requestOptions?: RequestOptions): Promise<MemoryResponseShape>

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

Parameters

Returns: Promise<MemoryResponseShape>

Example

Example 1:

const memory = await client.memories.create({
  spaceId: "your-space-id",
  originalContent: "GoodMem stores and retrieves vectorized memories for RAG.",
  metadata: { source: "docs" },
});

Example 2:

const minimalPdf = `%PDF-1.4
1 0 obj
<< /Type /Catalog /Pages 2 0 R >>
endobj
2 0 obj
<< /Type /Pages /Kids [3 0 R] /Count 1 >>
endobj
3 0 obj
<< /Type /Page /Parent 2 0 R /MediaBox [0 0 612 792] /Resources << /Font << /F1 5 0 R >> >> /Contents 4 0 R >>
endobj
4 0 obj
<< /Length 51 >>
stream
BT /F1 12 Tf 72 720 Td (GoodMem example PDF) Tj ET
endstream
endobj
5 0 obj
<< /Type /Font /Subtype /Type1 /BaseFont /Helvetica >>
endobj
xref
0 6
0000000000 65535 f
0000000009 00000 n
0000000058 00000 n
0000000115 00000 n
0000000241 00000 n
0000000341 00000 n
trailer
<< /Size 6 /Root 1 0 R >>
startxref
411
%%EOF
`;
const pdfFile = new Blob([minimalPdf], { type: "application/pdf" });
  const pdfMemory = await client.memories.createFromFile({
    spaceId: "your-space-id",
    file: pdfFile,
    filename: "guide.pdf",
    metadata: { source: "FILE" },
    extractPageImages: true,
  });

Example 3:

const referencedMemory = await client.memories.create({
  spaceId: "your-space-id",
  originalContent: "Content mirrored from external storage.",
  originalContentRef: "s3://bucket/object.txt",
  metadata: { source: "external" },
});

client.memories.delete

client.memories.delete(id: string, requestOptions?: RequestOptions): Promise<void>

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.

HTTP: DELETE /v1/memories/{id}

Parameters

Returns: Promise<void>

Example

await client.memories.delete("your-memory-id");

client.memories.get

client.memories.get(id: string, options?: MemoriesGetOptions, requestOptions?: RequestOptions): Promise<MemoryResponseShape>

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.

HTTP: GET /v1/memories/{id}

Parameters

Returns: Promise<MemoryResponseShape>

Example

const fetchedMemory = await client.memories.get("your-memory-id", {
  includeContent: true,
});
console.log(fetchedMemory.processingStatus);

client.memories.list

client.memories.list(spaceId: string, options?: MemoriesListOptions, requestOptions?: RequestOptions): Promise<Page<MemoryResponseShape>>

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

Parameters

Returns: Promise<Page<MemoryResponseShape>>

Example

Example 1:

for await (const item of await client.memories.list("your-space-id")) {
  console.log(item.memoryId, item.processingStatus);
}

Example 2:

for await (const item of await client.memories.list("your-space-id", {
  filter: 'metadata.source == "docs"',
  maxResults: 10,
})) {
  console.log(item.memoryId);
}

client.memories.pages

client.memories.pages(id: string, options?: MemoriesPagesOptions, requestOptions?: RequestOptions): Promise<Page<MemoryPageImageResponseShape>>

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.

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

Parameters

Returns: Promise<Page<MemoryPageImageResponseShape>>

Example

for await (const image of await client.memories.pages("your-memory-id", { maxResults: 10 })) {
  console.log(image.pageIndex, image.contentType);
}

client.memories.pagesImage

client.memories.pagesImage(id: string, pageIndex: number, options?: MemoriesPagesImageOptions, requestOptions?: RequestOptions): Promise<Uint8Array>

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.

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

Parameters

Returns: Promise<Uint8Array>

Example

const pageImage = await client.memories.pagesImage("your-memory-id", 0, {
  contentType: "image/png",
});
console.log(pageImage.byteLength);

client.memories.retrieve

client.memories.retrieve(request: MemoriesRetrieveParams, requestOptions?: RequestOptions): AsyncIterable<RetrieveMemoryEventResponseShape>

Streams semantic retrieval results with full feature support including context items and embedder weight overrides, per-space filters, and request-level HNSW tuning.

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

HTTP: POST /v1/memories:retrieve

Parameters

Returns: AsyncIterable<RetrieveMemoryEventResponseShape>

Example

Example 1:

for await (const event of client.memories.retrieve("What is GoodMem?", {
  spaceIds: ["your-space-id"],
  requestedSize: 5,
})) {
  console.log(event.retrievedItem?.chunk?.chunk.chunkText);
}

Example 2:

for await (const event of client.memories.retrieve("Summarize the memories.", {
  spaceIds: ["your-space-id"],
  llmId: "your-llm-id",
  outputBudget: { tokens: 2048 },
})) {
  console.log(event.abstractReply?.text);
}

Example 3:

for await (const event of client.memories.retrieve("What is GoodMem?", {
  spaceIds: ["your-space-id"],
  requestedSize: 5,
  logging: {
    enabled: true,
    callerAttributes: {
      testCase: "docs_logging_opt_in",
      attempt: 1,
    },
  },
})) {
  console.log(event.retrievedItem?.chunk?.chunk.chunkText);
}

Data Models

Enum Values

HnswIterativeScan

ITERATIVE_SCAN_UNSPECIFIED, ITERATIVE_SCAN_OFF, ITERATIVE_SCAN_RELAXED_ORDER, ITERATIVE_SCAN_STRICT_ORDER

Interfaces

AbstractReply

Generated abstractive reply with relevance information

BackgroundJobAttempt

Telemetry captured for a single execution attempt of a background job

BackgroundJobSummary

Summary of the most recent background job execution for a resource

BatchDeleteMemorySelectorRequest

A single delete selector: either memoryId or filterSelector

BatchMemoryDeletionRequest

Request body for deleting memories using ID and/or filtered selectors

BatchMemoryResponse

Response containing per-item results for a batch memories operation

BatchMemoryResult

Individual item result for a batch memories operation

BatchMemoryRetrievalRequest

Request body for retrieving multiple memories by their IDs

BinaryContent

Binary content with MIME type for context items.

ChunkReference

Reference to a memory chunk with pointer to its parent memory

ContextItem

Context item with either text or binary content.

EmbedderWeight

Per-embedder weight override for retrieval operations.

ErrorDetail

Structured error details for an individual batch operation result

FilteredDeleteMemorySelectorRequest

Filtered selector scoped to a specific space

HnswOptions

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

JsonBatchMemoryCreationRequest

Request body for creating multiple memories via application/json.

JsonMemoryCreationRequest

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

ListMemoryPageImagesResponse

Page of memory page-image metadata

LoggingOptions

Memory

Memory object containing stored content and metadata

MemoryChunkResponse

Memory chunk information

MemoryListResponse

Response containing a list of memories within a space

MemoryPageImage

Metadata for one memory page-image rendition

PostProcessor

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.

ProcessingHistory

Background job execution history associated with a memory

ResultSetBoundary

Boundary marker for logical result sets in streaming memory retrieval

RetrieveMemoryEvent

Streaming event from memory retrieval operation

RetrieveMemoryRequest

Request body for semantic memory retrieval with optional embedder weight overrides.

RetrievedItem

A retrieved result that can be either a Memory or MemoryChunk

SpaceKey

Space configuration for retrieval operations with optional embedder weight overrides.

TokenBudget

Soft token budget hint for retrieve request processing.

Response Shapes

Response shape types model values returned by the SDK after forward-compatible unknown enum strings are coerced to null.

AbstractReplyResponseShape

BackgroundJobAttemptResponseShape

BackgroundJobSummaryResponseShape

BatchMemoryResponseShape

BatchMemoryResultResponseShape

ChunkReferenceResponseShape

ErrorDetailResponseShape

ListMemoryPageImagesResponseShape

MemoryResponseShape

MemoryChunkResponseShape

MemoryListResponseShape

MemoryPageImageResponseShape

ProcessingHistoryResponseShape

ResultSetBoundaryResponseShape

RetrieveMemoryEventResponseShape

RetrievedItemResponseShape

Type constraint: RetrievedItemResponseShape = RequireExactlyOne<RetrievedItemResponseShapeBase, "chunk" \| "memory">