Memories API
Memories API documentation for JavaScript SDK
The default url is http://localhost:8080
| Method | HTTP request | Description |
|---|---|---|
| batchCreateMemory | POST /v1/memories:batchCreate | Create multiple memories in a batch |
| batchDeleteMemory | POST /v1/memories:batchDelete | Delete memories in batch |
| batchGetMemory | POST /v1/memories:batchGet | Get multiple memories by ID |
| createMemory | POST /v1/memories | Create a new memory |
| deleteMemory | DELETE /v1/memories/{id} | Delete a memory |
| getMemory | GET /v1/memories/{id} | Get a memory by ID |
| getMemoryContent | GET /v1/memories/{id}/content | Download memory content |
| getMemoryPageImageContent | GET /v1/memories/{id}/pages/{pageIndex}/image | Download memory page image content |
| listMemories | GET /v1/spaces/{spaceId}/memories | List memories in a space |
| listMemoryPageImages | GET /v1/memories/{id}/pages | List memory page images |
| retrieveMemory | GET /v1/memories:retrieve | Stream semantic memory retrieval |
| retrieveMemoryAdvanced | POST /v1/memories:retrieve | Advanced 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
| Name | Type | Description | Notes |
|---|---|---|---|
| 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. |
Return type
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
| Name | Type | Description | Notes |
|---|---|---|---|
| batchMemoryDeletionRequest | BatchMemoryDeletionRequest | Batch memory deletion details |
Return type
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
| Name | Type | Description | Notes |
|---|---|---|---|
| batchMemoryRetrievalRequest | BatchMemoryRetrievalRequest | Batch memory retrieval details |
Return type
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
| Name | Type | Description | Notes |
|---|---|---|---|
| jsonMemoryCreationRequest | 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. |
Return type
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
| Name | Type | Description | Notes |
|---|---|---|---|
| id | String | The 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
| Name | Type | Description | Notes |
|---|---|---|---|
| id | String | The unique identifier of the memory to retrieve | |
| includeContent | Boolean | Whether to include the original content in the response (defaults to false). The snake_case alias include_content is also accepted. | [optional] [default to false] |
| includeProcessingHistory | Boolean | Whether 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
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
| Name | Type | Description | Notes |
|---|---|---|---|
| id | String | The 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
| Name | Type | Description | Notes |
|---|---|---|---|
| id | String | Memory UUID | |
| pageIndex | Number | 0-based page index | |
| dpi | 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. | [optional] |
| contentType | String | Optional 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
| Name | Type | Description | Notes |
|---|---|---|---|
| spaceId | String | The unique identifier of the space containing the memories | |
| includeContent | Boolean | Whether to include the original content in the response (defaults to false). The snake_case alias include_content is also accepted. | [optional] [default to false] |
| includeProcessingHistory | Boolean | Whether 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] |
| statusFilter | String | Filter memories by processing status (PENDING, PROCESSING, COMPLETED, FAILED). The snake_case alias status_filter is also accepted. | [optional] |
| filter | String | Optional metadata filter expression for list results | [optional] |
| maxResults | Number | Maximum 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] |
| nextToken | 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. | [optional] |
| sortBy | String | Field to sort by (e.g., 'created_at'). The snake_case alias sort_by is also accepted. | [optional] |
| sortOrder | String | Sort direction (ASCENDING or DESCENDING). The snake_case alias sort_order is also accepted. | [optional] |
Return type
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
| Name | Type | Description | Notes |
|---|---|---|---|
| id | String | Memory UUID | |
| startPageIndex | Number | Optional lower bound for returned page indices, inclusive. The snake_case alias start_page_index is also accepted. | [optional] |
| endPageIndex | Number | Optional upper bound for returned page indices, inclusive. The snake_case alias end_page_index is also accepted. | [optional] |
| dpi | Number | Optional rendition filter for page-image DPI. | [optional] |
| contentType | String | Optional rendition filter for page-image MIME type, such as image/png. The snake_case alias content_type is also accepted. | [optional] |
| maxResults | Number | Maximum number of results per page. The snake_case alias max_results is also accepted. | [optional] |
| nextToken | String | Opaque pagination token for the next page. The snake_case alias next_token is also accepted. Do not parse or construct it. | [optional] |
Return type
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 generationppRerankerId: UUID of reranker for result rerankingppRelevanceThreshold: Minimum relevance scoreppLlmTemp: LLM temperature for generationppMaxResults: Maximum results to returnppChronologicalResort: Whether to resort by creation timeformat: Streaming format ('ndjson'or'sse')
Return type
Promise resolving to AsyncIterableIterator of streaming events
Authorization
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 messagespaceIds: Array of space UUIDsrequestedSize: Maximum memories to retrievefetchMemory: Whether to fetch memory definitionsfetchMemoryContent: Whether to fetch original contentformat: Streaming format ('ndjson'or'sse')postProcessorName: Name of custom post-processorpostProcessorConfig: Configuration object for the post-processor
Return type
Promise resolving to AsyncIterableIterator of streaming events