Deprecate MemoryControlPlaneClient in favor of MemoryClient

[jariy17]

Summary

Propose deprecating MemoryControlPlaneClient in v1.3.0 and removing it in v1.4.0. The MemoryClient class provides a superset of functionality, making MemoryControlPlaneClient redundant.

Reason for Deprecation

1. Functional Overlap

MemoryClient already provides all control plane operations that MemoryControlPlaneClient offers:

Operation	MemoryControlPlaneClient	MemoryClient
create_memory	✅	✅ (+ create_or_get_memory, create_memory_and_wait)
get_memory	✅	✅
list_memories	✅	✅
update_memory	✅	✅
delete_memory	✅	✅ (+ delete_memory_and_wait)
add_strategy	✅ (generic)	✅ (+ 8 typed variants like add_semantic_strategy)
get_strategy	✅	✅
update_strategy	✅	✅
delete_strategy	✅	✅

2. MemoryClient Provides Additional Value

• Data plane operations: retrieve_memories(), create_event(), list_events(), fork_conversation(), etc.
• Response normalization: Handles API field name asymmetry automatically
• Type-safe strategy helpers: add_semantic_strategy(), add_summary_strategy(), etc.
• Convenience methods: create_memory_and_wait(), add_*_strategy_and_wait()

3. Maintenance Burden

Maintaining two clients with overlapping functionality increases:

• Bug fix duplication
• API change propagation effort
• Documentation complexity
• User confusion on which client to use

Deprecation Plan

v1.3.0 (Next Minor Release)

• Add DeprecationWarning to MemoryControlPlaneClient.__init__
• Update documentation to recommend MemoryClient
• Add migration guide

import warnings

class MemoryControlPlaneClient:
    def __init__(self, ...):
        warnings.warn(
            "MemoryControlPlaneClient is deprecated and will be removed in v1.4.0. "
            "Use MemoryClient instead, which provides all control plane operations "
            "plus data plane features. See migration guide: <link>",
            DeprecationWarning,
            stacklevel=2
        )
        # ... existing init code

v1.4.0 (Following Minor Release)

• Remove MemoryControlPlaneClient class
• Remove from __init__.py exports
• Remove associated tests

Code References

• MemoryControlPlaneClient: src/bedrock_agentcore/memory/controlplane.py
• MemoryClient: src/bedrock_agentcore/memory/client.py
• Module exports: src/bedrock_agentcore/memory/__init__.py
• MemoryControlPlaneClient tests: tests/bedrock_agentcore/memory/test_controlplane.py

Migration Guide (Draft)

Users currently using MemoryControlPlaneClient can migrate with minimal changes:

# Before
from bedrock_agentcore.memory import MemoryControlPlaneClient
client = MemoryControlPlaneClient(region_name="us-west-2")
client.create_memory(memory_id="my-memory", ...)

# After
from bedrock_agentcore.memory import MemoryClient
client = MemoryClient(region_name="us-west-2")
client.create_memory(memory_id="my-memory", ...)

Most method signatures are compatible. Key differences:

• MemoryClient uses gmcp_client internally for control plane ops
• Response field names are normalized for consistency
• Additional *_and_wait convenience methods available

Checklist

• Add deprecation warning in v1.3.0
• Update documentation
• Create migration guide
• Remove class in v1.4.0
• Update CHANGELOG