Anthropic Agent Memory Header: Migrate Before July 22

Anthropic’s Managed Agents memory store API is getting a forced upgrade on July 22 — five days from now. A new beta header, agent-memory-2026-07-22, changes how memory listing works and rewires three parameter behaviors. When the deadline hits, the old managed-agents-2026-04-01 header automatically inherits those changes whether you’ve opted in or not. If you’re setting beta headers manually in curl, or if you haven’t updated to the latest Anthropic SDK versions, your code will break silently or with 400 errors by next Wednesday.

The Header Split

Anthropic announced this change on July 2, alongside SDK updates across all eight official languages. The core rule is straightforward: memory store endpoints (/v1/memory_stores/…) now use agent-memory-2026-07-22 as their beta header. Session endpoints — creating agents, attaching stores to sessions — still use managed-agents-2026-04-01. The two headers serve different endpoint groups and are no longer interchangeable on memory calls. Sending both on the same memory store request returns a 400 error immediately.

The reason for the split is endpoint versioning independence. Anthropic wants to iterate on memory store behavior without bumping the broader managed agents header. This is the first dedicated versioning of the memory store surface, and more changes will follow.

Four Changes That Will Break Your Code

The new header is not cosmetic. It changes four specific behaviors on GET /v1/memory_stores/{store_id}/memories. Two are silent failures — the worst kind.

1. path_prefix Now Matches Whole Segments, Not Substrings

This is the one most likely to cause invisible bugs. Previously, path_prefix=/notes would match /notes-archive/todo.md as a substring match. Under the new header, path_prefix must end with / and matches only complete path segments. path_prefix=/notes/ returns /notes/todo.md but not /notes-archive/todo.md. If your code constructs path_prefix values without the trailing slash, or relies on partial segment matching, your listing results will silently shrink.

2. order_by and order Are Silently Ignored

Results are now returned in a stable, server-defined order. The order_by and order query parameters still exist but do nothing — they’re ignored without error. If your code sorts memory listings by passing these parameters and then relies on that ordering for downstream logic, the ordering will change without any indication that your parameters were dropped.

3. depth Is Restricted to 0, 1, or Omitted

This one is loud, not silent. Under the new header, passing any depth value other than 0 or 1 returns a 400 error. Omitting depth lists the full subtree. If you’re passing depth=2 or higher anywhere, those calls start returning errors on July 22.

4. Page Cursors From the Old Header Don’t Transfer

Cursors issued by the API before the header change are not valid after you adopt agent-memory-2026-07-22. If you’re in the middle of paginating through a large store and you switch headers mid-run, restart from page one. This also applies on July 22 when the auto-adoption kicks in — any in-flight pagination at the moment of adoption needs to restart.

Who Needs to Act

The official Anthropic SDKs have already been updated: Python 0.116.0, TypeScript 0.110.0, Go 1.56.0, Java 2.48.0, Ruby 1.55.0, PHP 0.36.0, C# 12.35.0, and CLI 1.16.0. All of them now send agent-memory-2026-07-22 on memory store calls automatically. If you’re on these versions or newer and you do not override beta headers manually, you’re already running the new behavior and you’ll see no change on July 22.

You need to act if:

• You use raw HTTP calls (curl, HTTP libraries) and set anthropic-beta headers directly
• You use an official SDK but pass betas explicitly on memory store calls with the old header string
• You’re on SDK versions below the minimums above

Migration Steps

Before July 22:

1. Search your codebase for managed-agents-2026-04-01 anywhere it appears on a memory store call. Session endpoint calls keep that header — only memory store calls change.
2. Replace with agent-memory-2026-07-22 on those calls. Do not send both — that’s a 400.
3. Audit every path_prefix value you construct. Ensure it ends with / and that you’re not relying on substring matching across directory boundaries.
4. Audit depth parameter usage. Values above 1 need to be removed or replaced with 0 or 1.
5. Invalidate any stored page cursors. Restart pagination from the first page after updating.

One More Thing: Read-Only Access

The memory documentation’s security note is worth flagging here. Memory stores default to read_write. If an agent is processing untrusted input — user-supplied prompts, fetched web content, third-party tool output — a successful prompt injection could write malicious content into the store. Every future session that reads from that store then sees it as trusted memory. Use read_only access for any store that the agent doesn’t need to modify, particularly shared reference material or stores attached to sessions handling external input.

The Deadline Is July 22

The auto-adoption on July 22 is unconditional. Anthropic doesn’t provide an opt-out path beyond adopting the new header early. Developers running on official SDKs at current versions are already there. Developers running manual header configurations or outdated SDK versions have five days. Check your memory store calls, update the header, and fix the three parameter behaviors — the path_prefix one in particular is easy to miss until queries start returning unexpectedly empty results.

The full behavior spec is in Anthropic’s memory documentation.