> ## Documentation Index
> Fetch the complete documentation index at: https://ara-90a60a07.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Memory

> Memory is what Reasons remember across Sessions: a short index, MEMORY.md, and topic notes. Who can change it, its limits, and the CLI and API for it.

Memory is what Reasons remember across Sessions. It is a set of plain Markdown files:

* **`MEMORY.md`** is a short index. Every Session starts by reading it.
* **Topic notes**, such as `web-app.md`, hold the detail. A Session gets the list of notes when it starts and reads a note when its topic comes up.

Keep `MEMORY.md` short, because it is in every Session's starting context. Put detail in topic notes.

## Memory belongs to the Workspace

Memory is shared: every member's Sessions read the same files, like the Workspace's [skills and secrets](https://ara-90a60a07.mintlify.site/docs/workspaces.md#what-the-workspace-shares). In the API and the CLI this is the `team` scope.

Older Workspaces also had a `personal` scope, read only by one person's Sessions. Elsewhere, the API answers a personal-scope request with `409 workspace_memory_scope_required`; use `team`.

Reasons treat memory as reference, not as instructions: a note cannot override what you ask for in a Session.

## How memory changes

* **Reasons save to it.** Ask a Reason to remember something, and it saves the fact to a note and links the note from `MEMORY.md`. Each saved fact carries a link to the Session it came from and the date.
* **You edit it.** Open [**Customize**, then **Memory**](https://reasonmachines.com/customize?tab=memory). **Memories** lists the saved files. Open one and choose **Edit** to change it, or **Delete note** to remove it. Saving replaces the note for everyone.
* **Scripts write it**, from the [CLI](#from-a-terminal) or the [API](#api).

A change reaches Reasons from their next Session on.

Every change is stored as a revision, with who made it. **Changes** on the same page lists them, including text that was since deleted, and restores an earlier version or a deleted note. A restore is itself a new revision, so nothing in the history is lost.

## Who can change team memory

Every member of the Workspace reads team memory. Every member but a viewer writes, deletes and restores its notes.

## Limits and rules

| Rule | Value |
| - | - |
| Size of a topic note | 32 KiB |
| Size of `MEMORY.md` | 12 KiB |
| Notes | 200 in one folder |
| Paths | Lower case, and `.md` is added: `Web-App` and `web-app.md` are one note |
| `MEMORY.md` | Cannot be deleted. Rewrite it shorter instead |

A write is refused when the text holds a secret, or instructions aimed at a later Session. Keep secrets in the [Vault](https://ara-90a60a07.mintlify.site/docs/vault.md).

## Search

Memory search finds lines that contain your words. It is a plain, case-insensitive match, with `|` between alternatives (`deploy|release`). It is not a regular expression and not a semantic search.

## From a terminal

`reason memory` reads memory:

```bash theme={null}
reason memory list --team                       # the files, the index first
reason memory show --team                       # MEMORY.md
reason memory show web-app.md --team            # one note
reason memory search "deploy|release" --team    # matching lines
```

Add `--json` for machine-readable output.

To write, use `reason team-memory` with JSON input. `reason tools describe writeMemoryFile` documents the fields and the revision check:

```bash theme={null}
reason team-memory list
reason team-memory read web-app.md
reason tools describe writeMemoryFile
```

> [!NOTE]
>
> `reason memory` with no subcommand, and `reason memory request GIB`, are about a computer's RAM, not about what Reasons remember.

## API

Every call takes `scope=team` and needs an API key with the scope shown. See [Authentication and scopes](https://ara-90a60a07.mintlify.site/docs/build/auth-and-scopes.md).

| Do | Call | Scope |
| - | - | - |
| List the files | [`GET /v3/organizations/{orgId}/memory/files`](https://ara-90a60a07.mintlify.site/api-reference/memory/list-memory-files) | `memory:read` |
| Read a file | [`GET .../memory/file`](https://ara-90a60a07.mintlify.site/api-reference/memory/read-a-memory-file) | `memory:read` |
| Search | [`GET .../memory/search`](https://ara-90a60a07.mintlify.site/api-reference/memory/search-memory) | `memory:read` |
| List the history | [`GET .../memory/history`](https://ara-90a60a07.mintlify.site/api-reference/memory/list-memory-history) | `memory:read` |
| Write a file | [`PUT .../memory/file`](https://ara-90a60a07.mintlify.site/api-reference/memory/write-a-memory-file) | `memory:write` |
| Delete a note | [`DELETE .../memory/file`](https://ara-90a60a07.mintlify.site/api-reference/memory/delete-a-memory-file) | `memory:write` |
| Restore a revision | [`POST .../memory/restore`](https://ara-90a60a07.mintlify.site/api-reference/memory/restore-a-memory-revision) | `memory:write` |

A write replaces the file's whole text. To change a file only if nobody changed it since you read it, send the `revision_id` you read back as `expected_revision_id`; the write is refused with `409` when the file has changed.

```bash theme={null}
curl -sS -X PUT "https://api.reasonmachines.com/v3/organizations/$ORG_ID/memory/file" \
  -H "Authorization: Bearer $REASON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "team",
    "path": "web-app.md",
    "content": "The web app deploys from the main branch."
  }'
```

## Moving memory from another agent

The [migrate-to-reason skill](https://ara-90a60a07.mintlify.site/docs/migrate-to-reason.md) moves memory files, notes and learned facts from another agent platform into Reason memory.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.