---
title: "Set a memory"
method: PUT
path: "/memories"
tags: ["Memories"]
---

# Set a memory

`PUT /memories`

Create or update a durable JSON memory under an org or function scope. Function-authenticated requests use their own Function id and cannot override it. If no explicit scope is provided for other credentials, `x-primitive-function-id` is used next, and other requests default to org scope. Function scope uses the function id UUID, not the function name.

## Headers

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

## Request body

- object
  - `key` string, required — Caller-defined key, at most 512 UTF-8 bytes.
  - `value` union, required — 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
  - `scope` union — Memory scope. `org` resolves to the authenticated organization. `function` requires the function id UUID in `id`; function names are not valid scope identifiers. Function-authenticated requests cannot override their own Function scope.
    - object
      - `type` 'org', required
    - object
      - `type` 'function', required
      - `id` string, uuid, required — Function id UUID.
  - `ttl_seconds` integer — Set or replace the TTL in seconds. Mutually exclusive with `expires_at` and `clear_ttl`.
  - `expires_at` string, date-time — Set or replace the absolute expiration timestamp. Mutually exclusive with `ttl_seconds` and `clear_ttl`.
  - `clear_ttl` boolean — Clear any existing TTL. Mutually exclusive with `ttl_seconds` and `expires_at`.
  - `if_absent` boolean — Create only when the key is absent. Mutually exclusive with `if_version`.
  - `if_version` string — Bigint counter serialized as a base-10 string.

## Response `200`

Existing memory updated.

- object
  - `success` true, required
  - `data` object, required — Memory record returned by get and set operations.
    - `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, required — 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

- `201` — Memory created.
- `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
- `409` — The request conflicts with the current state of the resource
- `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)