MEMORY.mdis 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.
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. In the API and the CLI this is theteam 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. 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 or the API.
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
A write is refused when the text holds a secret, or instructions aimed at a later Session. Keep secrets in the Vault.
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:
--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:
reason memory with no subcommand, and reason memory request GIB, are about a computer’s RAM, not about what Reasons remember.API
Every call takesscope=team and needs an API key with the scope shown. See Authentication and scopes.
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.

