GoodMemAdvanced semantic memory retrieval with JSON
Streams semantic retrieval results with full feature support including context items and embedder weight overrides, per-space filters, and request-level HNSW tuning. Supports SSE (text/event-stream) and NDJSON (application/x-ndjson) formats.
Header Parameters
Response format: 'text/event-stream' for Server-Sent Events or 'application/x-ndjson' for newline-delimited JSON
Request body with query, context, and space configurations
Primary query/message for semantic search.
"How do I implement vector search?"1 <= length <= 10000Optional context items (text or binary) to provide additional context for the search.
[{"text":"Focus on implementation details"},{"binary":{"contentType":"image/png","data":"base64data..."}}]List of spaces to search with optional per-embedder weight overrides.
[{"spaceId":"550e8400-e29b-41d4-a716-446655440000","embedderWeights":[{"embedderId":"550e8400-e29b-41d4-a716-446655440001","weight":1.5}],"filter":"lower(CAST(val('$.primaryLocation.city') AS TEXT)) = 'manila'"}]Maximum number of memories to retrieve.
10int32Optional soft cap for generated retrieve replies. When set to a positive token count, chat post-processing uses this value as the LLM completion-token budget.
Whether to include streamed memory-definition records in the response. Defaults to true when omitted. These records include memory metadata and audit fields, but omit originalContent unless fetchMemoryContent is true.
trueWhether streamed memory-definition records include originalContent bytes. Requires fetchMemory=true. Defaults to false when omitted.
falseOptional request-level HNSW tuning overrides. Advanced usage; available on POST retrieve.
{"efSearch":200,"iterativeScan":"ITERATIVE_SCAN_RELAXED_ORDER","maxScanTuples":20000,"scanMemMultiplier":2.5}Optional post-processor configuration to transform retrieval results.
{"name":"com.goodmem.retrieval.postprocess.ChatPostProcessorFactory","config":{"llm_id":"72eaec11-c698-4262-970b-83aa957f9e02","llm_temp":0.3,"max_results":10,"chronological_resort":true}}Optional durable request logging block for POST retrieve requests. Set logging.enabled=true to opt in, or supply flat scalar logging.callerAttributes to attach if caller opt-in or an admin policy logs the request.
Response Body
curl -X POST "https://loading/v1/memories:retrieve" \ -H "Accept: application/x-ndjson" \ -H "Content-Type: application/json" \ -d '{ "message": "How do I implement vector search?", "spaceKeys": [ { "spaceId": "550e8400-e29b-41d4-a716-446655440000", "embedderWeights": [ { "embedderId": "550e8400-e29b-41d4-a716-446655440001", "weight": 1.5 } ], "filter": "lower(CAST(val(\'$.primaryLocation.city\') AS TEXT)) = \'manila\'" } ] }'{
"resultSetBoundary": {
"resultSetId": "550e8400-e29b-41d4-a716-446655440000",
"kind": "BEGIN",
"stageName": "vector_search",
"expectedItems": 10
},
"abstractReply": {
"text": "Based on the retrieved memories, the recommended approach is to use vector similarity search combined with keyword filtering for optimal results.",
"relevanceScore": 0.85,
"resultSetId": "550e8400-e29b-41d4-a716-446655440000"
},
"retrievedItem": {
"memory": null,
"chunk": {
"resultSetId": "550e8400-e29b-41d4-a716-446655440000",
"chunk": {
"chunkId": "550e8400-e29b-41d4-a716-446655440000",
"memoryId": "550e8400-e29b-41d4-a716-446655440001",
"chunkSequenceNumber": 1,
"chunkText": "This is a chunk of text from the memory content.",
"vectorStatus": "COMPLETED",
"startOffset": 0,
"endOffset": 150,
"metadata": {
"source": "page-3",
"language": "en"
},
"createdAt": 1617293472000,
"updatedAt": 1617293472000,
"createdById": "550e8400-e29b-41d4-a716-446655440000",
"updatedById": "550e8400-e29b-41d4-a716-446655440000"
},
"memoryIndex": 2,
"relevanceScore": 0.92
}
},
"memoryDefinition": {
"memoryId": "550e8400-e29b-41d4-a716-446655440000",
"spaceId": "550e8400-e29b-41d4-a716-446655440001",
"originalContent": "VGhpcyBpcyBiYXNlNjQgYmluYXJ5Lg==",
"originalContentLength": 0,
"originalContentSha256": "9f2c8c5a9d740eb56d...",
"originalContentRef": "s3://my-bucket/document.pdf",
"contentType": "text/plain",
"processingStatus": "COMPLETED",
"pageImageStatus": "COMPLETED",
"pageImageCount": 12,
"metadata": {
"source": "document",
"author": "John Doe"
},
"createdAt": 1672531200000,
"updatedAt": 1672531200000,
"createdById": "550e8400-e29b-41d4-a716-446655440002",
"updatedById": "550e8400-e29b-41d4-a716-446655440002",
"chunkingConfig": {
"none": null,
"recursive": {
"chunkSize": 1000,
"chunkOverlap": 200,
"separators": [
"\n\n",
"\n",
".",
" "
],
"keepStrategy": "KEEP_END",
"separatorIsRegex": false,
"lengthMeasurement": "CHARACTER_COUNT"
},
"sentence": {
"maxChunkSize": 1000,
"minChunkSize": 100,
"enableLanguageDetection": true,
"lengthMeasurement": "CHARACTER_COUNT"
}
},
"processingHistory": {
"latestJob": {
"jobId": 42,
"jobType": "document_processor",
"status": "BACKGROUND_JOB_RUNNING",
"attempts": 1,
"maxAttempts": 5,
"runAt": 1714713600000,
"leaseUntil": 1714713660000,
"lockedBy": "worker-1",
"lastError": "Transient network failure",
"updatedAt": 1714713615000
},
"attempts": [
{
"attemptId": 101,
"jobId": 42,
"startedAt": 1714713605000,
"finishedAt": 1714713612000,
"ok": true,
"workerId": "worker-1",
"statusMessage": "Uploading chunk 3/10",
"progressCurrent": 3,
"progressTotal": 10,
"progressUnit": "chunks",
"progressUpdatedAt": 1714713609000,
"errorMessage": "S3 upload timed out",
"errorStacktrace": "string"
}
]
}
},
"status": {
"code": "VECTOR_SEARCH_PARTIAL",
"message": "Some embedders were unavailable, returning partial results",
"details": {
"embedder_id": "550e8400-e29b-41d4-a716-446655440000"
}
}
}