REST API endpoints for memory CRUD operations

The /memories endpoints cover the full lifecycle of a memory record: creating, reading, updating, deleting, and paginated listing. All five operations share the same Memory response schema and the same error envelope described in Error codes and HTTP status mapping.

POST /memories

Add a new memory record. Returns the created Memory object with a provider-assigned id.

Request body

string

required

The text content of the memory. This is the only field that all providers are required to index and return.

string

required

The user this memory belongs to. All memory operations are scoped to a user_id.

string

Slash-delimited hierarchical namespace, e.g. coding/preferences or health/symptoms. Used to filter and access-control memories. See Scopes for full scope semantics.

string[]

Free-form labels attached to this memory. You can filter by a single tag using GET /memories?tag=<value>.

object

Origin metadata for the memory.

Show source properties

string

Name of the application that created the memory (e.g. cursor, chatgpt).

string

How the memory was created. One of extracted, explicit, or imported.

string

An opaque pointer back to the source — a session ID, document ID, or similar.

number

A float between 0 and 1 indicating how confident the system is in this memory. Defaults to null if omitted.

string

ISO 8601 datetime from which this memory is considered valid.

string

ISO 8601 datetime after which this memory is no longer valid. Pass null for no expiry.

string[]

List of memory IDs that this record replaces. Useful when updating a fact while preserving history.

Response — 201 Created

string

required

Provider-assigned unique identifier for the memory (e.g. mem_abc123).

string

required

The stored text content.

string

required

The user this memory belongs to.

string

required

ISO 8601 datetime when the record was created.

string

Scope if provided at creation time.

string[]

Tags if provided at creation time.

object

Source metadata if provided at creation time.

number

Confidence score between 0 and 1.

string

Validity start datetime.

string

Validity end datetime, or null.

string[]

IDs of memories this record supersedes.

string

The embedding model used to index the content, if reported by the provider.

string

ISO 8601 datetime of the last update.

string

Ingestion lifecycle state. One of queued, indexing, done, or failed. Synchronous providers always return done. Absent or null means the provider does not track ingestion state.

Example

curl -s -X POST http://localhost:8080/memories \
  -H "Content-Type: application/json" \
  -d '{
    "content": "User prefers pnpm over npm",
    "user_id": "u1",
    "scope": "coding/preferences",
    "tags": ["tooling", "nodejs"],
    "source": { "app": "cursor", "type": "extracted" },
    "confidence": 0.92
  }'

{
  "id": "mem_abc123",
  "content": "User prefers pnpm over npm",
  "user_id": "u1",
  "scope": "coding/preferences",
  "tags": ["tooling", "nodejs"],
  "source": { "app": "cursor", "type": "extracted", "ref": null },
  "confidence": 0.92,
  "valid_from": null,
  "valid_to": null,
  "supersedes": null,
  "embedding_model": "text-embedding-3-small",
  "created_at": "2026-04-27T10:00:00Z",
  "updated_at": "2026-04-27T10:00:00Z",
  "status": "done"
}

GET /memories/{id}

Retrieve a single memory by its ID.

Path parameters

string

required

The memory ID returned when the record was created (e.g. mem_abc123).

Response — 200 OK

Returns the Memory object. Returns 404 with a not_found error code if the ID does not exist.

Example

curl -s http://localhost:8080/memories/mem_abc123

{
  "id": "mem_abc123",
  "content": "User prefers pnpm over npm",
  "user_id": "u1",
  "scope": "coding/preferences",
  "tags": ["tooling", "nodejs"],
  "created_at": "2026-04-27T10:00:00Z",
  "updated_at": "2026-04-27T10:00:00Z",
  "status": "done"
}

PATCH /memories/{id}

Update one or more fields of an existing memory. All fields in the request body are optional — only the fields you include are modified.

Path parameters

string

required

The ID of the memory to update.

Request body

string

New text content for the memory.

string

Updated scope path.

string[]

Replacement tag list. The entire list is replaced, not merged.

number

Updated confidence score between 0 and 1.

string

Updated expiry datetime, or null to remove the expiry.

string[]

Updated list of memory IDs that this record replaces.

Response — 200 OK

Returns the full updated Memory object. Returns 404 if the ID does not exist.

Example

curl -s -X PATCH http://localhost:8080/memories/mem_abc123 \
  -H "Content-Type: application/json" \
  -d '{
    "content": "User prefers bun for new projects",
    "supersedes": ["mem_abc123"]
  }'

DELETE /memories/{id}

Permanently delete a memory. This action cannot be undone.

Path parameters

string

required

The ID of the memory to delete.

Response — 204 No Content

Returns an empty body on success. Returns 404 if the ID does not exist.

Deletion is permanent. If you want to preserve history while marking a memory as replaced, use PATCH /memories/{id} with the supersedes field instead.

Example

curl -s -X DELETE http://localhost:8080/memories/mem_abc123
# (empty body, HTTP 204)

GET /memories

Return a paginated list of memories for a user, with optional filtering by scope, tag, and time range.

Query parameters

string

required

Return only memories belonging to this user.

string

Glob pattern to filter by scope, e.g. coding/* returns all memories under the coding/ hierarchy.

string

Return only memories that have this tag. To filter by multiple tags, call the endpoint multiple times and intersect client-side, or use GET /memories/search.

string

ISO 8601 datetime. Return only memories created at or after this time.

string

ISO 8601 datetime. Return only memories created before or at this time.

integer

default:"50"

Maximum number of results per page. Maximum is 500.

string

Opaque pagination cursor from the previous response’s next_cursor field. Omit to start from the beginning.

Response — 200 OK

Memory[]

required

The list of memory records for this page.

string

Opaque string to pass as cursor in the next request. null when there are no more results.

Pagination example

# First page
curl -s "http://localhost:8080/memories?user_id=u1&limit=2"

{
  "items": [
    { "id": "mem_abc123", "content": "User prefers pnpm over npm", "..." },
    { "id": "mem_def456", "content": "User prefers dark mode", "..." }
  ],
  "next_cursor": "eyJvZmZzZXQiOjJ9"
}

# Second page — pass the cursor from the previous response
curl -s "http://localhost:8080/memories?user_id=u1&limit=2&cursor=eyJvZmZzZXQiOjJ9"

{
  "items": [
    { "id": "mem_ghi789", "content": "User is based in Berlin", "..." }
  ],
  "next_cursor": null
}

Treat next_cursor as an opaque value. Its internal structure is provider-defined and may change across releases.

Overview

Endpoints

REST API endpoints for memory CRUD operations

POST /memories

Request body

Response — 201 Created

Example

GET /memories/{id}

Path parameters

Response — 200 OK

Example

PATCH /memories/{id}

Path parameters

Request body

Response — 200 OK

Example

DELETE /memories/{id}

Path parameters

Response — 204 No Content

Example

GET /memories

Query parameters

Response — 200 OK

​POST /memories

​Request body

​Response — 201 Created

​Example

​GET /memories/{id}

​Path parameters

​Response — 200 OK

​Example

​PATCH /memories/{id}

​Path parameters

​Request body

​Response — 200 OK

​Example

​DELETE /memories/{id}

​Path parameters

​Response — 204 No Content

​Example

​GET /memories

​Query parameters

​Response — 200 OK

​Pagination example

POST /memories

Request body

Response — 201 Created

Example

GET /memories/{id}

Path parameters

Response — 200 OK

Example

PATCH /memories/{id}

Path parameters

Request body

Response — 200 OK

Example

DELETE /memories/{id}

Path parameters

Response — 204 No Content

Example

GET /memories

Query parameters

Response — 200 OK

Pagination example