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 --saveFinally, you need to build the module:
npm run buildLocal 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 installNext, link it globally in npm with the following, also from JAVASCRIPT_CLIENT_DIR:
npm linkTo 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 buildgit
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.jsThen 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
| Class | Method | HTTP request | Description |
|---|---|---|---|
| GoodMemClient.APIKeysApi | createApiKey | POST /v1/apikeys | Create a new API key |
| GoodMemClient.APIKeysApi | deleteApiKey | DELETE /v1/apikeys/{id} | Delete an API key |
| GoodMemClient.APIKeysApi | listApiKeys | GET /v1/apikeys | List API keys |
| GoodMemClient.APIKeysApi | updateApiKey | PUT /v1/apikeys/{id} | Update an API key |
| GoodMemClient.AdministrationApi | drainServer | POST /v1/admin:drain | Request the server to enter drain mode |
| GoodMemClient.AdministrationApi | purgeBackgroundJobs | POST /v1/admin/background-jobs:purge | Purge completed background jobs |
| GoodMemClient.AdministrationApi | reloadLicense | POST /v1/admin/license:reload | Reload the active license from disk |
| GoodMemClient.EmbeddersApi | createEmbedder | POST /v1/embedders | Create a new embedder |
| GoodMemClient.EmbeddersApi | deleteEmbedder | DELETE /v1/embedders/{id} | Delete an embedder |
| GoodMemClient.EmbeddersApi | getEmbedder | GET /v1/embedders/{id} | Get an embedder by ID |
| GoodMemClient.EmbeddersApi | listEmbedders | GET /v1/embedders | List embedders |
| GoodMemClient.EmbeddersApi | updateEmbedder | PUT /v1/embedders/{id} | Update an embedder |
| GoodMemClient.LLMsApi | createLLM | POST /v1/llms | Create a new LLM |
| GoodMemClient.LLMsApi | deleteLLM | DELETE /v1/llms/{id} | Delete an LLM |
| GoodMemClient.LLMsApi | getLLM | GET /v1/llms/{id} | Get an LLM by ID |
| GoodMemClient.LLMsApi | listLLMs | GET /v1/llms | List LLMs |
| GoodMemClient.LLMsApi | updateLLM | PUT /v1/llms/{id} | Update an LLM |
| GoodMemClient.MemoriesApi | batchCreateMemory | POST /v1/memories:batchCreate | Create multiple memories in a batch |
| GoodMemClient.MemoriesApi | batchDeleteMemory | POST /v1/memories:batchDelete | Delete memories in batch |
| GoodMemClient.MemoriesApi | batchGetMemory | POST /v1/memories:batchGet | Get multiple memories by ID |
| GoodMemClient.MemoriesApi | createMemory | POST /v1/memories | Create a new memory |
| GoodMemClient.MemoriesApi | deleteMemory | DELETE /v1/memories/{id} | Delete a memory |
| GoodMemClient.MemoriesApi | getMemory | GET /v1/memories/{id} | Get a memory by ID |
| GoodMemClient.MemoriesApi | getMemoryContent | GET /v1/memories/{id}/content | Download memory content |
| GoodMemClient.MemoriesApi | getMemoryPageImageContent | GET /v1/memories/{id}/pages/{pageIndex}/image | Download memory page image content |
| GoodMemClient.MemoriesApi | listMemories | GET /v1/spaces/{spaceId}/memories | List memories in a space |
| GoodMemClient.MemoriesApi | listMemoryPageImages | GET /v1/memories/{id}/pages | List memory page images |
| GoodMemClient.MemoriesApi | retrieveMemory | GET /v1/memories:retrieve | Stream semantic memory retrieval |
| GoodMemClient.MemoriesApi | retrieveMemoryAdvanced | POST /v1/memories:retrieve | Advanced semantic memory retrieval with JSON |
| GoodMemClient.OCRApi | ocrDocument | POST /v1/ocr:document | Run OCR on a document or image |
| GoodMemClient.PingApi | pingOnce | POST /v1/ping:once | Run a single ping probe |
| GoodMemClient.PingApi | pingStream | POST /v1/ping:stream | Stream ping probe results |
| GoodMemClient.RerankersApi | createReranker | POST /v1/rerankers | Create a new reranker |
| GoodMemClient.RerankersApi | deleteReranker | DELETE /v1/rerankers/{id} | Delete a reranker |
| GoodMemClient.RerankersApi | getReranker | GET /v1/rerankers/{id} | Get a reranker by ID |
| GoodMemClient.RerankersApi | listRerankers | GET /v1/rerankers | List rerankers |
| GoodMemClient.RerankersApi | updateReranker | PUT /v1/rerankers/{id} | Update a reranker |
| GoodMemClient.SpacesApi | createSpace | POST /v1/spaces | Create a new Space |
| GoodMemClient.SpacesApi | deleteSpace | DELETE /v1/spaces/{id} | Delete a space |
| GoodMemClient.SpacesApi | getSpace | GET /v1/spaces/{id} | Get a space by ID |
| GoodMemClient.SpacesApi | listSpaces | GET /v1/spaces | List spaces |
| GoodMemClient.SpacesApi | updateSpace | PUT /v1/spaces/{id} | Update a space |
| GoodMemClient.SystemApi | getSystemInfo | GET /v1/system/info | Retrieve server build metadata |
| GoodMemClient.SystemApi | initializeSystem | POST /v1/system/init | Initialize the system |
| GoodMemClient.UsersApi | getCurrentUser | GET /v1/users/me | Get current user profile |
| GoodMemClient.UsersApi | getUser | GET /v1/users/{id} | Get a user by ID |
| GoodMemClient.UsersApi | getUserByEmail | GET /v1/users/email/{email} | Get user by email address |
Documentation for Authorization
Authentication required - see configuration below.