How It Works

Add Memory

Send useful context from your trusted server. Then handle the result as one of two normal outcomes: a memory was created, or the input was skipped.

What happens from your application’s view

Add request paths

REQUEST

Scoped input arrives

Your server sends text with project and end-user scope.

201

Memory created

Use the returned memory object and ID.

200

Input skipped

Treat the reason as a completed no-storage result.

4xx

Correction required

Fix credentials, scope, or request fields before retrying.

Add and handle both outcomes

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="user-123",
)

result = client.add(
    "The user prefers concise answers and dark mode.",
    source="profile",
    tags=["preference", "ui"],
)

if getattr(result, "status", None) == "skipped":
    print("Not stored:", result.reason)
else:
    print("Created memory:", result.id)

Read the outcome before continuing

Outcome	HTTP status	What to do
Created memory object	`201 Created`	Use the returned `id`; do not predict or construct one.
`status: "skipped"`	`200 OK`	Treat it as a completed no-storage result. Do not retry unchanged input.
Validation or authentication error	`4xx`	Correct the request or credentials before retrying.

{
  "id": 123,
  "text": "The user prefers concise answers and dark mode.",
  "source": "profile",
  "tags": ["preference", "ui"],
  "is_summary": false,
  "created_at": "2026-07-31T12:00:00Z"
}

Add several candidates

Bulk add accepts 1 to 50 items and returns HTTP 207 Multi-Status. Always inspect every item because one request can contain a mix of created, skipped, and rejected outcomes.

from memorysync.types import BulkAddItem

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="user-123",
)

result = client.bulk_add([
    BulkAddItem(text="The user prefers weekly status updates.", tags=["preference"]),
    BulkAddItem(text="The user selected dark mode for the dashboard.", tags=["ui"]),
])

for item in result.results:
    print(item.index, item.status, item.reason)

Decide what your product will remember

Write durable, confirmed information that can improve a later task.
Keep passwords, API keys, access tokens, hidden prompts, and encryption material out of memory.
Use source, tags, and small non-secret metadata values for application context.
Treat model-produced facts as untrusted until your product validates them.

Continue

Memory Object

Review writable and readable fields.

Add Memory API

See the endpoint contract.

← Previous

Overview

Retrieve Memory