A Managed Agents session starts fresh. Whatever the agent learned last time (that you prefer two-space indent, that the deploy step needs a manual approval, that it botched the same migration last week) is gone the moment the session ends. That is the default, and for a one-shot task it is the right one. But an agent you come back to 5 days a week should not relearn you every morning.
The fix is a memory store: a workspace-scoped collection of text documents that mounts as a directory the agent reads and writes with its ordinary file tools. Preferences, conventions, prior mistakes, domain context. They go in the directory, and the next session finds them there. For the repo-level counterpart, where committed memory travels with the codebase itself, see Every new repo starts with your lessons.
01A directory, versioned
A memory store is a set of text files, each addressed by a path like
/formatting_standards.md. Attach one at session creation and it mounts under /mnt/memory/ at a
short name derived from the store’s name. Read the authoritative mount_path off the session’s
memory-store resource rather than constructing it yourself. The agent needs its file tools enabled
at agent creation to touch the mount at all. A description of every mount lands in the system prompt
automatically, so the agent knows what each store holds.
Two details make this safe to run in production. Every change creates an immutable memory version
(id prefix memver_), which is your audit trail and your way to restore an earlier version. Versions belong
to the store and survive after a memory is deleted, so the history stays complete. And writes only
persist if they land under the real mount path; a write anywhere else under /mnt/memory/ goes to
temporary local storage and vanishes when the session ends. The store stays in sync across every
session that shares it.
02read_only is the big decision
The access field defaults to read_write, and that default is risky. The docs say
why: a prompt injection from untrusted input can make one session write
malicious content, and a later session reads that content back as trusted memory.
It is the same threat model that Expertise you can install applies to a downloaded skill file: untrusted input you cannot afford to trust blindly. Access is enforced at the filesystem
level, so read_only genuinely rejects writes. Use it for reference material and any store the
agent has no business modifying. Reserve read_write for the sessions that actually add memories.
Every write to a read_write mount is attributed to its session in the version history, so you can
always see who wrote what.
03Know the caps before you hit them
The limits are hard, and each one fails in a specific way. A single memory caps at 100 kB, roughly
25 thousand tokens, which is why the docs push many small focused files over a few large ones. A
store holds at most 2,000 memories; at the cap, new writes fail (both memories.create and the
agent’s own writes to new paths) while existing memories stay readable and editable. A session
attaches at most 8 stores, and only in the resources[] array at creation time. You cannot add or
drop a store mid-session. Plan the attach list up front.
| Cap | Limit | What fails at it |
|---|---|---|
| Memory size | 100 kB, about 25 thousand tokens | Writing that memory at all |
| Memories per store | 2,000 | New writes; existing entries stay readable |
| Stores per session | 8, fixed in resources[] at creation | Attaching more, or swapping mid-session |
Because each store carries its own 2,000-memory budget, a healthy setup uses several
focused stores: a store per end user, a shared domain-knowledge store, a store
per project. A common pattern is one read_only shared reference store shared across many
sessions, plus a read_write store scoped to whoever is actually writing.
04Keeping it healthy over time
Stores rot the way any pile of notes rots. Three tools keep them clean. Prune stale entries with
memories.delete, cheap and direct, every 2 weeks or so: 10 minutes of pruning is better than letting a store sit at
90% of its cap, where it quietly confuses the agent. When a store fragments, a
dreaming session
consolidates its content into a separate new output store without touching the original; you then
switch sessions to the output store and archive the old one. And when a store outgrows its scope,
attach a fresh store for new content while reattaching the original as read_only, so the agent
reads both but writes only to the new one.
Two more endpoints matter for compliance. Rolling back has no dedicated restore call. Retrieve the
memver_ version you want and write it back with memories.update. And the redact endpoint scrubs
content from a historical version while preserving its metadata, for leaked secrets, personal data, or a user
deletion request. You cannot redact a live memory’s current version, so write a new version or delete
the memory first, then redact the old one.
Further reading
- Anthropic · Managed Agents memory stores, the primary documentation this guide works from
- Anthropic · dreaming sessions, consolidation for fragmented stores
- Greshake et al. · “Not what you’ve signed up for: Compromising Real-World LLM-Integrated Applications with Indirect Prompt Injection” (arXiv), the attack class behind the read_only advice
- Wikipedia · prompt injection, the survey view of the same threat
- Anthropic · Claude Code memory documentation, the repo-side counterpart