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. Advanced HNSW tuning options are available on POST /v1/memories:retrieve only.

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. The snake_case alias space_ids is also accepted.

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. See Filter Expressions reference for syntax and examples.

requestedSize?integer

Maximum number of memories to retrieve. The snake_case alias requested_size is also accepted.

Formatint32
fetchMemory?boolean

Whether to fetch memory definitions (defaults to true). The snake_case alias fetch_memory is also accepted.

Defaulttrue
fetchMemoryContent?boolean

Whether to fetch original content for memories (defaults to false). The snake_case alias fetch_memory_content is also accepted.

Defaultfalse
postProcessorRerankerId?string

UUID of reranker to use for ChatPostProcessor (enables post-processing). Accepted aliases: ppRerankerId, pp_reranker_id.

postProcessorLlmId?string

UUID of LLM to use for ChatPostProcessor generation. Accepted aliases: ppLlmId, pp_llm_id.

postProcessorRelevanceThreshold?number

Minimum relevance score for ChatPostProcessor. If omitted, no relevance threshold is applied. Accepted aliases: ppRelevanceThreshold, pp_relevance_threshold.

Formatdouble
postProcessorLlmTemp?number

LLM temperature for ChatPostProcessor generation (default: 0.3). Accepted aliases: ppLlmTemp, pp_llm_temp.

Default0.3
Formatdouble
postProcessorMaxResults?integer

Maximum results for ChatPostProcessor (default: 10). Accepted aliases: ppMaxResults, pp_max_results.

Default10
Formatint32
postProcessorChronologicalResort?boolean

Whether ChatPostProcessor should resort by creation time (default: true). Accepted aliases: ppChronologicalResort, pp_chronological_resort.

Defaulttrue

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==",
      "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

List memory page images

Previous Page

Advanced semantic memory retrieval with JSON

Next Page