SmartMemory
GET
/memory/list

List all memories for the current user, optionally filtered by type and metadata.

Requires authentication and operates on user-scoped data. SecureSmartMemory automatically handles tenant isolation.

GRAPH-API-1l: supersedes GET /memory/by-metadata for metadata lookups: same filter, but with this route's pagination and total. Filters only ever narrow the caller's own accessible set. They can never surface an item the caller could not otherwise see. See docs/features/GRAPH-API-1l/list-filters-contract.json.

SVC-LIST-EXCLUDE-ENTITY-1: exclude_node_category (repeatable) and q narrow the set the same way, before pagination, so total is the filtered count.

Authorization

AuthorizationBearer <token>

Send Authorization: Bearer <token>. The token is either a Clerk session JWT or a SmartMemory API key (prefix sm_live_, sm_test_, or legacy sk_).

In: header

Query Parameters

limit?Limit
offset?Offset
order?Order
metadata_key?|

Metadata key to filter on (exact match). Nested keys use dot syntax, e.g. profile.tier. Must be supplied together with metadata_value.

metadata_value?|

Value the metadata key must equal. Must be supplied together with metadata_key.

memory_type?|

Exact memory type filter

include_grounding?|

Include grounding nodes. Omit to inherit workspace then env (default OFF)

cursor?|

Opaque page cursor from a previous response's next_cursor

exclude_node_category?array<string>|

Node categories to leave out, repeatable (for example exclude_node_category=entity). Applied before pagination, so total counts the filtered set.

q?|

Case-insensitive substring match over content, applied before pagination like the other filters.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/memory/list"
{
  "items": [
    {}
  ],
  "total": 0,
  "limit": 0,
  "offset": 0,
  "policy": {
    "include_grounding": true,
    "source": "request"
  },
  "next_cursor": "string",
  "has_more": true,
  "skipped_rows": 0,
  "unattributable_skipped_rows": 0
}
{
  "detail": {
    "code": "invalid_scoped_validity",
    "message": "string",
    "retryable": false
  }
}
{
  "detail": {
    "code": "invalid_scoped_validity",
    "message": "string",
    "retryable": false
  }
}
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}
{
  "detail": {
    "code": "invalid_scoped_validity",
    "message": "string",
    "retryable": false
  }
}