Deep Dive

Memory Contract

Understand the fields and outcomes your application can safely build against—without depending on private storage or processing details.

The public object at a glance

Memory response anatomy

Memory object

A created or retrieved memory has a stable identity and text, plus optional context your application may use when present.

id: Returned by the API
Store and pass this value; do not construct or interpret its format.
text: Durable context
Treat it as untrusted application data, not as model instructions.
created_at: Creation time
Use the returned timestamp when your product needs ordering or display.
source · tags · metadata: Optional context
Use small, non-secret values for traceability and supported filters.
importance: Optional 0–1 weight
A product hint, not a probability or guaranteed result position.
summary · tier · enrichment: Optional response data
Render defensively because these fields may be absent.

Choose what belongs in memory

What are you about to store?

A confirmed preference, fact, decision, or outcome

It can improve a later task and has a clear application purpose.

Use: Store one focused memory with a source or stable tag.

A temporary instruction for this request

It only matters to the current model call or UI action.

Use: Keep it in current request context instead of durable memory.

A credential, hidden prompt, or access token

Secrets create unnecessary exposure and are not memory content.

Use: Keep it in a secret manager and never submit it.

Unverified model-produced information

Generated claims can be wrong or manipulated by untrusted input.

Use: Validate it in your application before deciding whether to store it.

Write only documented fields

Field	Python and Node.js add	REST add	Purpose
`text`	Yes	Yes (`content` alias accepted)	The information to remember.
`source`	Yes	Yes	Origin label such as `profile` or `support`.
`tags`	Yes	Yes	Stable labels usable by retrieval filters.
`metadata`	Yes	Yes	Small application-owned JSON context.
`importance`	Yes	Yes	Optional weight from `0.0` to `1.0`.
`session_id`	Yes	Use the API reference	Optional related-session context.
`event_type` · `ttl_minutes` · `deduplicate`	Not exposed by single-add SDK methods	Documented REST fields	Use only when calling the REST contract directly.

Add and branch on the result

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.",
    source="profile",
    tags=["preference"],
    importance=0.7,
    metadata={"setting_id": "response-style"},
)

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

A successful call has two normal outcomes

Add outcome rail

201

Created

Use the returned memory object and its id.

200

Skipped

No memory was created. Read the reason and do not retry unchanged input.

4xx

Request needs correction

Fix authentication, scope, or validation before trying again.

Customer-visible lifecycle

01
Add
POST
Submit useful text and inspect whether the result is created or skipped.
02
Read
GET / query
Fetch by returned ID or retrieve candidates with a query.
03
Update
PATCH
Replace tags, importance, metadata, source, or event type. Text and scope are not editable.
04
Forget
DELETE
Delete selected memory IDs through your account, consent, or support workflow.

Continue

Retrieval Contract

See query inputs, filters, and result handling.

Memory API

Look up endpoint-specific request and response fields.

← Previous

Connected Sources