Docs Memory API
How requests behave
The guarantees and behaviours to design around: asynchronous ingestion, idempotency, ordering, supersession, ranking and limits.
#Ingestion is asynchronous
A send is accepted with 202 and processed in the background. Recall reflects a record only after its job completes. In request/response flows where the user just said something, include their message in the prompt directly; don’t wait for memory.
#Idempotency and unchanged sends
Send an Idempotency-Key header on writes. A retry with the same key returns the original response and costs nothing. Separately, re-sending a record whose text, title, time, metadata and visibility are unchanged returns 200 with "state": "unchanged" and is not processed again.
#Ordering and late records
Records are placed by occurredAt. If an older record arrives after a newer one, it becomes history rather than the current value. Two records with the same timestamp are ordered by receivedAt.
#Supersession, not overwrite
A changed fact closes the old memory’s validity and opens a new one. Both remain queryable: the current one by default, the old one in history or via asOf. Deleting a record removes memories that depend only on it.
#Ranking and token budget
Recall scores visible memories by relevance to the query and recency, then packs them with their source excerpts until maxTokens is reached (up to 8,000 on Pay as you go and Flex, 32,000 on Enterprise). truncated: true means more matched than fit.
#Rate limits
| Plan | Requests per minute |
|---|---|
| Pay as you go | 500 |
| Flex | 750 |
| Enterprise | 1,000 |
Limits apply per project. Over the limit you receive 429 with Retry-After. Your project’s current limits are returned by GET /v1/project.