# Claude Managed Agents Memory Stores **Public beta since 2026-04-28.** [[Claude Managed Agents|Managed Agent]] sessions are ephemeral by default; everything the agent learned dies with the container. **Memory stores** fix this. They are workspace-scoped collections of text documents that get mounted as a directory inside the session's container; the agent reads and writes them with the same file tools it uses for the rest of the filesystem. A note describing each mount is automatically appended to the system prompt so the agent knows where to look. No prompt engineering required. Each change creates an immutable **memory version**, giving point-in-time recovery and a full audit trail. ## The design choice that matters Memory is **mounted as a filesystem** under `/mnt/memory/`. Claude uses its normal [agent toolset](https://platform.claude.com/docs/en/managed-agents/tools) (bash, file ops) to list, read, write, and edit memory files. There is no parallel "memory tool surface" for the model to learn. The same files are addressable externally via the Memory Stores API for your own code to manage them. The [agent toolset](https://platform.claude.com/docs/en/managed-agents/tools) must be enabled on the agent for memory access to work; enable it at agent creation time. ## Mental model - Think of a memory store as a tiny versioned filesystem - Each memory is addressed by a path like `/preferences/formatting.md` - Individual memories cap at **100 KB (~25K tokens)** - **Design rule**: many small focused files, not a few big ones. Progressive disclosure beats context bloat. ## Create and seed ```python store = client.beta.memory_stores.create( name="User Preferences", description="Per-user preferences and project context.", ) client.beta.memory_stores.memories.create( store.id, path="/formatting_standards.md", content="All reports use GAAP formatting. Dates are ISO-8601...", ) ``` The store's `name` + `description` are passed to the agent so it knows when to consult it. ## Attach to a session Memory stores attach via the session's `resources[]` **at creation time only** — you cannot add or remove them from a running session. Up to **8 memory stores per session**. ```python session = client.beta.sessions.create( agent=agent.id, environment_id=environment.id, resources=[{ "type": "memory_store", "memory_store_id": store.id, "access": "read_write", # default; also: "read_only" "instructions": "Check before starting any task.", # max 4,096 chars }], ) ``` - `access` is **`read_write` by default** and is enforced at the filesystem level (a `read_only` mount rejects writes) - `instructions` (max 4,096 chars) is session-specific guidance; shown to the agent alongside the store's `name` + `description` - Mounted under `/mnt/memory/`; reads and writes appear in the [event stream](https://platform.claude.com/docs/en/managed-agents/events-and-streaming) as ordinary `agent.tool_use` / `agent.tool_result` events **Security warning**: `read_write` is the default but it's also the foot-gun. If the agent processes untrusted input (user prompts, fetched web content, third-party tool output), a successful [[Prompt injection|prompt injection]] could write malicious content into the store; later sessions then read it as trusted memory. Use `read_only` for reference material, shared lookups, and anything the agent doesn't need to modify. ### When to use multiple stores - **Shared knowledge** (read-only standards/conventions) separate from per-user **read-write** learnings - **One store per end-user / team / project** while sharing a single agent config - **Different lifecycles** — a long-lived store that outlives any session, or one you want to archive on its own schedule ## CRUD the memories directly Useful for review workflows, correcting bad memories, and seeding stores before any agent runs. The API has `list`, `retrieve`, `create`, `update`, `delete`. - `list` supports `path_prefix`, `order_by`, and `depth` so you can browse a store like a directory tree - `create` does **not** overwrite an existing path; use `update` to modify - `update` can change `content`, `path` (rename/move), or both - The Claude Console exposes the same operations in a UI ## Safe concurrent writes - `precondition: {"type": "not_exists"}` — create-only; returns `409` if path exists. Useful for seeding without clobbering. - `precondition: {"type": "content_sha256", "content_sha256": "..."}` — optimistic lock on an edit; retry on `409 memory_precondition_failed` after re-reading. ## Versions and audit Every mutation creates an **immutable memory version** (`memver_...`) with `operation` = `created` | `modified` | `deleted`. Versions belong to the **store**, not the individual memory, and **survive the parent memory's deletion** so the audit trail stays complete. - Per-version history with actor (session, API key) and timestamps - Retrieve prior content via the memory_versions endpoint - **Redact** any historical version to scrub leaked secrets or PII while preserving the audit trail (actor + timestamps stay, `content`/`path`/hash are hard-cleared). The head version of a live memory cannot be redacted — write a new version (or delete the memory) first, then redact the old one. - **No dedicated restore endpoint**: to roll back, fetch the version you want and write its `content` back via `memories.update` (or `memories.create` if the parent memory was deleted) **Retention**: versions are kept for 30 days; the most recent versions are always retained regardless of age (so a memory that rarely changes keeps history longer). For longer-term retention, export versions via the API. ## Multi-agent sharing A single store can be attached to many sessions and many agents at once. Typical pattern: an org-wide store mounted **read-only** holding standards and conventions, plus a per-user store mounted **read-write** for personal learnings. Concurrent agent access is safe because every mutation is versioned; combine with `content_sha256` preconditions when two agents may edit the same file. ## Store lifecycle - `archive` makes a store read-only and prevents attaching it to new sessions. **One-way; there is no unarchive.** - `delete` permanently removes a store along with its memories and versions - `list` excludes archived stores by default; pass `include_archived: true` to include them ## Portability Memory entries are plain files. Export, archive, diff, or migrate between stores; no platform lock-in beyond the API. Layer version-control workflows (review before promotion, rollback) on top for free. ## Real-world results From Anthropic's announcement (vendor-reported): - **Rakuten**: 97% fewer first-pass errors, 27% lower cost, 34% lower latency on long-running task agents - **Wisedocs**: 30% faster document verification by recognising recurring issues across sessions - **Netflix**: agents carry context across sessions without manual prompt updates; mid-conversation human corrections persist - **Ando**: captures organisational interaction patterns without building custom memory infrastructure ## Curation Memory stores accumulate duplicates, contradictions, and stale entries over many sessions. [[Claude Managed Agents Dreams|Dreams]] (research preview) is the answer: a non-destructive curation job that reads the store + past sessions and produces a *new* reorganised output store you can adopt or discard. ## Access and beta header Public beta since 2026-04-28. Same `anthropic-beta: managed-agents-2026-04-01` header as the rest of [[Claude Managed Agents]]; no separate research-preview form. Sessions, memory contents, and version history are all visible in the Claude Console. ## Default limits Default capacity and rate limits apply during beta. Contact support for higher limits. ## References - https://platform.claude.com/docs/en/managed-agents/memory - Announcement: https://claude.com/blog/claude-managed-agents-memory ## Related - [[Claude Managed Agents]] - [[Claude Managed Agents Dreams]] - [[Claude Managed Agents Sessions]] - [[Claude Managed Agents Events]] - [[Claude Managed Agents Tools]] - [[AI Agent Memory]] - [[Prompt injection]]