Claude agent memory migration: prepare for the July 22 API behavior change

Quick answer

On July 22, 2026, Claude memory-store list requests that still use managed-agents-2026-04-01 adopt the behavior already available through agent-memory-2026-07-22. This is not only a header rename. The list contract changes in five ways:

Area	New behavior
Header	Memory-store endpoints use agent-memory-2026-07-22; sending it together with managed-agents-2026-04-01 returns 400
Ordering	Results use a stable server-defined order; order_by and order are ignored
Depth	Only 0, 1, or omission is accepted; other values return 400
Prefix	path_prefix must end with / and matches whole path segments
Pagination	Cursors created under the old behavior cannot be reused with the new header

If you call /v1/memory_stores through a current Anthropic SDK, upgrade to the documented minimum version and remove explicit beta overrides. If you use raw HTTP, replace the header on memory-store requests, normalize list parameters, discard saved cursors, and test the new contract before July 22.

Who this is for

This guide is for teams using Claude Managed Agents memory stores through the REST API, ant CLI, or Anthropic SDKs. It matters most when an application lists memories for an admin screen, synchronizes them into another store, walks hierarchical prefixes, or saves pagination cursors between jobs.

The change is specific to /v1/memory_stores and its sub-resources. Agent, session, and environment endpoints still use managed-agents-2026-04-01. It is also separate from Claude Code project instruction files or a local MEMORY.md.

If your wider agent runtime needs a configuration inventory, adapt the layered approach in the AGENTS.md, CLAUDE.md, and Copilot instructions guide. For provider-level cutovers, reuse the canary and rollback discipline from the GitHub Models migration checklist.

Why July 22 can break existing clients

Anthropic introduced agent-memory-2026-07-22 on July 2 so developers could test the new list behavior early. On July 22, requests that still send the older Managed Agents header to memory-store endpoints receive the same behavior.

Four common assumptions can then fail:

• A tree browser sends depth=2 and starts receiving 400 responses.
• A sync job depends on order_by=path&order=asc, even though those fields are now ignored.
• A prefix such as /projects/acme is treated like a raw substring instead of the directory prefix /projects/acme/.
• A worker resumes from a cursor issued under the previous behavior and gets an invalid or inconsistent pagination flow.

The current SDK floors documented by Anthropic are 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. These versions send the memory-specific header automatically. If your code passes betas explicitly, replace the old value; do not add the new value beside it.

Migrate in six steps

1. Inventory headers, SDKs, and list assumptions

Search application code, API gateways, test fixtures, scheduled sync jobs, and saved request templates:

rg -n 'managed-agents-2026-04-01|agent-memory-2026-07-22|memory_stores|path_prefix|order_by|next_page' . \
  --glob '!node_modules/**' --glob '!dist/**'

Record whether each caller uses a current SDK, raw HTTP, or a wrapper that injects headers. Also identify persisted page cursors and any UI that assumes server-side sorting.

2. Separate memory headers from agent headers

For raw HTTP, send the new header only on memory-store endpoints:

curl --get \
  "https://api.anthropic.com/v1/memory_stores/$MEMORY_STORE_ID/memories" \
  --data-urlencode 'path_prefix=/projects/acme/' \
  --data-urlencode 'depth=1' \
  --data-urlencode 'limit=100' \
  -H 'anthropic-version: 2023-06-01' \
  -H 'anthropic-beta: agent-memory-2026-07-22' \
  -H "x-api-key: $ANTHROPIC_API_KEY"

Keep managed-agents-2026-04-01 on agent and session calls. A blanket header replacement across every Managed Agents endpoint is incorrect.

3. Normalize list queries

Treat memory paths like directories. Canonicalize a non-empty prefix so it starts and ends with /, and reject .., duplicate separators, and ambiguous empty segments in your own input layer. Use depth=0 for the exact level, depth=1 for one directory layer, or omit it for an unrestricted listing.

Remove order_by and order from correctness-sensitive code. If a UI needs alphabetical paths or newest-first timestamps, sort the returned page client-side and document whether sorting applies per page or after collecting every page.

4. Reset pagination state

Invalidate saved memory-list cursors during deployment. Start from the first page under the new header and follow the returned next_page chain until it is empty. For sync jobs, deduplicate by stable memory id, not by page position or path order.

Do not run old-header and new-header workers against the same cursor checkpoint. Use a versioned checkpoint key such as memory-list:v2: so rollback cannot mix pagination contracts.

5. Run a compatibility matrix

Test	Evidence required
Header routing	Memory call has only the new header; session call keeps the Managed Agents header
Prefix	/projects/acme/ returns only whole path segments, not similar names
Depth	0, 1, and omission succeed; 2 produces the expected handled 400
Ordering	Business logic remains correct when server order differs from the old requested order
Pagination	A full walk has no missing or duplicate memory IDs
Cursor reset	An old cursor is rejected or discarded rather than silently reused
Empty store	The job completes without inventing a cursor or retry loop

Use a disposable store with similarly named paths such as /projects/acme/, /projects/acme-labs/, and /projects/acme/archive/. That fixture exposes substring and depth mistakes quickly.

6. Canary before the default changes

Enable the new contract in staging, then canary one store or one sync worker in production. Track 400 rate, request IDs, pages per store, unique memory IDs, duplicate IDs, missing expected paths, and sync duration. Keep a rollback for application logic, but do not make the legacy memory header the long-term fallback.

Decision tree

Do you call /v1/memory_stores or a sub-resource?
├─ No -> This migration does not apply.
└─ Yes
   ├─ Current SDK/CLI with no explicit beta override?
   │  └─ Verify the version floor, reset cursors, and run the matrix.
   └─ Raw HTTP, old SDK, proxy, or explicit betas?
      └─ Replace the memory header, normalize prefix/depth, remove order assumptions,
         reset cursors, and canary before July 22.

Common mistakes

• Adding agent-memory-2026-07-22 while leaving the old header on the same memory request.
• Replacing the header on sessions and agents even though those endpoints keep the Managed Agents header.
• Upgrading the SDK but retaining an explicit betas=["managed-agents-2026-04-01"] override.
• Fixing depth but leaving a prefix without a trailing slash.
• Assuming “stable server-defined order” means alphabetical or chronological order.
• Reusing persisted cursors after changing the header or query contract.
• Testing one page only and missing duplicates or omissions across pagination.

FAQ

Does every Claude Managed Agents request switch headers?

No. Memory-store endpoints use agent-memory-2026-07-22. Agent, session, and environment endpoints continue to use managed-agents-2026-04-01.

Will depth=2 keep working after July 22?

No. Anthropic says the new behavior accepts only 0, 1, or omission. Other values return 400.

Can I keep order_by=path?

The request may still contain it, but the new contract ignores order_by and order. Do not rely on either field for correctness; sort in your application if presentation requires it.

Do current SDKs need a manual beta header?

No. Anthropic says the listed SDK and CLI versions send the correct header automatically. Manual overrides are mainly a migration risk when they preserve the old value.

Sources

• Claude Platform release notes: https://platform.claude.com/docs/en/release-notes/overview
• Claude beta headers: https://platform.claude.com/docs/en/api/beta-headers
• Using agent memory: https://platform.claude.com/docs/en/managed-agents/memory
• List memories API reference: https://platform.claude.com/docs/en/api/cli/beta/memory_stores/memories/list