GoodMemCreate a new memory
POST /v1/memories: Creates a new memory in a specified space and starts asynchronous processing.
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.
AUTHORIZATION: Requires CREATE_MEMORY on the containing space. Side effects include creating the memory record and enqueuing a background processing job.
ApiKeyAuthx-api-key<token>GoodMem-Timeout-Ms?integerOptional waiting budget in milliseconds, measured from REST servlet ingress and shared across all internal gRPC calls. Supply one decimal integer from 1 to 86400000. Omission adds no deadline. Existing shorter deadlines still apply. Expiry returns HTTP 504 before streaming starts; after streaming starts, no successful completion event is sent. Use SSE or opt into GoodMem-Stream-Terminal for an explicit terminal outcome. Retrieval work is cooperatively cancelled. An accepted mutation may still commit after timeout or disconnect; a failed response does not imply rollback.
int641 <= value <= 86400000Memory 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.
- body
Application/json memory creation requires exactly one of originalContent or originalContentB64.
memoryId?|Optional client-provided UUID for the memory. If omitted, the server generates one. Returns ALREADY_EXISTS if the ID is already in use.
uuid"f47ac10b-58cc-4372-a567-0e02b2c3d479"spaceId*stringID of the space where this memory will be stored
uuid"550e8400-e29b-41d4-a716-446655440000"originalContent?|Original content as plain text (use either this or originalContentB64)
"This is the text content to be stored as a memory."originalContentB64?|Original content as base64-encoded binary data (use either this or originalContent)
"VGhpcyBpcyBiYXNlNjQgZW5jb2RlZCBjb250ZW50"originalContentRef?|Reference to external content location
"s3://my-bucket/document.pdf"contentType*stringMIME type of the content
"text/plain"metadata?|Additional metadata for the memory. A top-level textual title is an optional document-title hint for embedding providers that support one; blank or non-string titles are ignored. Later metadata edits do not automatically re-embed existing chunks.
properties <= 50{ "source": "document", "author": "John Doe", "tags": [ "important" ], "title": "Quarterly report"}chunkingConfig?||Chunking strategy for this memory (if not provided, uses space 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" }}extractPageImages?|Optional hint to extract page images for eligible document types (for example, PDFs)
fileField?|Optional multipart file field name to bind binary content; required when multiple files are uploaded in a batch multipart request.
Successfully created memory
application/json- response
Memory object containing stored content and metadata
memoryId*stringUnique identifier of the memory
uuid"550e8400-e29b-41d4-a716-446655440000"spaceId*stringID of the space containing this memory
uuid"550e8400-e29b-41d4-a716-446655440001"originalContent?|Original content (only included if requested)
binary"VGhpcyBpcyBiYXNlNjQgYmluYXJ5Lg=="originalContentLength?|Size in bytes of the inline original content
int640 <= valueoriginalContentSha256?|SHA-256 digest of the inline original content, hex encoded
"9f2c8c5a9d740eb56d..."originalContentRef?|Reference to external content location
"s3://my-bucket/document.pdf"contentType*stringMIME type of the content
"text/plain"processingStatus*stringProcessing status of the memory
"COMPLETED""UNSPECIFIED""PENDING""PROCESSING""COMPLETED""FAILED"pageImageStatus*stringProcessing status of page-image extraction for this memory
"COMPLETED""UNSPECIFIED""PENDING""PROCESSING""COMPLETED""FAILED"pageImageCount*integerNumber of extracted page-image renditions linked to this memory
int320 <= value12metadata?|Additional metadata for the memory. A top-level textual title may have been used as a document-title hint when its chunks were embedded; changing it does not automatically re-embed existing chunks.
{ "source": "document", "author": "John Doe"}createdAt*integerTimestamp when the memory was created (milliseconds since epoch)
int641672531200000updatedAt*integerTimestamp when the memory was last updated (milliseconds since epoch)
int641672531200000createdById*stringExact principal or API-key audit actor that created this memory
uuid"550e8400-e29b-41d4-a716-446655440002"updatedById*stringExact principal or API-key audit actor that last updated this memory
uuid"550e8400-e29b-41d4-a716-446655440002"chunkingConfig?||Chunking strategy used for this memory
{ "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?|Background job processing history associated with this memory
{ "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, "failureStage": "DOCUMENT_PROCESSING_STAGE_GENERATING_EMBEDDINGS" }}curl -X POST 'https://your-goodmem-server.example.com/v1/memories' \ -H 'GoodMem-Timeout-Ms: 30000' \ -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" ], "title": "Quarterly report" }, "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, "failureStage": "DOCUMENT_PROCESSING_STAGE_GENERATING_EMBEDDINGS" } }}