Memories API
Memories API documentation for JavaScript SDK
All URIs are relative to http://localhost:8080
| Method | HTTP request | Description |
|---|---|---|
| batchCreateMemory | POST /v1/memories:batchCreate | Create multiple memories in a batch |
| batchDeleteMemory | POST /v1/memories:batchDelete | Delete multiple memories by ID |
| 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 |
| listMemories | GET /v1/spaces/{spaceId}/memories | List memories in a space |
| retrieveMemory | GET /v1/memories:retrieve | Stream semantic memory retrieval |
| retrieveMemoryAdvanced | POST /v1/memories:retrieve | Advanced 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
| Name | Type | Description | Notes |
|---|---|---|---|
| batchMemoryCreationRequest | BatchMemoryCreationRequest | Batch 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
| Name | Type | Description | Notes |
|---|---|---|---|
| batchMemoryDeletionRequest | BatchMemoryDeletionRequest | Batch 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
| Name | Type | Description | Notes |
|---|---|---|---|
| batchMemoryRetrievalRequest | BatchMemoryRetrievalRequest | Batch 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
| Name | Type | Description | Notes |
|---|---|---|---|
| memoryCreationRequest | MemoryCreationRequest | Memory creation details |
Return type
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
| 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)
'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
| 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) | [optional] |
| includeProcessingHistory | Boolean | Whether to include background job processing history in the response (defaults to false) | [optional] |
Return type
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
| Name | Type | Description | Notes |
|---|---|---|---|
| id | String | The 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
| 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) | [optional] |
| statusFilter | String | Filter memories by processing status (PENDING, PROCESSING, COMPLETED, FAILED) | [optional] |
| maxResults | Number | IGNORED: The current server implementation does not support pagination for this endpoint. This parameter is documented for future compatibility but will be ignored. | [optional] |
| nextToken | String | IGNORED: The current server implementation does not support pagination for this endpoint. This parameter is documented for future compatibility but will be ignored. | [optional] |
| sortBy | String | Field to sort by (e.g., 'created_at') | [optional] |
| sortOrder | String | Sort direction (ASCENDING or DESCENDING) | [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