Memory Scopes
Every memory entry names exactly one scope: where it is visible. There are five, and the visibility rule for each is enforced on every read — listing, search, and direct fetch alike.
| Scope | Written as | Who can see it |
|---|---|---|
| Agent | agent | Only the agent that owns it. Private — no other agent, no other client. |
| Session | session | Only the session it belongs to. An agent with no live session cannot write one. |
| Workspace | workspace (the default) | Every agent in that workspace. |
| Project | — (created by pinning) | Every workspace linked to the project — the project follows the folder, not the workspace. |
| Global | global | Everyone, everywhere — including an agent that has no workspace at all. |
Writing into a scope
memory_add accepts agent, workspace (the default when no scope is passed), global, and session. Two constraints apply:
- No workspace, global only. An agent that belongs to no workspace can only write
global-scoped entries — the other scopes are meaningless without one, and the call says so. - No live session, no session scope. Writing
sessionscope requires the caller to have a live session to bind the entry to.
Project scope is not writable through memory_add. Project-scoped entries are created by the pinning flow — Pin as Project Rule… / Pin as Data Mapping… and promotion in the Pinned Memory panel — because they can end up exported into committed project files. See Pinning & Promotion.
What an agent recalls
At recall time an agent reads the union of its scopes: its own private entries, its live session's entries, its workspace's entries, the entries of the project resolved from its session's working directory, and every global entry. Relevance search (memory_query) and listing (memory_list) both operate over exactly this visible set, and memory_list can filter to one scope.
How surfaces group the scopes
Two surfaces show scopes in a deliberately coarser vocabulary:
- The Memory card on an agent's page buckets counts as Private, Session, Workspace, Project, Global — every project folds into one Project bucket, every session into one Session bucket. See Memory card.
- The Pinned Memory panel's scope chips are Project, Workspace, Global only. Agent-private and session scopes have no chip on purpose: a pin surface only ever lists durable rules and data mappings, and those are never private or session-bound.
Session scope is durable
A session-scoped entry does not expire when the session closes. It is durable — it survives a restart — it simply stops being visible to callers whose session identity no longer matches. If it should not outlive the session, delete it deliberately with memory_delete.
Where to go next
- Memory tools — the tool-level contract.
- Project Model — what a "project" is and how it differs from a workspace and a repository.
- Versions & Deletion — what happens to an entry over time, in any scope.