Claude APIupdate

Persistent Memory for Claude Managed Agents

In brief

By default, a Managed Agents session starts fresh and forgets everything when it ends. Memory stores change that — they're workspace-scoped document collections the agent reads and writes across sessions. The feature entered public beta on April 23, 2026.

8 min read·AI Agent

Contents

♡Sign in to save

Claude Managed Agents sessions start with a blank context by default. When a session ends, anything the agent learned is gone. Memory stores let you carry information across sessions: user preferences, project conventions, prior mistakes, domain knowledge.

Memory entered public beta on April 23, 2026, under the existing managed-agents-2026-04-01 beta header — no additional header required.

How memory stores work

A memory store is a workspace-scoped collection of text documents. When you attach a store to a session, it mounts as a directory inside the session's container at /mnt/memory/. The agent reads and writes it using the same file tools it uses for the rest of the filesystem. A short description of each mount is automatically added to the system prompt so the agent knows where to look.

Every write creates an immutable memory version — an audit trail and point-in-time recovery for everything the agent changes.

Individual memory files are capped at 100KB (~25K tokens). Store many small focused files rather than a few large ones.

Create a memory store

Give the store a name and a description. The description tells the agent what the store contains.

const store = await client.beta.memoryStores.create({
  name: "User Preferences",
  description: "Per-user preferences and project context."
});
console.log(store.id); // memstore_01Hx...

The store ID (memstore_...) is what you pass when attaching to a session.

Seed a store with content

Pre-load reference material before any agent session runs:

await client.beta.memoryStores.memories.create(store.id, {
  path: "/formatting_standards.md",
  content: "All reports use GAAP formatting. Dates are ISO-8601..."
});

Useful for organizational standards, domain conventions, or any reference material that doesn't need to be generated by the agent — just read.

Attach to a session

Memory stores are attached in the session's resources[] array at creation time. You cannot add or remove a store from a running session.

const session = await client.beta.sessions.create({
  agent: agent.id,
  environment_id: environment.id,
  resources: [
    {
      type: "memory_store",
      memory_store_id: store.id,
      access: "read_write",
      instructions: "User preferences and project context. Check before starting any task."
    }
  ]
});

access defaults to read_write. Set it to read_only for reference stores the agent should consult but not change.

Up to 8 memory stores can be attached per session.

Access patterns

One store per user. If you're building a multi-user product, create a separate store per end user keyed to their user ID. Each session for that user attaches their store. The agent picks up prior context — their preferences, past decisions — without you building a retrieval layer.

One shared read-only store + per-user read-write store. Common pattern: one store for organizational standards (read-only, shared across all sessions) and one store per user for their personal context (read-write). Attach both to every session.

const session = await client.beta.sessions.create({
  agent: agent.id,
  environment_id: environment.id,
  resources: [
    {
      type: "memory_store",
      memory_store_id: orgStoreId,
      access: "read_only",
      instructions: "Organizational formatting and compliance standards."
    },
    {
      type: "memory_store",
      memory_store_id: userStoreId,
      access: "read_write",
      instructions: "This user's preferences and project context. Update when the user states a preference."
    }
  ]
});

Reading and editing memories via the API

You can inspect and correct memories directly — no session needed.

List memories in a store:

const page = await client.beta.memoryStores.memories.list(store.id, {
  path_prefix: "/",
  order_by: "path",
  depth: 2
});
for (const item of page.data) {
  console.log(item.type, item.path);
}

Read a specific memory:

const mem = await client.beta.memoryStores.memories.retrieve(memId, {
  memory_store_id: store.id
});
console.log(mem.content);

Update a memory with an optimistic concurrency check:

// Pass content_sha256 to prevent clobbering a concurrent write.
// On hash mismatch, re-read and retry.
await client.beta.memoryStores.memories.update(mem.id, {
  memory_store_id: store.id,
  content: "CORRECTED: Always use 2-space indentation.",
  precondition: { type: "content_sha256", content_sha256: mem.content_sha256 }
});

Security: prompt injection risk

Memory stores attach with read_write access by default. If the agent processes untrusted input — user-supplied prompts, fetched web content, third-party tool output — a successful prompt injection could write malicious content into the store. Future sessions then read that content as trusted memory.

Use read_only for:

Reference material and shared lookups
Any store the agent doesn't need to modify
Stores shared across many sessions

Audit what the agent has written with the memory versions API before relying on store contents in production.

Audit trail and version history

Every mutation creates a memory version (memver_...). Versions survive even after the memory is deleted.

// List version history for a memory
for await (const v of client.beta.memoryStores.memoryVersions.list(store.id, {
  memory_id: mem.id
})) {
  console.log(`${v.id}: ${v.operation}`);
}

To roll back: retrieve the version you want and write its content back with memories.update.

For compliance workflows — removing leaked secrets or PII — use the redact endpoint to scrub content from a historical version while preserving the audit record.

Version history is retained for 30 days.

Limits (public beta)

Limit	Value
Memory stores per organization	1,000
Memories per store	2,000
Total storage per store	100 MB
Size per memory	100 KB (~25K tokens)
Stores per session	8
Version history retention	30 days