MemorySync
API Reference

Bulk Add Memory

Submit 1–50 independent memory candidates and inspect the outcome for every original item.

Endpoint and request fields

POST/memory/bulk-add
207 Multi-Status
FieldTypeContract
itemsarrayRequired; 1–50 candidates.
items[].textstringRequired candidate text.
items[].sourcestringOptional source label.
items[].event_type / eventTypestringOptional event label.
items[].tagsstring[]Optional tags.
items[].importancenumberOptional value from 0 to 1.
items[].metadataobjectOptional metadata.
items[].client_refstringOptional; up to 128 characters. Your own identifier for this record. An item carrying one you have sent before is reported as skipped with reason already_ingested, and no second copy is stored. Unique per end user, project and environment.
deduplicatebooleanAccepted and ignored. Deduplication is always on for this route; the field is kept so existing callers are not rejected.

Add a batch

import os
from memorysync import MemorySyncClient


client = MemorySyncClient(
    api_key=os.environ["MEMORYSYNC_API_KEY"],
    base_url="https://api.memorysync.io",
    project_id=os.environ["MEMORYSYNC_PROJECT_ID"],
    end_user_id="usr_7f3a9c2e",
)


from memorysync import BulkAddItem


result = client.bulk_add([
    BulkAddItem(text="The user prefers concise answers.", tags=["preference"]),
    BulkAddItem(text="The user uses dark mode.", tags=["preference", "ui"]),
])

Result paths

MeaningPython pathNode.js pathREST path
Totalsresult.total, .created, .skipped, .rejectedresult.total, .created, .skipped, .rejectedtotal, created, skipped, rejected
Per-item outcomeresult.results[i].statusresult.results[i].statusresults[i].status
Created IDsresult.results[i].memory_idsresult.results[i].memoryIdsresults[i].memory_ids
Explanationresult.results[i].reasonresult.results[i].reasonresults[i].reason
207-response.json
{"total":2,"created":1,"skipped":1,"rejected":0,"results":[{"index":0,"status":"created","memory_ids":[101],"reason":null},{"index":1,"status":"skipped","memory_ids":[],"reason":"duplicate"}]}

Errors and next action

Batch handling
CREATED
Use returned IDs

Continue with the created item.

SKIPPED
Accept the normal outcome

Read the reason; no new memory was created for that item.

REJECTED
Correct this item

Use the original index to locate and fix the candidate.

REQUEST ERROR
Handle the whole call

Correct 4xx; preserve a recoverable state for 429 or 5xx.

Safety notes

Batch contract in detail

RuleContract
Batch sizeSubmit from 1 to 50 independent items.
Item textEach item requires meaningful text and is validated independently.
Item contextEach item can include source, event type, tags, importance, metadata, and an end-user override.
DeduplicationAlways applied. Near-duplicate detection is part of the shared extraction pipeline, so it cannot be turned off for a batch. It compares meaning rather than matching an id, which makes it a filter and not an idempotency guarantee.
Safe retriesSend items[].client_ref with your own id for each record. A retry carrying the same value reports that item as skipped with reason already_ingested and returns the ids the first submission produced. This is the guarantee near-duplicate detection cannot give.
ResponseHTTP 207 reports totals and preserves the original zero-based index for each result.

Reconcile every item

Batch reconciliation
  1. 01

    Match

    INDEX

    Use each result’s index to find the original candidate.

  2. 02

    Accept

    CREATED

    Record returned IDs for every created item.

  3. 03

    Explain

    SKIPPED

    Treat skipped as a normal outcome and read its reason.

  4. 04

    Correct

    REJECTED

    Fix only the corresponding rejected item.

  5. 05

    Report

    DONE

    Present completion only after inspecting all entries.

Related reference

Bulk Import

Move more than 50 records at a time.

Add Memory

Submit a single candidate.

Query Memory

Retrieve created records.

Rate limits and errors

Handle request-level failures.

Was this page helpful?
← Previous
Add
Next →
Bulk Import