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.
IMPORTANT: This operation is NOT idempotent - each request creates a new memory record. 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, generating a unique UUID, and enqueuing a background processing job.
In: header
Memory creation details. Accepts application/json or multipart/form-data with a JSON request part and a file part.
Optional client-provided UUID for the memory. If omitted, the server generates one. Returns ALREADY_EXISTS if the ID is already in use.
ID of the space where this memory will be stored
Original content as plain text (use either this or originalContentB64)
Original content as base64-encoded binary data (use either this or originalContent)
Reference to external content location
MIME type of the content
Additional metadata for the memory
properties <= 50Empty Object
Chunking strategy for this memory (if not provided, uses space default)
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 '{ "spaceId": "550e8400-e29b-41d4-a716-446655440000", "originalContent": "This is the content to be stored and processed as a memory.", "contentType": "text/plain", "metadata": { "source": "document", "author": "John Doe", "tags": [ "important", "research" ] }, "chunkingConfig": { "recursive": { "chunkSize": "500", "chunkOverlap": "50", "separators": [ "\\n\\n", "\\n", "." ], "keepStrategy": "KEEP_END", "separatorIsRegex": "false", "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",
"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"
}
]
}
}