Claude Managed Agents Memory Store Tutorial (2026)

A Claude Managed Agents session starts with a clean container and forgets everything once it ends. A memory store fixes that: a workspace-scoped set of small text files that mounts into the session's sandbox, so an agent can read what it learned last time and write down what it just learned now¹.

TL;DR

You'll use @anthropic-ai/sdk to create a memory store, seed it, and attach it to a session with read_write access. Then you'll update a memory safely under concurrent writes using the content_sha256 precondition, including a retry pattern for the 409 conflict it throws. You'll also read the audit trail every write leaves behind.

Memory stores have been in public beta since April 23, 2026², and use their own beta header, separate from the rest of Managed Agents¹³. Runtime: Node.js with @anthropic-ai/sdk@0.125.0. Build time: about 20 minutes.

What you'll learn

• How a memory store attaches to a session and shows up inside the sandbox filesystem
• How to create, seed, and attach a store with the real, verified TypeScript SDK method names
• How to avoid clobbering a concurrent write with the content_sha256 optimistic-concurrency precondition, including a documented edge case that only shows up in the SDK's own source, not the prose docs
• How to read a memory's full version history for an audit trail, and why there's no dedicated "restore" endpoint
• Where memory stores stop being free: the exact pricing dimensions and a worked example
• What this tutorial's code is actually checked against, and what running it live would additionally require

Prerequisites

• Node.js 20 or later — @anthropic-ai/sdk's own README specifies "Node.js 20 LTS or later" as of this SDK version.
• @anthropic-ai/sdk@0.125.0 — confirmed as the registry-published latest via npm view @anthropic-ai/sdk version on 2026-09-15⁴. This package ships frequently; pin the exact version in production.
• An ANTHROPIC_API_KEY if you want to run any of this for real. Memory store CRUD calls outside a session carry no session-runtime charge, but any turn an agent takes inside an attached session bills standard token rates plus $0.08 per session-hour⁵. See Verification below for exactly what this tutorial's code was, and wasn't, checked against.
• Optional: the ant CLI, installable with brew install anthropics/tap/ant on macOS, for the ant beta:memory-stores commands shown in Anthropic's own docs⁶.

Which "Claude memory" is this?

Anthropic ships at least four things people call "Claude memory," and this is the one most tutorials skip:

1. The Messages API memory tool (memory_20250818) — a client-side tool where Claude requests file operations against a /memories directory you host and code yourself. Covered in our memory tool and Context Editing tutorial.
2. Claude Agent SDK's SessionStore — mirrors a session's raw transcript to external storage so the same conversation can resume later. A different package (@anthropic-ai/claude-agent-sdk).
3. Claude Code's CLAUDE.md — project-level instructions for the Claude Code CLI, not an API feature.
4. Managed Agents' hosted memory stores — this post. Anthropic hosts the storage layer; you don't write a /memories handler at all. It mounts as an ordinary directory and the agent uses the same file tools it already has¹.

Memory stores are also the foundation for Dreaming, Anthropic's background process that reviews a store's contents and consolidates them into a fresh output store — still in research preview and covered in our Managed Agents Dreaming tutorial⁷.

Step 1: Install the SDK and confirm the version

mkdir memory-store-demo && cd memory-store-demo
npm init -y
npm install @anthropic-ai/sdk
npm view @anthropic-ai/sdk version

This tutorial's code was checked against 0.125.0. All of the memory-store methods below live under client.beta.memoryStores, client.beta.memoryStores.memories, and client.beta.memoryStores.memoryVersions — confirmed directly from the package's own shipped type definitions, not just the docs prose⁴.

Step 2: Create and seed a memory store

A store needs a name; description is what gets shown to the agent, so word it for Claude, not for yourself:

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });

const store = await client.beta.memoryStores.create({
  name: "repo-conventions",
  description: "Coding conventions and past review corrections for this repo.",
  metadata: { team: "platform" },
});

console.log(store.id); // memstore_...

That metadata field — up to 16 key-value pairs for your own bookkeeping — isn't mentioned anywhere in the memory docs prose. It's only visible if you install the SDK and read memory_store_create_params directly, which is what this tutorial did⁸. It's never shown to the agent, unlike description.

Seed the store before any agent ever touches it:

const seed = await client.beta.memoryStores.memories.create(store.id, {
  path: "/conventions.md",
  content: "Use tabs, not spaces. Prefer named exports.",
});

console.log(seed.id, seed.content_sha256);

Each memory is capped at 100 kB (about 25,000 tokens), and a store holds at most 10,000 memories. Anthropic's own guidance is to write many small, focused files rather than a few large ones¹.

Step 3: Attach the store to a session

Memory stores only attach at session creation — you can't add or remove one from a session that's already running¹:

const session = await client.beta.sessions.create({
  agent: "agent_011CZkYpogX7uDKUyvBTophP",
  environment_id: "env_011CZkZ9X2dpNyB7HsEFoRfW",
  resources: [
    {
      type: "memory_store",
      memory_store_id: store.id,
      access: "read_write",
      instructions: "Check this before writing any code in this repo.",
    },
  ],
});

agent and environment_id come from an agent and environment you've already created; both fields, and the resources array shape, are copied from the SDK's own example blocks and verified against the shipped types, not guessed⁹.

Inside the sandbox, the store mounts at /mnt/memory/<slug>/, where <slug> is the store's display name lowercased with non-alphanumeric runs collapsed to a hyphen. A store named "Demo Memory" mounts at /mnt/memory/demo-memory/.

Don't hardcode that path yourself. The session's memory-store resource returns the real mount_path field, and that's the one to read¹. A short note describing the mount (name, path, access mode, description, instructions) is automatically added to the system prompt, so the agent doesn't need to be told the store exists.

A session can attach up to 8 memory stores at once — one per user, one shared read-only reference store, whatever split matches how your data is actually owned¹.

Read-only isn't just about mistakes. If a session processes untrusted input — user prompts, fetched web pages, third-party tool output — a successful prompt injection can write malicious content straight into a read_write store. A later session then reads that content back as trusted memory.

Anthropic's own guidance is blunt about this: use read_only for reference material and anything the agent doesn't need to modify. Reserve read_write for stores the agent is actually supposed to update¹.

Step 4: Update a memory without clobbering a concurrent write

Two sessions can share a store. If both read a memory, edit it, and write back without coordination, the second write silently destroys the first. The fix is optimistic concurrency: pass the content_sha256 you read, and the update only applies if nothing else changed it first.

async function updateWithRetry(
  memoryId: string,
  storeId: string,
  newContent: string,
): Promise<void> {
  const current = await client.beta.memoryStores.memories.retrieve(memoryId, {
    memory_store_id: storeId,
  });

  try {
    await client.beta.memoryStores.memories.update(memoryId, {
      memory_store_id: storeId,
      content: newContent,
      precondition: {
        type: "content_sha256",
        content_sha256: current.content_sha256,
      },
    });
  } catch (err) {
    if (err instanceof Anthropic.ConflictError) {
      // memory_precondition_failed_error (HTTP 409) — someone else wrote first.
      console.log("Precondition failed, retrying against fresh content...");
      return updateWithRetry(memoryId, storeId, newContent);
    }
    throw err;
  }
}

await updateWithRetry(
  seed.id,
  store.id,
  "Use tabs, not spaces. Prefer named exports. Avoid default exports.",
);

Anthropic.ConflictError is the SDK's real exported class for any HTTP 409, confirmed directly in its error-handling source (if (status === 409) return new ConflictError(...)), which is cleaner than checking err.status === 409 by hand¹⁰.

There's an edge case worth knowing that the prose docs don't mention at all. If the precondition fails, but the memory's stored content and path already exactly match what you were about to write, the API returns 200 instead of 409. That behavior is documented only in the SDK's own parameter docstring for precondition, not on the memory docs page⁸.

Practically, it means a retry loop that happens to converge on the same content Claude already wrote won't loop forever on a real conflict — it succeeds instead.

Step 5: Read the audit trail

Every write — create, update, or delete — appends an immutable memory version. There's no separate "audit log" to wire up; it's built into the store:

for await (const version of client.beta.memoryStores.memoryVersions.list(store.id, {
  memory_id: seed.id,
})) {
  console.log(version.id, version.operation, version.created_at);
}

version.operation is one of exactly three values: created, modified, or deleted — confirmed from the SDK's type definitions, since the prose docs don't enumerate them¹¹. The list endpoint also supports filtering by api_key_id, by operation, and by a created_at range, none of which are documented outside the SDK's own source¹¹.

Versions are retained for 30 days, except that the most recent versions of a memory that's still alive are kept regardless of age¹. There's no dedicated restore endpoint.

To roll back, retrieve the version you want and write its content back with memories.update — or memories.create, if the memory itself was deleted and the version you want is still retained¹.

If you need to scrub something out of history entirely — a leaked secret, a deletion request — memoryVersions.redact() does that. It can't touch the current head version of a live memory still in use, though; write a new version (or delete the memory) first, then redact the old one¹.

One more attribution detail is buried in the SDK source rather than the docs. A version records who wrote it as one of four actor kinds: an API key, a service account, a session, or a user. A source comment is explicit that "the API key that created a session is not recorded on agent writes; attribution answers who made the write, not who is ultimately responsible"¹¹.

If you need to trace a bad memory back to a specific session for accountability, that's a separate lookup — not something the version's actor field gives you directly.

Production patterns worth copying

Split stores by owner, not by convenience. One store per end user or per project, plus a separate read_only store for shared reference material, keeps each store's 10,000-memory ceiling from being shared across unrelated data, and keeps write access scoped to sessions that should actually be writing¹.

Cap runaway spend at the session level. sessions.create() also takes an optional budget field — "a hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches max_list_cost." It isn't specific to memory, but it's a reasonable default for any session that can run for a while against a shared store⁹.

Plan for the 10,000-memory ceiling before you hit it. Past that limit, both direct memories.create calls and the agent's own file writes to new paths start failing; existing memories stay readable and editable. Anthropic's suggested path is to prune stale memories, or run a Dreaming session, which consolidates a store's contents into a separate new output store rather than modifying the original — you then switch sessions over and archive or delete the old one¹⁷.

What it actually costs

Memory store CRUD calls made directly against the API — create a store, write a memory, list versions — don't carry their own line-item charge in Anthropic's pricing page; the only Managed-Agents-specific charges documented are tokens (at standard per-model rates) and session runtime⁵:

Anthropic's own worked example: a one-hour Claude Opus 5 coding session using 50,000 input and 15,000 output tokens comes to $0.705 total — $0.25 in input tokens, $0.375 in output tokens, and $0.08 in session runtime⁵.

Attaching a memory store to that same session doesn't add a separate fee on top. It's the agent's reads and writes inside the sandbox that consume tokens, same as any other tool call. (A third-party guide circulates a $0.25-per-session-hour figure for Managed Agents; Anthropic's own pricing page says $0.08, and that's the primary source this post uses⁵.)

What teams are shipping with it

Anthropic's launch post quotes several early adopters. These are the companies' own reported, attributed figures — not independently verified benchmarks, and not typical results to expect out of the box:

Rakuten's Yusuke Kaji, General Manager, AI for Business, is quoted saying memory delivered "97% fewer first-pass errors at 27% lower cost and 34% lower latency" on their task-based long-running agents². Wisedocs' Head of Machine Learning, Denys Linkov, says cross-session memory in their document-verification pipeline "sped verification up 30%"². Netflix and Ando are also named as users, without a specific number attached to either².

Verification

What this is, and isn't, verified against: none of the code above was run against a live Managed Agents session — that requires a paid ANTHROPIC_API_KEY and a real agent and environment already configured, which is outside the scope of writing this tutorial. Nothing here should be read as "captured console output."

Instead, every method name, parameter, and error class above was verified against the real, currently-published SDKs, not assumed from the docs prose. @anthropic-ai/sdk@0.125.0 was installed fresh from the npm registry, and its shipped .d.ts and .js source read directly: memoryStores.create/retrieve/update/list/delete/archive, .memories.create/retrieve/update/list/delete, .memoryVersions.list/retrieve/redact, and Anthropic.ConflictError.

The Python SDK (anthropic@1.5.0, also the current PyPI release) was installed separately, and its memory_stores resource and type files cross-checked against the TypeScript ones. Every TypeScript sample above then type-checked with npx tsc --noEmit (TypeScript 7.0.2) against that real installed package — zero errors — after first confirming the checker itself catches a real mistake, by running it against a deliberately broken throwaway file first.

The CLI commands (ant beta:memory-stores create, etc.) and the quickstart's session-creation example are Anthropic's own verbatim documentation examples, reproduced here rather than run independently.

If you have a live ANTHROPIC_API_KEY, every snippet above is copy-pasteable as-is: swap in a real agent ID and environment_id from your own account and it will run.

Troubleshooting

A memory-store request returns 400. You've likely sent both managed-agents-2026-04-01 and agent-memory-2026-07-22 as beta headers. Memory store endpoints want agent-memory-2026-07-22 only; the SDK sets this automatically if you're not setting beta headers by hand³.

Updating a memory returns 409. That's memory_precondition_failed_error — another write landed between your read and your update. Re-read the memory and retry, as in Step 4¹.

The agent's writes to /mnt/memory/... silently fail. Check the store's access mode. A read_only mount rejects writes at the filesystem level; that's enforcement, not a bug¹.

New memories stop being created. The store has likely hit its 10,000-memory cap. Existing memories remain readable and writable; only new paths fail. Prune, or consolidate with a Dreaming session¹.

The bottom line

A memory store is a small, well-scoped piece of infrastructure: text files, a mount path, an access mode, and an audit trail, wired into tools the agent already knows how to use.

The part that's easy to get wrong isn't the happy path. It's what happens when two sessions write to the same store at once — exactly what the content_sha256 precondition exists to catch. Read the version history before you build your own logging on top of it; most of what a "did the agent do this?" question needs is already there.

Related reads

• Claude Memory Tool + Context Editing: Agent Tutorial (2026)
• Claude Managed Agents: Dreaming, Outcomes, Orchestration
• OpenAI Agents API: The Managed Codex Harness 2026