Create a new memory

Creates a new memory in a specified space and starts asynchronous processing. The memory begins in PENDING status while a background job performs chunking and embedding generation.

IDEMPOTENCY: If memoryId is omitted, the server generates a new UUID and retries are not idempotent. If the client supplies a stable memoryId, the operation behaves as create-if-absent: the first request creates the memory and subsequent retries return HTTP 409 Conflict (ALREADY_EXISTS) rather than creating duplicates. Returns INVALID_ARGUMENT if space_id, original_content, or content_type is missing or invalid. Returns NOT_FOUND if the specified space does not exist. Requires CREATE_MEMORY_OWN permission for spaces you own (or CREATE_MEMORY_ANY for admin users to create in any space). Side effects include creating the memory record and enqueuing a background processing job.

Authorization

x-api-key<token>

In: header

Request Body

Memory creation details. For application/json requests, provide exactly one of originalContent or originalContentB64. For multipart/form-data, provide a JSON request part plus a file part.

memoryId?string | null

Optional client-provided UUID for the memory. If omitted, the server generates one. Returns ALREADY_EXISTS if the ID is already in use.

Formatuuid

spaceIdstring

ID of the space where this memory will be stored

Formatuuid

originalContent?string | null

Original content as plain text (use either this or originalContentB64)

Default"This is the text content to be stored as a memory."

originalContentB64?string | null

Original content as base64-encoded binary data (use either this or originalContent)

Default"VGhpcyBpcyBiYXNlNjQgZW5jb2RlZCBjb250ZW50"

originalContentRef?string | null

Reference to external content location

Default"s3://my-bucket/document.pdf"

contentTypestring

MIME type of the content

Default"text/plain"

metadata?object | null

Additional metadata for the memory

Default{"source":"document","author":"John Doe","tags":["important"]}

Propertiesproperties <= 50

Empty Object

chunkingConfig?None | Recursive | Sentence

Chunking strategy for this memory (if not provided, uses space default)

Default

{"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"}}

Configuration for text chunking strategy used when processing content. Exactly one of none, recursive, or sentence must be provided.

noneNoChunkingConfiguration | null

No chunking strategy - preserve original content as single unit

Configuration for text chunking strategy used when processing content. Exactly one of none, recursive, or sentence must be provided.

recursiveRecursiveChunkingConfiguration | null

Recursive hierarchical chunking strategy with configurable separators

Default

{"chunkSize":1000,"chunkOverlap":200,"separators":["\n\n","\n","."," "],"keepStrategy":"KEEP_END","separatorIsRegex":false,"lengthMeasurement":"CHARACTER_COUNT"}

Configuration for text chunking strategy used when processing content. Exactly one of none, recursive, or sentence must be provided.

sentenceSentenceChunkingConfiguration | null

Sentence-based chunking strategy with language detection

Default{"maxChunkSize":1000,"minChunkSize":100,"enableLanguageDetection":true,"lengthMeasurement":"CHARACTER_COUNT"}

extractPageImages?boolean | null

Optional hint to extract page images for eligible document types (for example, PDFs)

fileField?string | null

Optional multipart file field name to bind binary content; required when multiple files are uploaded in a batch multipart request.

Response Body

curl -X POST "http://localhost:8080/v1/memories" \
  -H "Content-Type: application/json" \
  -d '{
    "memoryId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "spaceId": "550e8400-e29b-41d4-a716-446655440000",
    "originalContent": "This is the content to be stored and processed as a memory.",
    "originalContentB64": "VGhpcyBpcyBiYXNlNjQgZW5jb2RlZCBjb250ZW50",
    "originalContentRef": "s3://my-bucket/document.pdf",
    "contentType": "text/plain",
    "metadata": {
      "source": "document",
      "author": "John Doe",
      "tags": [
        "important",
        "research"
      ]
    },
    "chunkingConfig": {
      "recursive": {
        "chunkSize": 500,
        "chunkOverlap": 50,
        "separators": [
          "\\n\\n",
          "\\n",
          "."
        ],
        "separatorIsRegex": false,
        "keepStrategy": "KEEP_END",
        "lengthMeasurement": "CHARACTER_COUNT"
      }
    }
  }'

curl -X POST "http://localhost:8080/v1/memories" \  -H "Content-Type: application/json" \  -d '{    "memoryId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",    "spaceId": "550e8400-e29b-41d4-a716-446655440000",    "originalContent": "This is the content to be stored and processed as a memory.",    "originalContentB64": "VGhpcyBpcyBiYXNlNjQgZW5jb2RlZCBjb250ZW50",    "originalContentRef": "s3://my-bucket/document.pdf",    "contentType": "text/plain",    "metadata": {      "source": "document",      "author": "John Doe",      "tags": [        "important",        "research"      ]    },    "chunkingConfig": {      "recursive": {        "chunkSize": 500,        "chunkOverlap": 50,        "separators": [          "\\n\\n",          "\\n",          "."        ],        "separatorIsRegex": false,        "keepStrategy": "KEEP_END",        "lengthMeasurement": "CHARACTER_COUNT"      }    }  }'

{
  "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": {
    "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
    }
  }
}

Empty

Create a new memory

Authorization

Request Body

Response Body

201

400

401

403

409