GoodMem
ReferenceAPIREST APIMemories

Advanced 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.

POST
/v1/memories:retrieve

Authorization

x-api-key<token>

In: header

Header Parameters

Accept?string

Response format: 'text/event-stream' for Server-Sent Events or 'application/x-ndjson' for newline-delimited JSON

Value in"text/event-stream" | "application/x-ndjson"

Request Body

Request body with query, context, and space configurations

messagestring

Primary query/message for semantic search.

Default"How do I implement vector search?"
Length1 <= length <= 10000
context?array<ContextItem> | null

Optional context items (text or binary) to provide additional context for the search.

Default[{"text":"Focus on implementation details"},{"binary":{"contentType":"image/png","data":"base64data..."}}]
spaceKeysarray<SpaceKey>

List of spaces to search with optional per-embedder weight overrides.

Default[{"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'"}]
requestedSize?integer | null

Maximum number of memories to retrieve.

Default10
Formatint32
fetchMemory?boolean | null

Whether to include full Memory objects in the response.

Defaulttrue
fetchMemoryContent?boolean | null

Whether to include memory content in the response. Requires fetchMemory=true.

Defaultfalse
hnsw?HnswOptions | null

Optional request-level HNSW tuning overrides. Advanced usage; available on POST retrieve.

Default{"efSearch":200,"iterativeScan":"ITERATIVE_SCAN_RELAXED_ORDER","maxScanTuples":20000,"scanMemMultiplier":2.5}
postProcessor?PostProcessor | null

Optional post-processor configuration to transform retrieval results. See ChatPostProcessor reference for the built-in ChatPostProcessor parameters.

Default{"name":"com.goodmem.retrieval.postprocess.ChatPostProcessorFactory","config":{"reranker_id":"a1b2c3d4-e5f6-7890-1234-567890abcdef","relevance_threshold":0.7,"chronological_resort":true,"llm_id":"72eaec11-c698-4262-970b-83aa957f9e02","llm_temp":0.3,"max_results":10,"sys_prompt":"You are an AI assistant helping to synthesize retrieved memory content.","prompt":"User Query: \"{{ userQuery }}\"\n\nRetrieved Data:\n{{ dataSection }}","gen_token_budget":512}}

Response Body

curl -X POST "http://localhost:8080/v1/memories:retrieve" \  -H "Accept: application/x-ndjson" \  -H "Content-Type: application/json" \  -d '{    "message": "How do I implement vector search?",    "context": [      {        "text": "Please focus on implementation details."      }    ],    "spaceKeys": [      {        "spaceId": "550e8400-e29b-41d4-a716-446655440000",        "embedderWeights": [          {            "embedderId": "550e8400-e29b-41d4-a716-446655440000",            "weight": 1.5          }        ],        "filter": "CAST(val(\'$.effectiveDate\') AS DATE) >= CAST(\'2024-10-01\' AS DATE)"      }    ],    "requestedSize": 10,    "fetchMemory": true,    "fetchMemoryContent": false,    "hnsw": {      "efSearch": 200,      "iterativeScan": "ITERATIVE_SCAN_RELAXED_ORDER",      "maxScanTuples": 20000,      "scanMemMultiplier": 2.5    },    "postProcessor": {      "name": "com.goodmem.retrieval.postprocess.ChatPostProcessorFactory",      "config": {        "reranker_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",        "relevance_threshold": 0.7,        "chronological_resort": true,        "llm_id": "72eaec11-c698-4262-970b-83aa957f9e02",        "llm_temp": 0.3,        "max_results": 10,        "sys_prompt": "You are an AI assistant helping to synthesize retrieved memory content.",        "prompt": "User Query: \"{{ userQuery }}\"\n\nRetrieved Data:\n{{ dataSection }}",        "gen_token_budget": 512      }    }  }'
{
  "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": {
      "memoryId": "550e8400-e29b-41d4-a716-446655440000",
      "spaceId": "550e8400-e29b-41d4-a716-446655440001",
      "originalContent": "VGhpcyBpcyBiYXNlNjQgYmluYXJ5Lg==",
      "originalContentSha256": "9f2c8c5a9d740eb56d...",
      "originalContentRef": "s3://my-bucket/document.pdf",
      "contentType": "text/plain",
      "processingStatus": "COMPLETED",
      "pageImageStatus": "COMPLETED",
      "pageImageCount": 12,
      "createdAt": 1672531200000,
      "updatedAt": 1672531200000,
      "createdById": "550e8400-e29b-41d4-a716-446655440002",
      "updatedById": "550e8400-e29b-41d4-a716-446655440002",
      "chunkingConfig": {
        "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
        }
      }
    },
    "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,
        "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==",
    "originalContentSha256": "9f2c8c5a9d740eb56d...",
    "originalContentRef": "s3://my-bucket/document.pdf",
    "contentType": "text/plain",
    "processingStatus": "COMPLETED",
    "pageImageStatus": "COMPLETED",
    "pageImageCount": 12,
    "createdAt": 1672531200000,
    "updatedAt": 1672531200000,
    "createdById": "550e8400-e29b-41d4-a716-446655440002",
    "updatedById": "550e8400-e29b-41d4-a716-446655440002",
    "chunkingConfig": {
      "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
      }
    }
  },
  "status": {
    "code": "PARTIAL_RESULTS",
    "message": "Some embedders were unavailable, returning partial results"
  }
}
Empty
Empty
Empty

Stream semantic memory retrieval

Previous Page

Rerankers

Rerankers API endpoints