GoodMem
ReferenceClient SDKsJavaScript

JavaScript SDK

JavaScript client SDK for GoodMem with npm support and streaming capabilities

Server Compatibility

This client version is generated with GoodMem server v1.0.260.

Installation

For Node.js

npm

Install it via:

npm install @pairsystems/goodmem-client --save

Finally, you need to build the module:

npm run build
Local development

To use the library locally without publishing to a remote npm registry, first install the dependencies by changing into the directory containing package.json (and this README). Let's call this JAVASCRIPT_CLIENT_DIR. Then run:

npm install

Next, link it globally in npm with the following, also from JAVASCRIPT_CLIENT_DIR:

npm link

To use the link you just defined in your project, switch to the directory you want to use your @pairsystems/goodmem-client from, and run:

npm link /path/to/<JAVASCRIPT_CLIENT_DIR>

Finally, you need to build the module:

npm run build

git

For browser

The library also works in the browser environment via npm and browserify. After following the above steps with Node.js and installing browserify with npm install -g browserify, perform the following (assuming main.js is your entry file):

browserify main.js > bundle.js

Then include bundle.js in the HTML pages.

Webpack Configuration

Using Webpack you may encounter the following error: "Module not found: Error: Cannot resolve module", most certainly you should disable AMD loader. Add/merge the following section to your webpack config:

module: {
  rules: [
    {
      parser: {
        amd: false
      }
    }
  ]
}

Getting Started

Please follow the installation instruction and execute the following JS code:

var GoodMemClient = require('@pairsystems/goodmem-client');

// Configure the API client
var defaultClient = GoodMemClient.ApiClient.instance;
defaultClient.basePath = "http://localhost:8080";  // Use your server URL

// Configure API key authentication: X-API-Key header
defaultClient.defaultHeaders = {
    "X-API-Key": "your-api-key-here",
    "Content-Type": "application/json",
    "Accept": "application/json"
};


var api = new GoodMemClient.APIKeysApi()
var createApiKeyRequest = {"labels":{"environment":"development","service":"chat-ui"},"expiresAt":1735689600000}; // {CreateApiKeyRequest} API key configuration
api.createApiKey(createApiKeyRequest).then(function(data) {
  console.log('API called successfully. Returned data: ' + data);
}, function(error) {
  console.error(error);
});

Streaming Memory Retrieval

The GoodMem JavaScript client provides a StreamingClient class for real-time streaming memory retrieval. This is the recommended approach for memory retrieval operations.

Supported Formats

The StreamingClient supports two streaming formats:

  • NDJSON (application/x-ndjson) - Newline-delimited JSON (default, recommended)
  • SSE (text/event-stream) - Server-Sent Events

Basic Streaming with ChatPostProcessor

Use retrieveMemoryStreamChat() for streaming with automatic ChatPostProcessor configuration:

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();

// Stream with ChatPostProcessor (NDJSON format)
streamingClient.retrieveMemoryStreamChat(
    controller.signal,
    'your search query',
    ['space-uuid'],
    10,                    // requested size
    true,                  // fetch memory
    false,                 // fetch memory content
    'ndjson',              // format (ndjson or sse)
    'llm-uuid',            // LLM ID
    'reranker-uuid',       // 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);
});

Advanced Streaming with Custom Post-Processor

Use retrieveMemoryStreamAdvanced() for custom post-processor configuration:

// Create advanced request
const request = {
    message: 'your search query',
    spaceIds: ['space-uuid'],
    requestedSize: 10,
    fetchMemory: true,
    fetchMemoryContent: false,
    format: 'ndjson',  // or 'sse'
    postProcessorName: 'com.goodmem.retrieval.postprocess.ChatPostProcessorFactory',
    postProcessorConfig: {
        llm_id: 'llm-uuid',
        reranker_id: 'reranker-uuid',
        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:', event.retrievedItem);
            }
        }
    }).catch(error => {
        console.error('Streaming error:', error);
    });

Choosing Between NDJSON and SSE

  • NDJSON (recommended): Simpler parsing, better for most use cases
  • SSE: Standard browser EventSource API compatible, useful for web applications

Authentication

Configure API key authentication by setting the X-API-Key header:

var GoodMemClient = require("@pairsystems/goodmem-client");

// Configure the API client
var defaultClient = GoodMemClient.ApiClient.instance;
defaultClient.basePath = "http://localhost:8080";  // Use your server URL

// Configure API key authentication
defaultClient.defaultHeaders = {
    "X-API-Key": "your-api-key-here",
    "Content-Type": "application/json",
    "Accept": "application/json"
};

// Create API instances
var apiKeysApi = new GoodMemClient.APIKeysApi();
var spacesApi = new GoodMemClient.SpacesApi();

Getting an API Key

You can create an API key using the APIKeysApi:

var createRequest = {
    labels: {
        "environment": "development",
        "service": "your-app-name"
    }
};

apiKeysApi.createApiKey(createRequest).then(function(response) {
    console.log("API Key created successfully:");
    console.log("Key ID:", response.apiKeyMetadata.apiKeyId);
    console.log("Raw API Key:", response.rawApiKey);
    console.log("Key Prefix:", response.apiKeyMetadata.keyPrefix);
}, function(error) {
    console.error("Error creating API key:", error);
});

Documentation for API Endpoints

The default url is http://localhost:8080

ClassMethodHTTP requestDescription
GoodMemClient.APIKeysApicreateApiKeyPOST /v1/apikeysCreate a new API key
GoodMemClient.APIKeysApideleteApiKeyDELETE /v1/apikeys/{id}Delete an API key
GoodMemClient.APIKeysApilistApiKeysGET /v1/apikeysList API keys
GoodMemClient.APIKeysApiupdateApiKeyPUT /v1/apikeys/{id}Update an API key
GoodMemClient.AdministrationApidrainServerPOST /v1/admin:drainRequest the server to enter drain mode
GoodMemClient.AdministrationApipurgeBackgroundJobsPOST /v1/admin/background-jobs:purgePurge completed background jobs
GoodMemClient.AdministrationApireloadLicensePOST /v1/admin/license:reloadReload the active license from disk
GoodMemClient.EmbeddersApicreateEmbedderPOST /v1/embeddersCreate a new embedder
GoodMemClient.EmbeddersApideleteEmbedderDELETE /v1/embedders/{id}Delete an embedder
GoodMemClient.EmbeddersApigetEmbedderGET /v1/embedders/{id}Get an embedder by ID
GoodMemClient.EmbeddersApilistEmbeddersGET /v1/embeddersList embedders
GoodMemClient.EmbeddersApiupdateEmbedderPUT /v1/embedders/{id}Update an embedder
GoodMemClient.LLMsApicreateLLMPOST /v1/llmsCreate a new LLM
GoodMemClient.LLMsApideleteLLMDELETE /v1/llms/{id}Delete an LLM
GoodMemClient.LLMsApigetLLMGET /v1/llms/{id}Get an LLM by ID
GoodMemClient.LLMsApilistLLMsGET /v1/llmsList LLMs
GoodMemClient.LLMsApiupdateLLMPUT /v1/llms/{id}Update an LLM
GoodMemClient.MemoriesApibatchCreateMemoryPOST /v1/memories:batchCreateCreate multiple memories in a batch
GoodMemClient.MemoriesApibatchDeleteMemoryPOST /v1/memories:batchDeleteDelete memories in batch
GoodMemClient.MemoriesApibatchGetMemoryPOST /v1/memories:batchGetGet multiple memories by ID
GoodMemClient.MemoriesApicreateMemoryPOST /v1/memoriesCreate a new memory
GoodMemClient.MemoriesApideleteMemoryDELETE /v1/memories/{id}Delete a memory
GoodMemClient.MemoriesApigetMemoryGET /v1/memories/{id}Get a memory by ID
GoodMemClient.MemoriesApigetMemoryContentGET /v1/memories/{id}/contentDownload memory content
GoodMemClient.MemoriesApigetMemoryPageImageContentGET /v1/memories/{id}/pages/{pageIndex}/imageDownload memory page image content
GoodMemClient.MemoriesApilistMemoriesGET /v1/spaces/{spaceId}/memoriesList memories in a space
GoodMemClient.MemoriesApilistMemoryPageImagesGET /v1/memories/{id}/pagesList memory page images
GoodMemClient.MemoriesApiretrieveMemoryGET /v1/memories:retrieveStream semantic memory retrieval
GoodMemClient.MemoriesApiretrieveMemoryAdvancedPOST /v1/memories:retrieveAdvanced semantic memory retrieval with JSON
GoodMemClient.OCRApiocrDocumentPOST /v1/ocr:documentRun OCR on a document or image
GoodMemClient.PingApipingOncePOST /v1/ping:onceRun a single ping probe
GoodMemClient.PingApipingStreamPOST /v1/ping:streamStream ping probe results
GoodMemClient.RerankersApicreateRerankerPOST /v1/rerankersCreate a new reranker
GoodMemClient.RerankersApideleteRerankerDELETE /v1/rerankers/{id}Delete a reranker
GoodMemClient.RerankersApigetRerankerGET /v1/rerankers/{id}Get a reranker by ID
GoodMemClient.RerankersApilistRerankersGET /v1/rerankersList rerankers
GoodMemClient.RerankersApiupdateRerankerPUT /v1/rerankers/{id}Update a reranker
GoodMemClient.SpacesApicreateSpacePOST /v1/spacesCreate a new Space
GoodMemClient.SpacesApideleteSpaceDELETE /v1/spaces/{id}Delete a space
GoodMemClient.SpacesApigetSpaceGET /v1/spaces/{id}Get a space by ID
GoodMemClient.SpacesApilistSpacesGET /v1/spacesList spaces
GoodMemClient.SpacesApiupdateSpacePUT /v1/spaces/{id}Update a space
GoodMemClient.SystemApigetSystemInfoGET /v1/system/infoRetrieve server build metadata
GoodMemClient.SystemApiinitializeSystemPOST /v1/system/initInitialize the system
GoodMemClient.UsersApigetCurrentUserGET /v1/users/meGet current user profile
GoodMemClient.UsersApigetUserGET /v1/users/{id}Get a user by ID
GoodMemClient.UsersApigetUserByEmailGET /v1/users/email/{email}Get user by email address

Documentation for Authorization

Authentication required - see configuration below.