Anthropic agent-memory-2026-07-22: Three Breaking Changes to Fix Before July 22 — Builder's Migration Guide

Anthropic has introduced a new beta header — agent-memory-2026-07-22 — that changes how memory listing works for Managed Agents memory stores. The new behavior is available now as an opt-in. On July 22, 2026, the older managed-agents-2026-04-01 header automatically adopts the same behavior for memory store list calls.

If you call GET /v1/memory_stores/{memory_store_id}/memories in your agent and do not update your code before July 22, three things will silently change — and one of them will throw a 400 if your parameters are wrong.

This is a research-based guide. We reviewed Anthropic’s documentation and release notes. We did not test the API endpoints ourselves.

Context: What Is the Managed Agents Memory Store?

Anthropic added persistent memory to Managed Agents in a public beta in mid-2026. Agents can write facts, preferences, or session state to a memory store, then retrieve them in future sessions. Each memory has a path (like a filesystem) — for example, user/profile, project/123/context.

The listing API — GET /v1/memory_stores/{id}/memories — lets you retrieve stored memories by path prefix, depth, and ordering. This is the endpoint that changes on July 22.

What Changes on July 22

Change 1: order_by and order Are Ignored

Before (current behavior with managed-agents-2026-04-01): You can sort results by passing order_by (e.g., created_at, updated_at) and order (asc or desc). Results come back in the requested order.

After July 22: order_by and order are silently ignored. Results return in a stable, server-defined order. Your code still runs — no error — but any sorting logic you wrote around these parameters is wrong.

Impact: If your agent processes memories in a specific sequence (e.g., most recently updated first), you can no longer rely on the API for that ordering. Sort client-side instead.

Change 2: depth Restricted to 0, 1, or Omitted

Before: depth can be any non-negative integer, letting you retrieve memories at arbitrary nesting levels below the path_prefix.

After July 22: depth accepts only 0, 1, or being omitted entirely. Sending any other value (e.g., depth=2 or depth=5) returns a 400 error.

Impact: This is the silent bomb. If you’re passing depth=2 or higher to retrieve deeply nested memories, your code will throw after July 22. Review every memories.list() call.

Change 3: path_prefix Must End With / and Matches Whole Segments

Before: path_prefix="user" matches any path that starts with the substring user — including user, username, users, user_data.

After July 22: path_prefix must end with a slash (/). It matches whole path segments, not substrings. path_prefix="user/" matches paths starting with user/ as a directory-style prefix, but not username/ or user_data/.

Additionally, if you pass a path_prefix without a trailing slash, you now get a 400 error.

Impact: Two problems. First, any call using a prefix without a trailing slash will fail with 400. Second, even calls you fix (by adding /) may silently return fewer results than before if you were relying on substring matching.

The Header Change

The new behavior is gated behind the agent-memory-2026-07-22 beta header. Sending this header opts you in now — you don’t need to wait until July 22.

Critical rule: Do not combine agent-memory-2026-07-22 with managed-agents-2026-04-01 on a single memory store request. Sending both returns a 400 error.

# Wrong — 400 error
headers = {
    "anthropic-beta": "managed-agents-2026-04-01, agent-memory-2026-07-22"
}

# Correct — use the new header alone on memory store calls
headers = {
    "anthropic-beta": "agent-memory-2026-07-22"
}

If your agent already sends managed-agents-2026-04-01 globally (e.g., in a shared HTTP client config), you need to strip it and replace it with agent-memory-2026-07-22 specifically on memory store endpoint calls. Other Managed Agents endpoints continue to use managed-agents-2026-04-01.

Page Cursor Invalidation

Page cursors issued without the agent-memory-2026-07-22 header are not valid with it. If you use pagination over memory results, you must restart from the first page when you adopt the new header. Do not resume from an old cursor — it will not work across the header boundary.

Migration Checklist

Find every call to the memory list endpoint:

# Search your codebase for memory list calls
grep -r "memory_stores" . --include="*.py"
grep -r "memories.list" . --include="*.py"
grep -r "v1/memory_stores" . --include="*.ts"

For each call, fix these issues before July 22:

1. Remove order_by and order parameters. Move any sort logic to client-side code.

2. Audit depth. If you pass depth=2 or higher, restructure your path hierarchy so a single depth-1 query covers what you need — or make multiple depth-1 calls across sub-prefixes.

3. Fix path_prefix. Add trailing slash to all prefixes. Verify that the narrower whole-segment matching still returns the memories you expect. Test with your actual stored paths.

4. Switch the header. Replace managed-agents-2026-04-01 with agent-memory-2026-07-22 on memory store list calls.

5. Reset pagination. If you cache page cursors, invalidate them and restart from the first page.

Before-and-after example:

# BEFORE — breaks or returns wrong results after July 22
memories = client.beta.memory_stores.memories.list(
    store.id,
    path_prefix="user",        # no trailing slash → 400 error after July 22
    depth=3,                   # invalid → 400 error after July 22
    order_by="updated_at",     # ignored after July 22
    order="desc",              # ignored after July 22
)

# AFTER — correct now, remains correct after July 22
memories = client.beta.memory_stores.memories.list(
    store.id,
    path_prefix="user/",       # trailing slash required
    depth=1,                   # only 0 or 1 valid
    # no order_by/order — sort client-side if needed
)
# Sort client-side if order matters
memories_sorted = sorted(memories, key=lambda m: m.updated_at, reverse=True)

Why These Changes

Anthropic’s documentation frames the changes as improvements to predictability and scalability for the memory store backend:

• Stable server ordering removes dependence on sort-at-read semantics that are expensive at scale. Clients that need ordering can sort cheaply in memory.
• Depth restriction to 0 or 1 prevents expensive recursive tree traversals. Agent developers who find they need deeper nesting should flatten their path hierarchy or make targeted per-prefix queries.
• Whole-segment path matching makes prefix semantics unambiguous — user/ cannot accidentally match username/. This reduces a class of subtle bugs where agents read more (or less) than intended.

Timeline

You have 9 days. The safe path is to adopt agent-memory-2026-07-22 now, verify your agent in staging, and deploy before July 22.

Bottom Line

Three changes, one deadline. The order_by/order change is silent — code keeps running but ordering breaks. The depth and path_prefix changes will throw 400 errors if you have invalid values. Check your codebase now, fix before July 22, and opt into the new header in staging to verify the behavior change doesn’t break any memory retrieval logic your agent relies on.