---
title: Claude Managed Agents Memory Store Tutorial (2026)
description: 'Build persistent memory for Claude Managed Agents: create a store, attach it to a session, and handle concurrent writes safely with tested TypeScript.'
url: https://nerdleveltech.com/claude-managed-agents-memory-store-tutorial
language: en
date: '2026-09-15'
category: ai-ml
tags:
  - claude managed agents
  - ai agent memory
  - memory store
  - agent state
  - typescript
  - anthropic api
markdown_url: https://nerdleveltech.com/claude-managed-agents-memory-store-tutorial.md
attribution: 'Source: NerdLevelTech — https://nerdleveltech.com/claude-managed-agents-memory-store-tutorial'
terms: https://nerdleveltech.com/llms.txt
---

# 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[^1].

## 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[^11], and use their own beta header, separate from the rest of Managed Agents[^1][^2]. 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[^3]. 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[^4]. 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[^5].

## 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](https://nerdleveltech.com/claude-memory-tool-context-editing-typescript-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[^1].

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](https://nerdleveltech.com/claude-managed-agents-dreaming-outcomes-multiagent-orchestration)[^6].

## Step 1: Install the SDK and confirm the version

```bash
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[^3].

## 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:

```typescript
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[^7]. It's never shown to the agent, unlike `description`.

Seed the store before any agent ever touches it:

```typescript
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[^1].

## 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[^1]:

```typescript
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[^8].

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[^1]. 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[^1].

**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[^1].

## 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.

```typescript
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[^9].

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[^7].

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:

```typescript
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[^10]. 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[^10].

Versions are retained for 30 days, except that the most recent versions of a memory that's still alive are kept regardless of age[^1]. 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[^1].

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[^1].

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"[^10].

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[^1].

**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[^8].

**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[^1][^6].

## 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[^4]:

| Line item | Rate |
|---|---|
| Input / output tokens | Standard per-model API rates |
| Session runtime | $0.08 per session-hour, metered to the millisecond, only while `status = running` |
| Web search inside a session | $10 per 1,000 searches |

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[^4].

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[^4].)

## 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[^11]. Wisedocs' Head of Machine Learning, Denys Linkov, says cross-session memory in their document-verification pipeline "sped verification up 30%"[^11]. Netflix and Ando are also named as users, without a specific number attached to either[^11].

## 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[^2].

**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[^1].

**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[^1].

**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[^1].

## FAQ

**What is a Claude Managed Agents memory store?**
A workspace-scoped collection of small text files that mounts as a directory inside a session's sandbox, so an agent can read and write persistent state that survives after the session ends[^1].

**When did memory stores launch?**
Public beta on April 23, 2026. Memory itself isn't gated — it's enabled by default. Only MCP tunnels and Dreaming currently require a separate access request[^1][^11].

**Do memory stores use the same beta header as the rest of Managed Agents?**
No. Managed Agents overall uses `managed-agents-2026-04-01`; memory store endpoints use `agent-memory-2026-07-22` instead, and combining both on one request returns a `400` error[^2].

**How much does a memory store cost to run?**
There's no separate memory-store line item. You pay standard token rates for whatever an agent reads or writes while a session is running, plus $0.08 per session-hour of runtime[^4].

**Can I attach a memory store to a session that's already running?**
No. Memory stores attach only at session creation[^1].

**What happens when a store fills up?**
At 10,000 memories, new writes fail — both direct API calls and the agent's own file writes to unmapped paths. Existing memories stay readable and editable[^1].

## 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)](https://nerdleveltech.com/claude-memory-tool-context-editing-typescript-tutorial)
- [Claude Managed Agents: Dreaming, Outcomes, Orchestration](https://nerdleveltech.com/claude-managed-agents-dreaming-outcomes-multiagent-orchestration)
- [OpenAI Agents API: The Managed Codex Harness 2026](https://nerdleveltech.com/openai-agents-api-managed-codex-harness)
- [Claude Managed Agents: ant apply Tutorial (2026)](https://nerdleveltech.com/claude-managed-agents-ant-apply-tutorial) — declare this same memory store as a file and sync it with `ant apply`

[^1]: Anthropic, "Using agent memory" — https://platform.claude.com/docs/en/managed-agents/memory (memory store definition, mount path derivation, size/count limits, access modes, prompt-injection guidance, version retention, redact rules, best practices; fetched 2026-09-15)
[^2]: Anthropic, "Claude Managed Agents overview" — https://platform.claude.com/docs/en/managed-agents/overview (Managed Agents still in beta as of this fetch; `managed-agents-2026-04-01` beta header; only MCP tunnels and Dreaming in research preview requiring access request; fetched 2026-09-15)
[^3]: npm registry — https://registry.npmjs.org/@anthropic-ai/sdk (version 0.125.0 confirmed via `npm view @anthropic-ai/sdk version` against the live registry, 2026-09-15); PyPI — `pip index versions anthropic` confirmed 1.5.0 as latest, same date
[^4]: Anthropic, "Pricing" — https://platform.claude.com/docs/en/about-claude/pricing (Claude Managed Agents pricing section: token rates, $0.08/session-hour runtime, $10/1,000 web searches, worked example; fetched 2026-09-15). A third-party guide (Tygart Media) states $0.25/session-hour; this post uses Anthropic's own page.
[^5]: Anthropic, "Get started with Claude Managed Agents" — https://platform.claude.com/docs/en/managed-agents/quickstart (CLI install command, SDK install, session-creation example; fetched 2026-09-15)
[^6]: NerdLevelTech, "Claude Managed Agents: Dreaming, Outcomes, Orchestration" — /claude-managed-agents-dreaming-outcomes-multiagent-orchestration (2026-05-10)
[^7]: `anthropic` Python SDK 1.5.0 (installed from PyPI and inspected directly, 2026-09-15) — `anthropic/types/beta/memory_store_create_params.py` (`metadata` field), `anthropic/types/beta/memory_stores/beta_managed_agents_precondition_param.py` (200-instead-of-409 behavior on matching content)
[^8]: `@anthropic-ai/sdk` 0.125.0 (installed from npm and inspected directly, 2026-09-15) — `resources/beta/sessions/sessions.d.ts` (`SessionCreateParams`, `BetaManagedAgentsMemoryStoreResourceParam`, `budget` field); example `agent`/`environment_id` IDs copied from this file's own JSDoc examples
[^9]: `@anthropic-ai/sdk` 0.125.0 — `core/error.ts` / `error.d.ts` (`ConflictError extends APIError<409, Headers>`)
[^10]: `@anthropic-ai/sdk` 0.125.0 — `resources/beta/memory-stores/memory-versions.d.ts` (`MemoryVersionListParams` filters, `BetaManagedAgentsMemoryVersionOperation` enum, actor attribution types and source comment)
[^11]: Anthropic, "Built-in memory for Claude Managed Agents" — https://claude.com/blog/claude-managed-agents-memory (April 23, 2026 public-beta announcement; Rakuten, Wisedocs, Netflix, Ando customer quotes; fetched 2026-09-15)