What Should Actually Persist in Your Bot's Memory Across Sessions?

The problem persistent memory is trying to solve

A bot that starts fresh every session is safe but expensive. It re-reads the same policy document, re-asks the same preference question, and re-derives the same conclusion it reached yesterday. Anthropic's Managed Agents documentation states the default plainly: each session starts with a fresh context, and when a session ends, any state the agent built up is gone. That's the baseline every persistent-memory decision is pushing back against.

The same gap exists at the raw API level, not just inside a managed agent platform. The memory tool lets Claude store and retrieve information across conversations through a memory file directory, so it can build knowledge over time without keeping everything in the context window. Both mechanisms solve the same underlying problem: the context window is temporary, and some facts shouldn't have to be re-derived every time it resets.

Sources: Using agent memory - Claude Platform Docs, Memory tool - Claude Docs.

Two different answers, two different control points

Anthropic ships two mechanisms that answer this question differently, and the difference matters for who controls what gets written. The memory tool is client-side: you implement the file operations yourself, and the model decides what to save and when, guided by whatever instructions you give it. The documentation is explicit that the memory tool operates client-side and you control where and how the data is stored through your own infrastructure. It's currently in beta, requiring a specific beta header on API requests.

Managed Agents memory stores work differently. A memory store is a workspace-scoped collection of text documents that gets mounted as a directory inside the session's sandbox when you attach it. The agent reads and writes it with the same file tools it uses for the rest of the filesystem, and every change to a memory creates an immutable memory version, giving you an audit trail and point-in-time recovery for everything the agent writes. That audit trail is the structural difference: with the memory tool, recovery from a bad write is your problem; with Managed Agents memory stores, Anthropic's platform keeps version history for you. It is not an indefinite backup: Anthropic says versions are retained for 30 days after writing, while recent versions of a live memory remain available beyond that window. Export version history if you need a longer recovery period.

Memory also pairs with, but is distinct from, context management techniques that clear old conversation content. Context editing clears specific tool results on the client or server side, while compaction summarizes the whole conversation when it nears the context limit. For long-running agents, the two are complementary: compaction keeps the active context small without client-side bookkeeping, and memory preserves the information that must survive summarization. Memory isn't a replacement for context management, it's the thing you point context management at so it doesn't throw away what matters.

Sources: Memory tool - Claude Docs, Using agent memory - Claude Platform Docs, Context editing - Claude Platform Docs.

A worked example: splitting reference facts from learned facts

Illustrative example. Say you're building a support bot for a fictional company, Acme Helpdesk, that should remember each customer's past tickets and preferences without re-explaining the refund policy every session. The naive approach is one memory store that holds everything. The better approach, and the one Anthropic's own announcement describes as a common pattern, is two stores with different access scopes: an org-wide store might be read-only, while per-user stores allow reads and writes. Acme's bot gets one read-only store for refund rules and tone guidelines that never change session to session, and one read-write store per customer for preferences and ticket history that the bot is actually supposed to update.

This isn't just a style choice. The default access level on a memory store is read_write, enforced at the filesystem level on the cloud mount, so if you don't explicitly set a store to read-only, anything with write access to that session can modify it, including content that arrived through an untrusted channel like a customer's own ticket text. A session can attach up to eight memory stores at once, which is enough room to keep reference material, per-customer facts, and anything else with a different owner or lifecycle in separate containers rather than one undifferentiated blob.

The failure mode this avoids: if Acme's policy store and its per-customer store were the same read-write store, a customer's crafted ticket description could, in principle, get written into the same store the bot treats as authoritative policy on the next session. Keeping policy read-only means that even if the bot's write logic misbehaves, the policy text itself can't be the thing that changes.

Sources: Memory for Claude Managed Agents: agents that learn across sessions, skills/skills/claude-api/shared/managed-agents-memory.md at main · anthropics/skills.

Where this goes wrong if you don't decide up front

Three failure paths show up repeatedly once memory is switched on. The first is clutter: if you don't tell the model what counts as worth saving, it saves too much. Anthropic's own prompting guidance for the memory tool anticipates this directly, recommending an instruction to keep memory content up-to-date, coherent, and organized, and to rename or delete files that are no longer relevant rather than creating new ones by default. If you skip that instruction, expect the memory directory to accumulate near-duplicate notes that the model then has to sift through on every run.

The second is staleness: a fact written three sessions ago may no longer be true, and nothing forces a review unless you build one. The memory tool gives you no built-in expiry; whatever gets written stays until something explicitly deletes it.

The third is scope: a store that defaults to read-write access stays writable on the filesystem level unless you set it to read-only, and that enforcement detail is specific to the cloud mount; self-hosted sandboxes enforce it through the worker's write and edit tools instead. If you're running a self-hosted sandbox and assumed the filesystem would stop an unwanted write the way the cloud mount does, you've assumed wrong. Check which enforcement path applies to your deployment before treating read-only as a guarantee.

Sources: Memory tool - Claude Docs, skills/skills/claude-api/shared/managed-agents-memory.md at main · anthropics/skills.

The decision to make before you turn memory on

Ask one question before persisting anything: is this fact expensive to rebuild, or cheap? If a fact can be regenerated from a source document or an API call in under a second, don't persist it; persisting it just adds a second copy that can go stale. Persist the things that took real work to produce, like a resolved customer preference, a decision the bot made and should stick to, or a past mistake it shouldn't repeat.

Once you know what to persist, split it by who's allowed to write it. Reference material the bot should consult but never change belongs in a read-only store. Facts the bot is supposed to update as it learns belong in a separate read-write store, and the two should not share a container. If you're using the raw memory tool instead of a managed store, write your own retention rule into the prompt, because nothing else will enforce it.

Finally, check your recovery path before you need it. Managed Agents memory stores give you built-in version history with the retention limit described above; the memory tool does not, so if you build on it, build your own versioning or backup before a bad write becomes the only copy of a fact your bot relies on.

Sources: Memory tool - Claude Docs, Using agent memory - Claude Platform Docs.