GoodMem
ReferenceClient SDKsJavaScript

Memories API

Memories API documentation for JavaScript SDK

The default url is http://localhost:8080

MethodHTTP requestDescription
batchCreateMemoryPOST /v1/memories:batchCreateCreate multiple memories in a batch
batchDeleteMemoryPOST /v1/memories:batchDeleteDelete memories in batch
batchGetMemoryPOST /v1/memories:batchGetGet multiple memories by ID
createMemoryPOST /v1/memoriesCreate a new memory
deleteMemoryDELETE /v1/memories/{id}Delete a memory
getMemoryGET /v1/memories/{id}Get a memory by ID
getMemoryContentGET /v1/memories/{id}/contentDownload memory content
getMemoryPageImageContentGET /v1/memories/{id}/pages/{pageIndex}/imageDownload memory page image content
listMemoriesGET /v1/spaces/{spaceId}/memoriesList memories in a space
listMemoryPageImagesGET /v1/memories/{id}/pagesList memory page images
retrieveMemoryGET /v1/memories:retrieveStream semantic memory retrieval
retrieveMemoryAdvancedPOST /v1/memories:retrieveAdvanced semantic memory retrieval with JSON

batchCreateMemory

BatchMemoryResponse batchCreateMemory(jsonBatchMemoryCreationRequest)

Create multiple memories in a batch

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

Example

import GoodMemClient from '@pairsystems/goodmem-client';

let apiInstance = new GoodMemClient.MemoriesApi();
let jsonBatchMemoryCreationRequest = new GoodMemClient.JsonBatchMemoryCreationRequest(); // JsonBatchMemoryCreationRequest | Batch memory creation details. For application/json requests, each item must provide exactly one of originalContent or originalContentB64. For multipart/form-data, provide a requests part and one file part per request.
apiInstance.batchCreateMemory(jsonBatchMemoryCreationRequest).then((data) => {
  console.log('API called successfully. Returned data: ' + data);
}, (error) => {
  console.error(error);
});

Parameters

NameTypeDescriptionNotes
jsonBatchMemoryCreationRequestJsonBatchMemoryCreationRequestBatch memory creation details. For application/json requests, each item must provide exactly one of originalContent or originalContentB64. For multipart/form-data, provide a requests part and one file part per request.

Return type

BatchMemoryResponse

Authorization

No authorization required

HTTP request headers

  • Content-Type: application/json, multipart/form-data
  • Accept: application/json

batchDeleteMemory

BatchMemoryResponse batchDeleteMemory(batchMemoryDeletionRequest)

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.

Example

import GoodMemClient from '@pairsystems/goodmem-client';

let apiInstance = new GoodMemClient.MemoriesApi();
let batchMemoryDeletionRequest = new GoodMemClient.BatchMemoryDeletionRequest(); // BatchMemoryDeletionRequest | Batch memory deletion details
apiInstance.batchDeleteMemory(batchMemoryDeletionRequest).then((data) => {
  console.log('API called successfully. Returned data: ' + data);
}, (error) => {
  console.error(error);
});

Parameters

NameTypeDescriptionNotes
batchMemoryDeletionRequestBatchMemoryDeletionRequestBatch memory deletion details

Return type

BatchMemoryResponse

Authorization

No authorization required

HTTP request headers

  • Content-Type: application/json
  • Accept: application/json

batchGetMemory

BatchMemoryResponse batchGetMemory(batchMemoryRetrievalRequest)

Get multiple memories by ID

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

Example

import GoodMemClient from '@pairsystems/goodmem-client';

let apiInstance = new GoodMemClient.MemoriesApi();
let batchMemoryRetrievalRequest = new GoodMemClient.BatchMemoryRetrievalRequest(); // BatchMemoryRetrievalRequest | Batch memory retrieval details
apiInstance.batchGetMemory(batchMemoryRetrievalRequest).then((data) => {
  console.log('API called successfully. Returned data: ' + data);
}, (error) => {
  console.error(error);
});

Parameters

NameTypeDescriptionNotes
batchMemoryRetrievalRequestBatchMemoryRetrievalRequestBatch memory retrieval details

Return type

BatchMemoryResponse

Authorization

No authorization required

HTTP request headers

  • Content-Type: application/json
  • Accept: application/json

createMemory

Memory createMemory(jsonMemoryCreationRequest)

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. Requires CREATE_MEMORY_OWN permission for spaces you own (or CREATE_MEMORY_ANY for admin users to create in any space). Side effects include creating the memory record and enqueuing a background processing job.

Example

import GoodMemClient from '@pairsystems/goodmem-client';

let apiInstance = new GoodMemClient.MemoriesApi();
let jsonMemoryCreationRequest = {"spaceId":"550e8400-e29b-41d4-a716-446655440000","originalContent":"This is the content to be stored and processed as a memory.","contentType":"text/plain","metadata":{"source":"document","author":"John Doe","tags":["important","research"]},"chunkingConfig":{"recursive":{"chunkSize":500,"chunkOverlap":50,"separators":["\\n\\n","\\n","."],"keepStrategy":"KEEP_END","separatorIsRegex":false,"lengthMeasurement":"CHARACTER_COUNT"}}}; // JsonMemoryCreationRequest | Memory creation details. For application/json requests, provide exactly one of originalContent or originalContentB64. For multipart/form-data, provide a JSON request part plus a file part.
apiInstance.createMemory(jsonMemoryCreationRequest).then((data) => {
  console.log('API called successfully. Returned data: ' + data);
}, (error) => {
  console.error(error);
});

Parameters

NameTypeDescriptionNotes
jsonMemoryCreationRequestJsonMemoryCreationRequestMemory creation details. For application/json requests, provide exactly one of originalContent or originalContentB64. For multipart/form-data, provide a JSON request part plus a file part.

Return type

Memory

Authorization

No authorization required

HTTP request headers

  • Content-Type: application/json, multipart/form-data
  • Accept: application/json

deleteMemory

deleteMemory(id)

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

Example

import GoodMemClient from '@pairsystems/goodmem-client';

let apiInstance = new GoodMemClient.MemoriesApi();
let id = "550e8400-e29b-41d4-a716-446655440000"; // String | The unique identifier of the memory to delete
apiInstance.deleteMemory(id).then(() => {
  console.log('API called successfully.');
}, (error) => {
  console.error(error);
});

Parameters

NameTypeDescriptionNotes
idStringThe unique identifier of the memory to delete

Return type

null (empty response body)

Authorization

No authorization required

HTTP request headers

  • Content-Type: Not defined
  • Accept: Not defined

getMemory

Memory getMemory(id, opts)

Get a memory by ID

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.

Example

import GoodMemClient from '@pairsystems/goodmem-client';

let apiInstance = new GoodMemClient.MemoriesApi();
let id = "550e8400-e29b-41d4-a716-446655440000"; // String | The unique identifier of the memory to retrieve
let opts = {
  'includeContent': false, // Boolean | Whether to include the original content in the response (defaults to false). The snake_case alias include_content is also accepted.
  'includeProcessingHistory': false // Boolean | Whether to include background job processing history in the response (defaults to false). The snake_case alias include_processing_history is also accepted.
};
apiInstance.getMemory(id, opts).then((data) => {
  console.log('API called successfully. Returned data: ' + data);
}, (error) => {
  console.error(error);
});

Parameters

NameTypeDescriptionNotes
idStringThe unique identifier of the memory to retrieve
includeContentBooleanWhether to include the original content in the response (defaults to false). The snake_case alias include_content is also accepted.[optional] [default to false]
includeProcessingHistoryBooleanWhether to include background job processing history in the response (defaults to false). The snake_case alias include_processing_history is also accepted.[optional] [default to false]

Return type

Memory

Authorization

No authorization required

HTTP request headers

  • Content-Type: Not defined
  • Accept: application/json

getMemoryContent

File getMemoryContent(id)

Download memory content

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

Example

import GoodMemClient from '@pairsystems/goodmem-client';

let apiInstance = new GoodMemClient.MemoriesApi();
let id = "550e8400-e29b-41d4-a716-446655440000"; // String | The unique identifier of the memory to download
apiInstance.getMemoryContent(id).then((data) => {
  console.log('API called successfully. Returned data: ' + data);
}, (error) => {
  console.error(error);
});

Parameters

NameTypeDescriptionNotes
idStringThe unique identifier of the memory to download

Return type

File

Authorization

No authorization required

HTTP request headers

  • Content-Type: Not defined
  • Accept: application/octet-stream

getMemoryPageImageContent

File getMemoryPageImageContent(id, pageIndex, opts)

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.

Example

import GoodMemClient from '@pairsystems/goodmem-client';

let apiInstance = new GoodMemClient.MemoriesApi();
let id = "550e8400-e29b-41d4-a716-446655440000"; // String | Memory UUID
let pageIndex = 0; // Number | 0-based page index
let opts = {
  'dpi': 150, // Number | Optional rendition filter. If omitted, the unique page-image rendition for the page is returned; if multiple renditions exist, specify dpi and/or contentType.
  'contentType': "image/png" // String | Optional rendition filter. MIME type of the desired page image, such as image/png. The snake_case alias content_type is also accepted.
};
apiInstance.getMemoryPageImageContent(id, pageIndex, opts).then((data) => {
  console.log('API called successfully. Returned data: ' + data);
}, (error) => {
  console.error(error);
});

Parameters

NameTypeDescriptionNotes
idStringMemory UUID
pageIndexNumber0-based page index
dpiNumberOptional rendition filter. If omitted, the unique page-image rendition for the page is returned; if multiple renditions exist, specify dpi and/or contentType.[optional]
contentTypeStringOptional rendition filter. MIME type of the desired page image, such as image/png. The snake_case alias content_type is also accepted.[optional]

Return type

File

Authorization

No authorization required

HTTP request headers

  • Content-Type: Not defined
  • Accept: application/octet-stream

listMemories

MemoryListResponse listMemories(spaceId, opts)

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. Requires LIST_MEMORY_OWN or LIST_MEMORY_ANY permission. Returns NOT_FOUND if the specified space does not exist.

Example

import GoodMemClient from '@pairsystems/goodmem-client';

let apiInstance = new GoodMemClient.MemoriesApi();
let spaceId = "550e8400-e29b-41d4-a716-446655440000"; // String | The unique identifier of the space containing the memories
let opts = {
  'includeContent': false, // Boolean | Whether to include the original content in the response (defaults to false). The snake_case alias include_content is also accepted.
  'includeProcessingHistory': false, // Boolean | Whether to include background job processing history in the response (defaults to false). The snake_case alias include_processing_history is also accepted.
  'statusFilter': "COMPLETED", // String | Filter memories by processing status (PENDING, PROCESSING, COMPLETED, FAILED). The snake_case alias status_filter is also accepted.
  'filter': "val('$.source') = 'email'", // String | Optional metadata filter expression for list results
  'maxResults': 100, // Number | Maximum number of results per page (defaults to 50, clamped to [1, 500]). The snake_case alias max_results is also accepted.
  'nextToken': "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...", // String | Opaque pagination token for the next page. URL-safe Base64 without padding; do not parse or construct it. The snake_case alias next_token is also accepted.
  'sortBy': "created_at", // String | Field to sort by (e.g., 'created_at'). The snake_case alias sort_by is also accepted.
  'sortOrder': "DESCENDING" // String | Sort direction (ASCENDING or DESCENDING). The snake_case alias sort_order is also accepted.
};
apiInstance.listMemories(spaceId, opts).then((data) => {
  console.log('API called successfully. Returned data: ' + data);
}, (error) => {
  console.error(error);
});

Parameters

NameTypeDescriptionNotes
spaceIdStringThe unique identifier of the space containing the memories
includeContentBooleanWhether to include the original content in the response (defaults to false). The snake_case alias include_content is also accepted.[optional] [default to false]
includeProcessingHistoryBooleanWhether to include background job processing history in the response (defaults to false). The snake_case alias include_processing_history is also accepted.[optional] [default to false]
statusFilterStringFilter memories by processing status (PENDING, PROCESSING, COMPLETED, FAILED). The snake_case alias status_filter is also accepted.[optional]
filterStringOptional metadata filter expression for list results[optional]
maxResultsNumberMaximum number of results per page (defaults to 50, clamped to [1, 500]). The snake_case alias max_results is also accepted.[optional] [default to 50]
nextTokenStringOpaque pagination token for the next page. URL-safe Base64 without padding; do not parse or construct it. The snake_case alias next_token is also accepted.[optional]
sortByStringField to sort by (e.g., 'created_at'). The snake_case alias sort_by is also accepted.[optional]
sortOrderStringSort direction (ASCENDING or DESCENDING). The snake_case alias sort_order is also accepted.[optional]

Return type

MemoryListResponse

Authorization

No authorization required

HTTP request headers

  • Content-Type: Not defined
  • Accept: application/json

listMemoryPageImages

ListMemoryPageImagesResponse listMemoryPageImages(id, opts)

List memory page images

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

Example

import GoodMemClient from '@pairsystems/goodmem-client';

let apiInstance = new GoodMemClient.MemoriesApi();
let id = "550e8400-e29b-41d4-a716-446655440000"; // String | Memory UUID
let opts = {
  'startPageIndex': 0, // Number | Optional lower bound for returned page indices, inclusive. The snake_case alias start_page_index is also accepted.
  'endPageIndex': 10, // Number | Optional upper bound for returned page indices, inclusive. The snake_case alias end_page_index is also accepted.
  'dpi': 150, // Number | Optional rendition filter for page-image DPI.
  'contentType': "image/png", // String | Optional rendition filter for page-image MIME type, such as image/png. The snake_case alias content_type is also accepted.
  'maxResults': 50, // Number | Maximum number of results per page. The snake_case alias max_results is also accepted.
  'nextToken': "eyJzdGFydCI6NTAsIm1lbW9yeUlkIjoiLi4uIn0" // String | Opaque pagination token for the next page. The snake_case alias next_token is also accepted. Do not parse or construct it.
};
apiInstance.listMemoryPageImages(id, opts).then((data) => {
  console.log('API called successfully. Returned data: ' + data);
}, (error) => {
  console.error(error);
});

Parameters

NameTypeDescriptionNotes
idStringMemory UUID
startPageIndexNumberOptional lower bound for returned page indices, inclusive. The snake_case alias start_page_index is also accepted.[optional]
endPageIndexNumberOptional upper bound for returned page indices, inclusive. The snake_case alias end_page_index is also accepted.[optional]
dpiNumberOptional rendition filter for page-image DPI.[optional]
contentTypeStringOptional rendition filter for page-image MIME type, such as image/png. The snake_case alias content_type is also accepted.[optional]
maxResultsNumberMaximum number of results per page. The snake_case alias max_results is also accepted.[optional]
nextTokenStringOpaque pagination token for the next page. The snake_case alias next_token is also accepted. Do not parse or construct it.[optional]

Return type

ListMemoryPageImagesResponse

Authorization

No authorization required

HTTP request headers

  • Content-Type: Not defined
  • Accept: application/json

retrieveMemory

📡 Stream Semantic Memory Retrieval

Use the StreamingClient class for streaming memory retrieval:

Working Example with Streaming Client

const GoodMemClient = require('@pairsystems/goodmem-client');
const { StreamingClient } = GoodMemClient;

// Configure client
const defaultClient = GoodMemClient.ApiClient.instance;
defaultClient.basePath = 'http://localhost:8080';
defaultClient.defaultHeaders = {
    'X-API-Key': 'your-api-key'
};

// Create streaming client
const streamingClient = new StreamingClient(defaultClient);

// Create abort controller for cancellation
const controller = new AbortController();

// Stream with ChatPostProcessor
streamingClient.retrieveMemoryStreamChat(
    controller.signal,
    'your search query',                          // message
    ['550e8400-e29b-41d4-a716-446655440000'],     // space IDs
    10,                                            // requested size
    true,                                          // fetch memory
    false,                                         // fetch memory content
    'ndjson',                                      // format (ndjson or sse)
    '550e8400-e29b-41d4-a716-446655440001',       // LLM ID
    '550e8400-e29b-41d4-a716-446655440000',       // reranker ID
    0.5,                                           // relevance threshold
    0.3,                                           // LLM temperature
    10,                                            // max results
    true                                           // chronological resort
).then(async (stream) => {
    for await (const event of stream) {
        if (event.abstractReply) {
            console.log('Abstract:', event.abstractReply.text);
        } else if (event.retrievedItem && event.retrievedItem.memory) {
            console.log('Memory:', event.retrievedItem.memory);
        }
    }
}).catch(error => {
    console.error('Streaming error:', error);
});

Parameters

Same parameters as the standard method, with additional ChatPostProcessor parameters:

  • ppLlmId: UUID of LLM for abstract generation
  • ppRerankerId: UUID of reranker for result reranking
  • ppRelevanceThreshold: Minimum relevance score
  • ppLlmTemp: LLM temperature for generation
  • ppMaxResults: Maximum results to return
  • ppChronologicalResort: Whether to resort by creation time
  • format: Streaming format ('ndjson' or 'sse')

Return type

Promise resolving to AsyncIterableIterator of streaming events

Authorization

ApiKeyAuth

retrieveMemoryAdvanced

📡 Advanced Stream Semantic Memory Retrieval

Use the StreamingClient class for advanced streaming memory retrieval with custom post-processor configuration:

Working Example with Streaming Client

const GoodMemClient = require('@pairsystems/goodmem-client');
const { StreamingClient } = GoodMemClient;

// Configure client
const defaultClient = GoodMemClient.ApiClient.instance;
defaultClient.basePath = 'http://localhost:8080';
defaultClient.defaultHeaders = {
    'X-API-Key': 'your-api-key'
};

// Create streaming client
const streamingClient = new StreamingClient(defaultClient);

// Create abort controller
const controller = new AbortController();

// Create advanced request with custom post-processor
const request = {
    message: 'your search query',
    spaceIds: ['550e8400-e29b-41d4-a716-446655440000'],
    requestedSize: 10,
    fetchMemory: true,
    fetchMemoryContent: false,
    format: 'ndjson',  // or 'sse'
    postProcessorName: 'com.goodmem.retrieval.postprocess.ChatPostProcessorFactory',
    postProcessorConfig: {
        llm_id: '550e8400-e29b-41d4-a716-446655440001',
        reranker_id: '550e8400-e29b-41d4-a716-446655440000',
        relevance_threshold: 0.5,
        llm_temp: 0.3,
        max_results: 10,
        chronological_resort: true
    }
};

// Execute advanced streaming
streamingClient.retrieveMemoryStreamAdvanced(controller.signal, request)
    .then(async (stream) => {
        for await (const event of stream) {
            if (event.abstractReply) {
                console.log('Abstract:', event.abstractReply.text);
            } else if (event.retrievedItem) {
                console.log('Retrieved item:', event.retrievedItem);
            }
        }
    }).catch(error => {
        console.error('Streaming error:', error);
    });

Parameters

Use AdvancedMemoryStreamRequest with:

  • message: Query message
  • spaceIds: Array of space UUIDs
  • requestedSize: Maximum memories to retrieve
  • fetchMemory: Whether to fetch memory definitions
  • fetchMemoryContent: Whether to fetch original content
  • format: Streaming format ('ndjson' or 'sse')
  • postProcessorName: Name of custom post-processor
  • postProcessorConfig: Configuration object for the post-processor

Return type

Promise resolving to AsyncIterableIterator of streaming events

Authorization

ApiKeyAuth