Add Memory | MemorySync Docs

Endpoint and request fields

POST/memory/add

201 Created or normal 200 Skipped

Field	Type	Contract
`text`	string	Required memory candidate.
`source`	string	Optional application source label.
`event_type`	string	Optional event label describing the trigger that produced this memory.
`tags`	string[]	Optional application tags.
`importance`	number	Optional value from 0 to 1.
`metadata`	object	Optional application metadata.
`client_ref`	string	Optional; up to 128 characters. Your own identifier for this record. Send it again and the write is recognised rather than stored twice. Unique per end user, project and environment.

Add a memory

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",
)

result = client.add(
    "The user prefers concise answers.",
    source="chat",
    tags=["preference"],
    importance=0.8,
    metadata={"confirmed": True},
)

Result paths

Outcome	Python path	Node.js path	REST path
Created Memory	`result.id`, `result.text`	`result.id`, `result.text`	`id`, `text`
Skipped	`result.status`, `result.reason`, `result.memory_ids`	`result.status`, `result.reason`, `result.memoryIds`	`status`, `reason`, `memory_ids`

Add status behavior

201

Created

The response is the stored Memory. Use its id for later operations. When the text distils into more than one atomic fact, this is the first one; Query and List show the rest.

200

Skipped

This is a normal result. No new memory was created; read reason.

201-response.json

{"id":101,"text":"The user prefers concise answers.","source":"chat","tags":["preference"],"importance":0.8,"metadata":{"confirmed":true},"is_summary":false,"created_at":"2026-05-04T12:30:11Z"}

Errors and next action

For 400 or 422, correct the body. For 401 or 403, correct server credentials or project scope. For 429 or 5xx, keep the UI recoverable and do not assume whether an interrupted write created a memory.

Safety notes

Validation, aliases, and defaults

Input	Behavior
`text`	Required by SDKs; REST also accepts `content` as an alias. Whitespace is trimmed and the service requires meaningful text.
`source`, `tags`, `importance`, `metadata`	Optional customer-controlled descriptive fields. Importance must be from 0 to 1.
End-user scope	The client-level value is used unless the operation supplies a supported override. API-key calls require a resolved end user.
Created result	Returns a Memory with HTTP `201`.
Skipped result	Returns HTTP `200` with `status`, `reason`, and memory outcome fields.

Production add pattern

Submit one durable fact, preference, decision, event, or outcome rather than a complete transcript.
Preserve non-secret source context that helps your application understand the record later.
Branch explicitly between a created Memory and a normal skipped result.
Keep an interrupted write recoverable; reconcile before repeating it blindly.
Store authoritative transactional data and permissions in their source systems.

Bulk Add

Submit several independent candidates.

Get Memory

Fetch a created memory by ID.

Query Memory

Retrieve relevant memories.