Skip to main content
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. 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. 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.
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

A write is refused when the text holds a secret, or instructions aimed at a later Session. Keep secrets in the Vault. 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:
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:
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. 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.

Moving memory from another agent

The migrate-to-reason skill moves memory files, notes and learned facts from another agent platform into Reason memory.