OAuth Memory API
The memory operations available to third-party OAuth applications. Authentication is an OAuth 2.0 bearer access token issued by the MemorySync authorization flow — not an API key — and every operation is bound to the user who granted consent.
Authentication and scopes
Register an OAuth application in the dashboard (Settings → OAuth Apps), send the user through the consent flow, and exchange the authorization code for tokens. Discovery documents are published at /.well-known/oauth-authorization-server. These endpoints require a user-scoped token from the authorization_code grant; a client_credentials token is rejected with 400 because there is no user to act for.
| Scope | Grants |
|---|---|
memory:read | Query and list the granting user's memories. |
memory:write | Store new memories for the granting user. |
memory:delete | Delete the granting user's memories. |
Store a memory
Runs the same extraction pipeline as every other write surface — there is no raw-storage branch, and pure chatter returns 201 with status: "skipped".
| Field | Type | Contract |
|---|---|---|
text | string | Required raw content, minimum 10 characters. |
source | string | Optional origin label. Defaults to oauth. |
metadata | object | Optional metadata persisted with stored candidates. |
tags | string[] | Optional semantic tags. |
importance | number | Optional importance hint, 0.0–1.0. |
deduplicate | boolean | Defaults to true. |
{"memory_id":"m_402","status":"created","memory_ids":["m_402"],"candidates_extracted":1,"candidates_stored":1,"candidates_updated":0,"candidates_deduped":0,"candidates_rejected":0}
curl --request POST https://api.memorysync.io/v1/oauth/memories \--header "Authorization: Bearer $OAUTH_ACCESS_TOKEN" \--header "Content-Type: application/json" \--data '{"text":"Prefers release notes as bullet points.","tags":["preference"]}'
Query memories
| Field | Type | Contract |
|---|---|---|
query | string | Required natural-language query. |
k | integer | Optional result ceiling, 1–50. Defaults to 5. |
filters | object | Optional filter object. |
{"memories":[{"memory_id":"m_402","text":"Prefers release notes as bullet points.","source":"oauth","summary":null,"metadata":null,"importance":0.5,"score":0.9,"created_at":"2026-08-22T10:00:04Z"}],"count":1}
curl --request POST https://api.memorysync.io/v1/oauth/memories/query \--header "Authorization: Bearer $OAUTH_ACCESS_TOKEN" \--header "Content-Type: application/json" \--data '{"query":"formatting preferences","k":5}'
List memories
| Parameter | Type | Contract |
|---|---|---|
limit | integer query | Optional page size. Defaults to 50. |
offset | integer query | Optional page offset. Defaults to 0. |
Returns the granting user's memories newest-first. total is the number of records in this page.
curl "https://api.memorysync.io/v1/oauth/memories?limit=50&offset=0" \--header "Authorization: Bearer $OAUTH_ACCESS_TOKEN"
Delete memories
| Field | Type | Contract |
|---|---|---|
memory_ids | string[] | Required IDs to delete, in the m_… form returned by other operations. |
Only memories owned by the granting user are deleted; unknown or unowned IDs are skipped rather than reported, so compare deleted_ids with what you sent.
{"deleted_ids":["m_402"]}
curl --request DELETE https://api.memorysync.io/v1/oauth/memories \--header "Authorization: Bearer $OAUTH_ACCESS_TOKEN" \--header "Content-Type: application/json" \--data '{"memory_ids":["m_402"]}'
Quota behaviour
Errors and next action
A 401 means a missing, expired, or revoked token — run the refresh flow. A 403 means the token lacks the required scope; request the scope during consent instead of retrying. A 400 with "requires a user-scoped token" means the token came from client_credentials; use the authorization_code grant.