GoodMem
ReferenceAPIREST APIMemories

Stream semantic memory retrieval

Streams semantic retrieval results based on query and context. Supports SSE (text/event-stream) and NDJSON (application/x-ndjson) formats.

GET
/v1/memories:retrieve

Authorization

x-api-key<token>

In: header

Query Parameters

messagestring

Primary query/message for semantic search

spaceIds?string

Comma-separated list of space UUIDs to search within

filter?string

Optional filter expression applied to every space ID supplied via the query parameter. Use the POST variant if you need distinct filters per space.

requestedSize?integer

Maximum number of memories to retrieve

Formatint32
fetchMemory?boolean

Whether to fetch memory definitions (defaults to true)

fetchMemoryContent?boolean

Whether to fetch original content for memories (defaults to false)

postProcessorRerankerId?string

UUID of reranker to use for ChatPostProcessor (enables post-processing). Legacy alias: pp_reranker_id.

postProcessorLlmId?string

UUID of LLM to use for ChatPostProcessor generation. Legacy alias: pp_llm_id.

postProcessorRelevanceThreshold?number

Minimum relevance score for ChatPostProcessor (default: 0.5). Legacy alias: pp_relevance_threshold.

Formatdouble
postProcessorLlmTemp?number

LLM temperature for ChatPostProcessor generation (default: 0.3). Legacy alias: pp_llm_temp.

Formatdouble
postProcessorMaxResults?integer

Maximum results for ChatPostProcessor (default: 10). Legacy alias: pp_max_results.

Formatint32
postProcessorChronologicalResort?boolean

Whether ChatPostProcessor should resort by creation time (default: true). Legacy alias: pp_chronological_resort.

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"

Response Body

curl -X GET "http://localhost:8080/v1/memories:retrieve?message=How+do+I+implement+vector+search%3F&spaceIds=550e8400-e29b-41d4-a716-446655440000%2C550e8400-e29b-41d4-a716-446655440001&filter=CAST%28val%28%27%24.effectiveDate%27%29+AS+DATE%29+%3E%3D+CAST%28%272024-10-01%27+AS+DATE%29&requestedSize=10&fetchMemory=true&fetchMemoryContent=false&postProcessorRerankerId=550e8400-e29b-41d4-a716-446655440000&postProcessorLlmId=550e8400-e29b-41d4-a716-446655440001&postProcessorRelevanceThreshold=0.5&postProcessorLlmTemp=0.3&postProcessorMaxResults=10&postProcessorChronologicalResort=true" \  -H "Accept: application/x-ndjson"
{
  "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

Download memory content

Previous Page

Advanced semantic memory retrieval with JSON

Next Page