---
title: "Create a new memory (conversation or document)"
method: POST
path: "/v1/memories"
tags: ["Memories"]
---

# Create a new memory (conversation or document)

`POST /v1/memories`

Create a new memory (conversation or document) using clean JSON body.

- Use `collection_id` (UUID)
- `engram_type` is optional and inferred from payload shape:
  - If `messages` present -> conversation
  - Otherwise -> document
- For conversations: provide `messages` array
- For documents: provide `raw_text` or `chunks`
- Use `snapshot` for device-memory mode (mutually exclusive with collection_id)

## Request body

- CreateMemoryRequest — Request model for creating memories (conversations or documents).
  - `chunks` string[], nullable — Pre-chunked text for document type
  - `collection_id` string, uuid, nullable — Collection UUID (mutually exclusive with snapshot)
  - `content_parts` union[], nullable — Multimodal content parts (text, images, audio, documents) for document type.
    - union
      - TextContentRequest — Text content block.
        - `text` string, required — Text content
        - `type` 'text'
      - FileContentRequest — Unified file content for multimodal messages.
        - `data` string, required — Base64 encoded file data
        - `duration_seconds` number, nullable — Duration in seconds (for audio)
        - `filename` string, nullable — Original filename
        - `media_type` string — MIME type
        - `type` 'file' | 'image' | 'audio' | 'document' — Content kind: file, image, audio, or document.
      - S3FileReferenceRequest — Reference to a file uploaded to S3 (for large files).
        - `bucket` string, nullable — S3 bucket (uses default if not specified)
        - `filename` string, nullable — Original filename
        - `media_type` string — MIME type
        - `s3_key` string, required — S3 object key
        - `size_bytes` integer, nullable — File size in bytes
        - `type` 's3_ref'
  - `contents` string[], nullable — Batch content strings for snapshot mode
  - `engram_type` 'document' | 'conversation' — Type of memory to create
  - `ingestion_config` IngestionConfig — Public ingestion config accepted by memory-ingestion endpoints. This mirrors the supported request payload shape while staying independent from the runtime provider config, which also carries internal-only fields such as ``app`` and ``extra_fields``.
    - `audio_transcription_model` string, nullable
    - `automatic_extraction` boolean
    - `chunk_enrichment_settings` ChunkEnrichmentSettings — Settings for chunk enrichment. Model selection for the enrichment LLM call lives in ``app.task_llms.chunk_enrichment``; the legacy ``generation_config`` field was removed in the per-task LLM cleanup pass.
      - `chunk_enrichment_prompt` string, nullable — The prompt to use for chunk enrichment
      - `enable_chunk_enrichment` boolean — Whether to enable chunk enrichment or not
      - `n_chunks` integer — The number of preceding and succeeding chunks to include. Defaults to 2.
    - `chunk_overlap` integer
    - `chunk_size` integer
    - `chunking_strategy` string
    - `excluded_parsers` string[]
    - `extra_parsers` object
    - `max_concurrent_vlm_tasks` integer
    - `parser_overrides` object
    - `provider` string
    - `vlm` string, nullable
    - `vlm_batch_size` integer
    - `vlm_max_tokens_to_sample` integer
    - `vlm_ocr_one_page_per_chunk` boolean
  - `ingestion_mode` 'hi-res' | 'ocr' | 'fast' | 'custom'
  - `messages` ConversationMessage[], nullable — Messages for conversation type
    - `authority` number, nullable — Optional authority score
    - `content` union, required — Message content. Use a string for text-only messages or a list of content parts for multimodal content.
      - string
      - union[]
        - union
          - TextContentRequest — Text content block.
            - `text` string, required — Text content
            - `type` 'text'
          - FileContentRequest — Unified file content for multimodal messages.
            - `data` string, required — Base64 encoded file data
            - `duration_seconds` number, nullable — Duration in seconds (for audio)
            - `filename` string, nullable — Original filename
            - `media_type` string — MIME type
            - `type` 'file' | 'image' | 'audio' | 'document' — Content kind: file, image, audio, or document.
          - S3FileReferenceRequest — Reference to a file uploaded to S3 (for large files).
            - `bucket` string, nullable — S3 bucket (uses default if not specified)
            - `filename` string, nullable — Original filename
            - `media_type` string — MIME type
            - `s3_key` string, required — S3 object key
            - `size_bytes` integer, nullable — File size in bytes
            - `type` 's3_ref'
    - `metadata` object, nullable — Optional message-level metadata
    - `role` 'user' | 'assistant' | 'system', required — Role: 'user', 'assistant', or 'system'
    - `timestamp` string, date-time, nullable — Semantic timestamp for when the message was authored. Drives chunk timestamps, the extraction LLM's temporal anchor, and episodic grouping. Without it, relative phrases ('this morning') resolve against ingestion wall-clock and episodes collapse.
  - `metadata` object, nullable — Metadata for the memory
  - `name` string, nullable — Optional name for the memory
  - `raw_text` string, nullable — Raw text content for document type
  - `snapshot` SnapshotEnvelopeInput — Portable full snapshot owned by the client.
    - `collection_id` string, uuid, required
    - `created_at` string, date-time
    - `format_version` integer
    - `generation` integer
    - `graph` GraphPayload — A complete graph payload or a context subgraph payload.
      - `entities` EntityRecord[]
        - `category` string, nullable
        - `chunk_ids` string[]
        - `collection_id` string
        - `created_at` string, date-time, required
        - `description` string, nullable
        - `engram_id` string, required
        - `fts_terms` object, nullable
        - `id` string, required
        - `metadata` object
        - `name` string, required
        - `relationship_count` integer
        - `updated_at` string, date-time, required
      - `entity_description_embeddings` EmbeddingBlock — A positionally-aligned masked embedding matrix.
        - `dim` integer
        - `encoding` 'npy-base64'
        - `mask_b64` string
        - `values_b64` string
      - `relationship_description_embeddings` EmbeddingBlock — A positionally-aligned masked embedding matrix.
        - `dim` integer
        - `encoding` 'npy-base64'
        - `mask_b64` string
        - `values_b64` string
      - `relationship_relation_embeddings` EmbeddingBlock — A positionally-aligned masked embedding matrix.
        - `dim` integer
        - `encoding` 'npy-base64'
        - `mask_b64` string
        - `values_b64` string
      - `relationships` RelationshipRecord[]
        - `category` string, nullable
        - `chunk_ids` string[]
        - `collection_id` string
        - `created_at` string, date-time, required
        - `description` string, nullable
        - `engram_id` string, nullable
        - `id` string, required
        - `inference_metadata` object, nullable
        - `metadata` object
        - `object` string, nullable
        - `object_id` string, required
        - `predicate` string
        - `relationship_type` string, nullable
        - `subject` string, nullable
        - `subject_id` string, required
        - `temporal_precision` string, nullable
        - `updated_at` string, date-time, required
        - `valid_span` object, nullable
        - `weight` number, nullable
    - `root_hash` string, required
  - `speaker_id` string, uuid, nullable — UUID of the SourceRole entity creating this memory
  - `speaker_name` string, nullable — Display name of the speaker/agent creating this memory

## Response `200`

Snapshot mode returns an updated SnapshotEnvelope synchronously.

- union — Create-memory success response. Standard memory ingestion returns an accepted async-ingestion envelope; snapshot mode returns the updated snapshot synchronously.
  - NebulaResultsMemoryCreateAcceptedResponse
    - `results` MemoryCreateAcceptedResponse, required — Accepted-response envelope for async memory ingestion.
      - `engram_id` string, uuid, nullable
      - `id` string, uuid, required
      - `memory_id` string, uuid, nullable
      - `message` string, required
      - `status` 'parsing' | 'processing' | 'queued', nullable
      - `task_id` string, nullable
  - NebulaResultsSnapshotMutationResult
    - `results` SnapshotMutationResult, required — Updated snapshot returned by snapshot-mode memory writes.
      - `snapshot` SnapshotEnvelopeOutput, required — Portable full snapshot owned by the client.
        - `collection_id` string, uuid, required
        - `created_at` string, date-time
        - `format_version` integer
        - `generation` integer
        - `graph` GraphPayload — A complete graph payload or a context subgraph payload.
          - `entities` EntityRecord[]
            - `category` string, nullable
            - `chunk_ids` string[]
            - `collection_id` string
            - `created_at` string, date-time, required
            - `description` string, nullable
            - `engram_id` string, required
            - `fts_terms` object, nullable
            - `id` string, required
            - `metadata` object
            - `name` string, required
            - `relationship_count` integer
            - `updated_at` string, date-time, required
          - `entity_description_embeddings` EmbeddingBlock — A positionally-aligned masked embedding matrix.
            - `dim` integer
            - `encoding` 'npy-base64'
            - `mask_b64` string
            - `values_b64` string
          - `relationship_description_embeddings` EmbeddingBlock — A positionally-aligned masked embedding matrix.
            - `dim` integer
            - `encoding` 'npy-base64'
            - `mask_b64` string
            - `values_b64` string
          - `relationship_relation_embeddings` EmbeddingBlock — A positionally-aligned masked embedding matrix.
            - `dim` integer
            - `encoding` 'npy-base64'
            - `mask_b64` string
            - `values_b64` string
          - `relationships` RelationshipRecord[]
            - `category` string, nullable
            - `chunk_ids` string[]
            - `collection_id` string
            - `created_at` string, date-time, required
            - `description` string, nullable
            - `engram_id` string, nullable
            - `id` string, required
            - `inference_metadata` object, nullable
            - `metadata` object
            - `object` string, nullable
            - `object_id` string, required
            - `predicate` string
            - `relationship_type` string, nullable
            - `subject` string, nullable
            - `subject_id` string, required
            - `temporal_precision` string, nullable
            - `updated_at` string, date-time, required
            - `valid_span` object, nullable
            - `weight` number, nullable
        - `root_hash` string, required

## Other responses

- `202` — Successful Response
- `422` — Validation Error

---

[API](https://skmtc.net/zeroset-inc/apis/nebula-api.md) · [All operations](https://skmtc.net/zeroset-inc/apis/nebula-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/zeroset-inc/nebula-api/revisions/b1da2c0bb1ae/schema)