Getting Started
Architecture at a Glance
This is the runtime shape of MemorySync from a caller's perspective: the request entry point, the route groups it exposes, and the work it does before the handler runs.
Mounted route groups
| Prefix | Mounted surface |
|---|---|
/memory | Memory routes — add, query, summarize, forget, compose, routed search, graph, clusters, decisions, intelligence, export, refresh, and purge. |
/auth | Signup, login, refresh, logout, and MFA. |
/org/* | API keys, projects, billing, webhooks, OAuth apps, and analytics. |
/api/v1 | Integrations, web crawler, lifecycle, explainability, and refusals. |
/scim/v2 | SCIM protocol routes. |
/sso/* and /oauth/* | SAML, OIDC, and OAuth browser flows. |
What runs before every request reaches a handler
- Authentication resolves the caller — either a JWT user or an API key.
- Project scope is resolved on project-scoped routes from the
X-Project-IDheader or a project-locked API key. - Quota checks run before
/memory/addand/memory/query. - Service-auth memory calls must identify the end user with
X-End-User-ID.
Request path for /memory/add
- Authentication and project scope must resolve successfully.
- Add-quota enforcement runs. When the org is over quota, the route silently returns
{"status":"ok"}without storing anything. - The route resolves the effective end user, overwrites client-supplied user, environment, and project values with trusted context, and runs the memory through the extraction pipeline.
- If a record was stored, the handler emits the memory-created webhook and returns the first stored
MemoryResponse.
Trust boundaries
The caller supplies credentials and request data, while the server resolves organization, project, environment, and effective end-user scope. Keep API keys server-side and use separate credentials for each environment.
Observe failures and asynchronous work
Treat the synchronous response as the request result, then use request IDs, audit events, and documented job status surfaces to investigate failures or follow work that completes after the handler returns.