GoodMem
ReferenceClient SDKsJavaScript SDK

Memories API

Memories API documentation for JavaScript SDK

All URIs are relative to http://localhost:8080

MethodHTTP requestDescription
batchCreateMemoryPOST /v1/memories:batchCreateCreate multiple memories in a batch
batchDeleteMemoryPOST /v1/memories:batchDeleteDelete multiple memories by ID
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
listMemoriesGET /v1/spaces/{spaceId}/memoriesList memories in a space
retrieveMemoryGET /v1/memories:retrieveStream semantic memory retrieval
retrieveMemoryAdvancedPOST /v1/memories:retrieveAdvanced semantic memory retrieval with JSON

batchCreateMemory

batchCreateMemory(batchMemoryCreationRequest)

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 batchMemoryCreationRequest = new GoodMemClient.BatchMemoryCreationRequest(); // BatchMemoryCreationRequest | Batch memory creation details
apiInstance.batchCreateMemory(batchMemoryCreationRequest).then(() => {
  console.log('API called successfully.');
}, (error) => {
  console.error(error);
});

Parameters

NameTypeDescriptionNotes
batchMemoryCreationRequestBatchMemoryCreationRequestBatch memory creation details

Return type

null (empty response body)

Authorization

No authorization required

HTTP request headers

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

batchDeleteMemory

batchDeleteMemory(batchMemoryDeletionRequest)

Delete multiple memories by ID

Deletes multiple memories in a single operation, with success/failure results for each ID.

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(() => {
  console.log('API called successfully.');
}, (error) => {
  console.error(error);
});

Parameters

NameTypeDescriptionNotes
batchMemoryDeletionRequestBatchMemoryDeletionRequestBatch memory deletion details

Return type

null (empty response body)

Authorization

No authorization required

HTTP request headers

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

batchGetMemory

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(() => {
  console.log('API called successfully.');
}, (error) => {
  console.error(error);
});

Parameters

NameTypeDescriptionNotes
batchMemoryRetrievalRequestBatchMemoryRetrievalRequestBatch memory retrieval details

Return type

null (empty response body)

Authorization

No authorization required

HTTP request headers

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

createMemory

Memory createMemory(memoryCreationRequest)

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. IMPORTANT: This operation is NOT idempotent - each request creates a new memory record. 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, generating a unique UUID, and enqueuing a background processing job.

Example

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

let apiInstance = new GoodMemClient.MemoriesApi();
let memoryCreationRequest = {"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"}}}; // MemoryCreationRequest | Memory creation details
apiInstance.createMemory(memoryCreationRequest).then((data) => {
  console.log('API called successfully. Returned data: ' + data);
}, (error) => {
  console.error(error);
});

Parameters

NameTypeDescriptionNotes
memoryCreationRequestMemoryCreationRequestMemory creation details

Return type

Memory

Authorization

No authorization required

HTTP request headers

  • Content-Type: application/json
  • 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)
  'includeProcessingHistory': false // Boolean | Whether to include background job processing history in the response (defaults to false)
};
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)[optional]
includeProcessingHistoryBooleanWhether to include background job processing history in the response (defaults to false)[optional]

Return type

Memory

Authorization

No authorization required

HTTP request headers

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

getMemoryContent

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(() => {
  console.log('API called successfully.');
}, (error) => {
  console.error(error);
});

Parameters

NameTypeDescriptionNotes
idStringThe unique identifier of the memory to download

Return type

null (empty response body)

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. CRITICAL: The current server implementation does NOT support pagination - the max_results and next_token parameters are IGNORED and all matching memories are returned. 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)
  'statusFilter': "COMPLETED", // String | Filter memories by processing status (PENDING, PROCESSING, COMPLETED, FAILED)
  'maxResults': 100, // Number | IGNORED: The current server implementation does not support pagination for this endpoint. This parameter is documented for future compatibility but will be ignored.
  'nextToken': "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...", // String | IGNORED: The current server implementation does not support pagination for this endpoint. This parameter is documented for future compatibility but will be ignored.
  'sortBy': "created_at", // String | Field to sort by (e.g., 'created_at')
  'sortOrder': "DESCENDING" // String | Sort direction (ASCENDING or DESCENDING)
};
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)[optional]
statusFilterStringFilter memories by processing status (PENDING, PROCESSING, COMPLETED, FAILED)[optional]
maxResultsNumberIGNORED: The current server implementation does not support pagination for this endpoint. This parameter is documented for future compatibility but will be ignored.[optional]
nextTokenStringIGNORED: The current server implementation does not support pagination for this endpoint. This parameter is documented for future compatibility but will be ignored.[optional]
sortByStringField to sort by (e.g., 'created_at')[optional]
sortOrderStringSort direction (ASCENDING or DESCENDING)[optional]

Return type

MemoryListResponse

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