# Claude Managed Agents Memory Stores **Public beta since 2026-04-28; own beta header `agent-memory-2026-07-22` as of October 2026** (see Access below). [[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)** - A store holds at most **10,000 memories**. At the limit, new writes fail (API creates and the agent's writes to new paths); existing memories stay readable and editable. Each store has its own limit, so focused stores (per user, shared knowledge, per project) help - **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/<slug>/`, where the slug is the store's name lowercased with non-alphanumeric runs turned into hyphens ("Demo Memory" → `/mnt/memory/demo-memory/`). Read the exact path from the `mount_path` field on the session's memory-store resource. Writes elsewhere under `/mnt/memory/` fail (the parent is read-only) - 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. ### Self-hosted sandboxes Memory stores also attach to sessions on self-hosted environments (the only resource type those accept), but the directory is a local copy managed by your worker, not a live mount. The worker syncs after tool calls, at most once per sync interval (15 seconds by default) and once more at session end, so another self-hosted session sees a change only after both workers have synced. On [[Claude Platform on AWS]], self-hosted sessions can't attach memory stores at all. ### When to use multiple stores - **Shared knowledge** (read-only standards/conventions) separate from per-user **read-write** lessons - **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` (must end with `/`, matches whole segments) and `depth` (omit or `0` for the whole subtree, `1` for immediate children) so you can browse a store like a directory tree. Results come back in a stable, server-defined order (the earlier `order_by` parameter is no longer documented) - `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": "content_sha256", "content_sha256": "..."}`: optimistic lock on an edit; the update only applies if the stored hash still matches, otherwise re-read and retry. - ~~`precondition: {"type": "not_exists"}` (create-only, `409` if the path exists).~~ No longer in the docs as of October 2026; `create` still never overwrites an existing path. ## 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 lessons. 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. The docs suggest it as the way to recover from the 10,000-memory limit: switch sessions to the output store, then archive or delete the original. ## 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]].~~ As of October 2026, memory store endpoints use `anthropic-beta: agent-memory-2026-07-22` INSTEAD of `managed-agents-2026-04-01`: sending both on a memory store request returns a `400`. Session endpoints, including attaching a store to a session, still use `managed-agents-2026-04-01`. No research-preview form. Sessions, memory contents, and version history are all visible in the Claude Console. With `ant apply`, a memory store is a YAML file in `memory_stores/`. ## 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 (beta header, limits, mount paths; read 2026-10-03) - Self-hosted sandboxes and memory: https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes-memory - Claude Platform on AWS, Managed Agents section: https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws#claude-managed-agents - `ant apply`: https://platform.claude.com/docs/en/cli-sdks-libraries/cli/apply - Announcement: https://claude.com/blog/claude-managed-agents-memory ## Related - [[Claude Managed Agents]] - [[Claude Platform on AWS]] - [[Claude Managed Agents Dreams]] - [[Claude Managed Agents Sessions]] - [[Claude Managed Agents Events]] - [[Claude Managed Agents Tools]] - [[AI Agent Memory]] - [[Prompt injection]]