Getting Started
How It Compares
This page compares the request modes and runtime behaviours of the MemorySync API. It does not compare MemorySync with external products.
Browser session auth vs service auth
| Question | Browser or session flow | Service-auth flow |
|---|---|---|
| How you authenticate | JWT tokens from /auth/login. | API keys from /org/api-keys in X-API-Key. |
| Who the end user is | The authenticated JWT user. | The caller must identify the end user with X-End-User-ID or end_user_id. |
| Project scope | X-Project-ID is still enforced on project-scoped routes. | Same rule, but a project-locked key can satisfy it automatically. |
JWT user context vs API-key end-user resolution
| Question | JWT route behaviour | Service-auth behaviour |
|---|---|---|
| Who owns the memory? | The backend uses the authenticated user id. | The backend resolves the end user from X-End-User-ID (or end_user_id in the body) and maps it to the corresponding user. |
Is body user_id trusted? | No. | No. |
Is X-End-User-ID used? | Ignored. | Required for service-auth memory callers. |
Project-locked key vs explicit project header
| Case | How project enforcement passes |
|---|---|
API key has project_id | The project-enforcement dependency can read the project from the active key. |
| API key is org-wide | Send X-Project-ID explicitly on project-scoped routes. |
| Bearer-token request | Send X-Project-ID explicitly unless the route is exempt. |
Query vs retrieve vs routed search vs compose
| Route | When to use it |
|---|---|
/memory/query | Default semantic retrieval route. |
/memory/retrieve | Compatibility alias. |
/memory/search/routed | Use when you want routed behaviour and a richer result model. |
/memory/compose | Use when the next step is prompt construction. |
Quota enforcement: Silent degradation
When your organization exceeds its plan quota, MemorySync uses silent degradation — no error is surfaced to your application:
| Operation | At-quota behaviour |
|---|---|
| Add memory | Returns 200 OK with {"status":"ok"} — memory is stored but not embedded. |
| Query memory | Returns 200 OK with {"memories":[]} — no results returned. |
Detection
Watch the usage dashboard for metrics approaching 100% of your plan limit. Webhook and email alerts can also be configured for at-quota and approaching-quota thresholds.