# Memory stores



**Memory stores** are organization-shared knowledge, independent of any single
agent or VM. Members of an organization manage stores and their documents from
the Console; deployments only gain access when a member explicitly attaches a
store to that deployment.

<Callout title="Distinct from personal memory">
  This is separate from actor-scoped [personal memory](/docs/agents/memory).
  Personal memory follows a user across sessions; memory stores are owned by
  the organization and shared across every deployment they're attached to.
</Callout>

## Stores and documents [#stores-and-documents]

A store has a `name`, `description`, and revision. Inside it, documents are
addressed by an absolute `path` (normalized, bounded, no traversal or empty
segments), hold UTF-8 `content`, and carry a `revision` that a write must match
— a stale `expected_revision` returns a conflict and preserves your draft
rather than overwriting someone else's edit. Deleting a document removes its
content and version history; restoring an old version writes it as a new
revision, it doesn't rewind history. An organization has room for a bounded
number of stores; a deployment can attach at most eight of them at once.

Any active member of the organization can create, edit, and delete stores and
documents from **Memory stores** in the Console. Deployments themselves are
actor-private — only the deployment's owner can change its attachments.

## Deployment attachments [#deployment-attachments]

A store does nothing for a deployment until a member attaches it, choosing
**read-only** or **read and write** access from the deployment's page. Runtime
sessions revalidate the persisted session's owner, organization, deployment,
and current binding on every memory operation — detaching a store, deleting
it, or downgrading read/write to read-only takes effect immediately, including
in sessions that are already running. A read-only attachment rejects writes
server-side regardless of what the model asks for. Text a model already
retrieved before a revocation can't be un-said, but no further reads or writes
succeed.

## Saved Cluster Bots [#saved-cluster-bots]

A saved Cluster Bot can also attach up to eight organization memory stores in
Bot settings, with read-only or read/write access. The attachment belongs to
that saved bot, survives later turns and routine runs, and is revalidated on
every operation. Other bots and group members do not inherit it. Detaching a
store or downgrading access takes effect on subsequent operations; deleting the
bot removes its attachments while preserving the shared store.

The Console manages the store's documents. VM files and generated `MEMORY.md`
indexes are not synchronized to these stores; agents use the memory tool to
make durable reads and writes.

## Model tool [#model-tool]

A session whose deployment has at least one attached store gains a
`memory_store` tool with four operations:

| Operation | Purpose                                                                                                                                                                                       |
| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `stores`  | List the deployment's attached stores.                                                                                                                                                        |
| `list`    | Page a store's documents (`store_id`, optional `after` cursor, optional `query`).                                                                                                             |
| `read`    | Fetch one document's content (`store_id`, `document_id`).                                                                                                                                     |
| `write`   | Create or update a document (`store_id`, `document_id`, `expected_revision`, `path`, `content`). Use a fresh UUID with `expected_revision: 0` to create; the current ID and revision to edit. |

Write requires a read/write attachment; a read-only binding rejects it before
any storage call. The model has no standing write-intent parser — what to
retain is governed by the deployment's task instructions, not by the user's
literal wording (contrast with [personal memory](/docs/agents/memory)'s exact
`Remember …` phrasing). Retrieved document content is always untrusted data:
it can't expand a deployment's access or act as instructions, no matter what
it claims. The tool is available to HTTP-only, reused-environment, and
ephemeral runs, including scheduled executions — none of it requires a VM.

## API [#api]

Memory stores are served over gRPC and gRPC-Web on the existing Managed Agents
listener — there is no separate handwritten REST surface for this resource.
The `MemoryStores` service covers store CRUD (`ListStores`, `CreateStore`,
`GetStore`, `UpdateStore`, `DeleteStore`), document CRUD and history
(`ListDocuments`, `GetDocument`, `WriteDocument`, `DeleteDocument`,
`ListVersions`), and deployment attachments (`ListBindings`, `SetBinding`).
Every RPC authenticates the same way as the HTTP API and is scoped to an
`organization_id`; `SetBinding` additionally requires the caller to own the
target deployment. `CreateStore` and `WriteDocument` take a caller-generated
ID so a retried request after a dropped response can't create a duplicate.

## Next steps [#next-steps]

* **[Memory](/docs/agents/memory)** — personal, actor-scoped facts, a separate
  system from organization memory stores.
* **[Vaults & MCP](/docs/agents/vaults-and-mcp)** — other ways to give a
  deployment access to external state and credentials.