GoodMem
ReferenceAPIREST APIMemories

Advanced semantic memory retrieval with JSON

Streams semantic retrieval results with full feature support including context items and embedder weight overrides. 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.

Length1 <= length <= 10000
context?array<ContextItem> | null

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

spaceKeysarray<SpaceKey>

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

requestedSize?integer | null

Maximum number of memories to retrieve.

Formatint32
fetchMemory?boolean | null

Whether to include full Memory objects in the response.

fetchMemoryContent?boolean | null

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

postProcessor?PostProcessor

Optional post-processor configuration to transform retrieval results.

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?",    "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": {
      "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",
      "metadata": "{\"source\": \"document\", \"author\": \"John Doe\"}",
      "createdAt": "1672531200000",
      "updatedAt": "1672531200000",
      "createdById": "550e8400-e29b-41d4-a716-446655440002",
      "updatedById": "550e8400-e29b-41d4-a716-446655440002",
      "chunkingConfig": {
        "none": {},
        "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"
          }
        ]
      }
    },
    "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": "COMPLETE",
        "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==",
    "originalContentLength": 0,
    "originalContentSha256": "9f2c8c5a9d740eb56d...",
    "originalContentRef": "s3://my-bucket/document.pdf",
    "contentType": "text/plain",
    "processingStatus": "COMPLETED",
    "metadata": "{\"source\": \"document\", \"author\": \"John Doe\"}",
    "createdAt": "1672531200000",
    "updatedAt": "1672531200000",
    "createdById": "550e8400-e29b-41d4-a716-446655440002",
    "updatedById": "550e8400-e29b-41d4-a716-446655440002",
    "chunkingConfig": {
      "none": {},
      "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": "PARTIAL_RESULTS",
    "message": "Some embedders were unavailable, returning partial results"
  }
}
Empty
Empty
Empty

Stream semantic memory retrieval

Previous Page

Rerankers

Rerankers API endpoints