---
title: "Write a memory file"
method: PUT
path: "/v3/organizations/{orgId}/memory/file"
tags: ["Memory"]
---

# Write a memory file

`PUT /v3/organizations/{orgId}/memory/file`

## Request

- Base URL: `https://api.reasonmachines.com`
- URL: `https://api.reasonmachines.com/v3/organizations/{orgId}/memory/file`
- Auth: HTTP bearer

Creates a file or replaces its whole text. Reasons read the change from their next Session on: `MEMORY.md` is in every Session's starting context, so keep it short and put detail in topic notes, which a Session reads when it needs them.

Personal memory is the caller's own; team memory takes direct writes only from a Workspace owner or admin (403 for other members). The change is stored as a revision under the caller's name with no source Session, so it shows in memory history and can be restored. Paths are normalized (lower case, `.md` added); empty text (for a note), text over the size limit (32 KiB a note, 12 KiB `MEMORY.md`), or text holding a secret or instructions aimed at a later Session is refused with 422, and a new note in a folder that already holds 200 answers 409. Personal memory that its owner turned off cannot change (409 `memory_disabled`).

<sub>Scope: `memory:write`</sub>

## Request body

- WriteMemoryFile
  - `scope` 'personal' | 'team', required: `personal`: the memory of the person the API key or OAuth grant belongs to, private to them. `team`: the Workspace's shared team memory, which every member's Sessions read.
  - `path` string, required: The file's path within the scope: `MEMORY.md` (the index) or a note such as `web-app.md`. A name without an extension gets `.md`, and paths are lower case, so `Web-App` and `web-app.md` are one note. Personal notes may sit in up to three folders (`projects/web-app.md`); team notes sit at the top or in a place folder such as `reasons/<key>/`. A `memory:/` or `team:/` prefix is accepted and ignored.
  - `content` string, required: The file's complete new text; it replaces what the file holds. A note needs some text and at most 32 KiB; `MEMORY.md` at most 12 KiB. Text holding a secret, or instructions aimed at a later Session, is refused.
  - `expected_revision_id` string, nullable: The `revision_id` of the file as last read: the write is refused with 409 when the file has changed since. `null` requires that the file does not exist yet. Leave it out to replace whatever the file holds.

## Response `200`

The file as stored.

- MemoryWriteResponse
  - `scope` 'personal' | 'team': `personal`: the memory of the person the API key or OAuth grant belongs to, private to them. `team`: the Workspace's shared team memory, which every member's Sessions read.
  - `file` MemoryFile
    - `path` string
    - `content` string
    - `byte_length` integer
    - `updated_at` string, date-time, nullable
    - `revision_id` string, nullable: The revision this text is; send it as `expected_revision_id` to write only if nobody changed the file since.
  - `updated` boolean: False when the file already held this text, so nothing changed.

## Other responses

- `400`: Invalid request.
- `401`: Missing, invalid, or expired key.
- `403`: The key lacks the required scope or role.
- `409`: The request conflicts with the current resource state.
- `422`: The content was refused: empty, too large, holding a secret, or instructions aimed at a later Session. `message` says what to change.
- `429`: Too many requests. Retry after the number of seconds in the `Retry-After` response header.

## Changes

- **2026-10-26** `c250866428e0`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/ara/apis/reason-api/changes/v3/organizations/:orgId/memory/file/put.md)

---

[API](https://skmtc.dev/ara/apis/reason-api.md) - [All operations](https://skmtc.dev/ara/apis/reason-api/llms.txt) - [OpenAPI document](https://skmtc.dev/ara/apis/reason-api/revisions/e97c8704807c?raw)