---
title: "Search memories"
method: GET
path: "/memories/search"
tags: ["Memories"]
---

# Search memories

`GET /memories/search`

List active memories in a scope by lexicographic key prefix. Results are ordered by key ascending. This is prefix search, not free-text search. Function-authenticated requests use their own Function id and cannot override it. Pass `include_value=false` to return metadata only.

## Query parameters

- `prefix` string
- `cursor` string
- `limit` integer
- `include_value` 'true' | 'false'
- `updated_after` string, date-time
- `updated_before` string, date-time
- `scope_type` 'org' | 'function'
- `scope_id` string, uuid

## Headers

- `x-primitive-function-id` string, uuid

## Response `200`

Paginated memory records.

- object
  - `success` true, required
  - `meta` object, required
    - `total` integer, required — Total number of matching records
    - `limit` integer, required — Page size used for this request
    - `cursor` string, nullable, required — Cursor for the next page, or null if no more results
  - `data` object[], required
    - `id` string, uuid, required
    - `key` string, required — Caller-defined key, at most 512 UTF-8 bytes.
    - `scope` object, required — Resolved memory scope returned by the API.
      - `type` 'org' | 'function', required
      - `id` string, uuid, required — Org id for org scope, function id for function scope.
    - `value` union — JSON value accepted by Primitive Memories. The server accepts strings, numbers, booleans, null, arrays, and objects, validates nested values, and rejects values that do not serialize as JSON.
      - string
      - number
      - boolean
      - MemoryJsonValue[]
        - union — JSON value accepted by Primitive Memories. The server accepts strings, numbers, booleans, null, arrays, and objects, validates nested values, and rejects values that do not serialize as JSON.
          - string
          - number
          - boolean
          - MemoryJsonValue[]
          - object
      - object
    - `version` string, required — Bigint counter serialized as a base-10 string.
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
    - `last_read_at` string, date-time, nullable, required — Last successful get timestamp, or null before any get.
    - `read_count` string, required — Bigint counter serialized as a base-10 string.
    - `write_count` string, required — Bigint counter serialized as a base-10 string.
    - `expires_at` string, date-time, nullable, required — Expiration timestamp, or null for no TTL.
    - `created_by` string, nullable, required — Actor that created the memory, when available.
    - `updated_by` string, nullable, required — Actor that last updated the memory, when available.

## Other responses

- `400` — Invalid request parameters
- `401` — Invalid or missing API key
- `402` — Usage credits are exhausted or payment is required.
- `403` — Authenticated caller lacks permission for the operation
- `404` — Resource not found
- `429` — Rate limit exceeded

---

[API](https://skmtc.dev/primitive/apis/primitive-api.md) · [All operations](https://skmtc.dev/primitive/apis/primitive-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/primitive/primitive-api/revisions/c2299d28022c/schema)