How It Works
Processing & Availability
Build against the status and response your application receives. Internal workers, queues, caches, schedules, and ranking stages are intentionally not public contracts.
Use customer-visible state
| Operation | Completion signal |
|---|---|
| Add one memory | A created memory object or a skipped outcome in the response. |
| Bulk add | Per-item created, skipped, or rejected outcomes in the response. |
| Query | A memories array, including an empty array when nothing matches. |
| Connected-source sync | A sync job with status and progress fields that can be checked later. |
What a successful response means
- A created add response gives you the memory ID returned by the API.
- A skipped add response means no memory was created for that request outcome.
- A successful query may return zero memories.
- A created sync job is not the same as a completed sync; inspect its status.
- Do not infer hidden processing state from timing or undocumented fields.
Classify failures before retrying
| Result | Typical action |
|---|---|
| Authentication or permission error | Fix the credential, scope, or application authorization. |
| Validation error | Correct the request; do not retry the same payload unchanged. |
| Not found | Verify the resource ID and active scope. |
| Rate limited | Wait before retrying and follow retry guidance when provided. |
| Server or network failure | Retry with bounded backoff and record the final failure. |
Retry without creating a loop
- 1Classify the failure as permanent or temporary.
- 2Do not retry
created,skipped, or validation outcomes. - 3For temporary transport or server failures, use bounded exponential backoff with jitter.
- 4After the retry limit, surface a recoverable application state and retain enough context to investigate.
Log what your application can safely use
- Operation name, status code, duration, and your own non-sensitive correlation ID.
- Project and end-user references only when your logging policy allows them; prefer opaque values.
- Returned memory IDs or sync job IDs needed for support workflows.
- Never log API keys, tokens, full sensitive memory text, or hidden prompts.